Working with Calls

The Calls API is one of the most used features of SIPSIM. Learn how to retrieve call history, filter results, and access detailed call information.

Required Scopes

calls.read — Required to list and view calls

List Calls

Retrieve a list of calls within a time range:

cURL
Python

curl "https://app.sipsim.com/api/v2/calls?start_time=2024-01-01T00:00:00Z&end_time=2024-01-31T23:59:59Z" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

import requests
from datetime import datetime, timedelta

access_token = "YOUR_ACCESS_TOKEN"

# Get calls from the last 7 days
end_time = datetime.utcnow()
start_time = end_time - timedelta(days=7)

response = requests.get(
    "https://app.sipsim.com/api/v2/calls",
    headers={"Authorization": f"Bearer {access_token}"},
    params={
        "start_time": start_time.isoformat() + "Z",
        "end_time": end_time.isoformat() + "Z",
        "limit": 100
    }
)

data = response.json()
for call in data["data"]:
    print(f"{call['direction']} call: {call['caller_number']} -> {call['receiver_number']}")

Required Parameters

Parameter	Type	Description
`start_time`	string	ISO 8601 datetime for the beginning of the time range

Optional Parameters

Parameter	Type	Description
`end_time`	string	ISO 8601 datetime for the end of the range (defaults to now)
`employees`	string	Comma-separated list of employee IDs
`tags`	string	Comma-separated list of tag IDs
`call_types`	string	Comma-separated: `inbound`, `outgoing`, `missed`, `voicemail`
`search`	string	Search by phone number or caller name
`limit`	integer	Results per page (20-1000, default: 1000)
`page`	string	Pagination token for next page

Filtering Calls

By Call Type

Get only missed calls:

curl "https://app.sipsim.com/api/v2/calls?start_time=2024-01-01T00:00:00Z&call_types=missed" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Get inbound and outgoing calls (exclude missed and voicemail):

curl "https://app.sipsim.com/api/v2/calls?start_time=2024-01-01T00:00:00Z&call_types=inbound,outgoing" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

By Employee

Filter calls for specific employees:

curl "https://app.sipsim.com/api/v2/calls?start_time=2024-01-01T00:00:00Z&employees=123,456,789" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

By Tags

Get calls with specific tags:

curl "https://app.sipsim.com/api/v2/calls?start_time=2024-01-01T00:00:00Z&tags=10,20" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

By Phone Number

Search for calls involving a specific number:

curl "https://app.sipsim.com/api/v2/calls?start_time=2024-01-01T00:00:00Z&search=+33612345678" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Call Object

Each call in the response includes:

{
  "id": 12345,
  "call_type": "inbound",
  "sip_status": "answer",
  "caller_number": "+33612345678",
  "target_number": "+33698765432",
  "answered_phone_number": "+33698765432",
  "answered": true,
  "wait_duration_sec": 5,
  "duration_sec": 120,
  "play_record_link": "https://example.com/recordings/call_12345.mp3",
  "phone_id": 456,
  "answered_phone_id": 789,
  "registration_time": "2024-01-15T10:30:00Z",
  "start_time": "2024-01-15T10:30:05Z",
  "answered_time": "2024-01-15T10:30:10Z",
  "end_time": "2024-01-15T10:32:10Z",
  "tags": [
    {"id": 10, "name": "Important"}
  ]
}

Call Fields

Field	Type	Description
`id`	integer	Unique call identifier
`call_type`	string	`inbound`, `outbound`, `missed`, or `voicemail`
`sip_status`	string	SIP status: `answer`, `cancel`, `no_answer`, `busy`, `unavailable`, `other`
`caller_number`	string	Phone number of the caller (E.164 format)
`target_number`	string	Phone number that was called (E.164 format)
`answered_phone_number`	string	Phone number that answered the call (nullable)
`answered`	boolean	Whether the call was answered
`wait_duration_sec`	integer	Duration in seconds the call waited before being answered
`duration_sec`	integer	Total duration of the call in seconds
`play_record_link`	string	URL to the call recording (nullable)
`phone_id`	integer	ID of the phone associated with the call
`answered_phone_id`	integer	ID of the phone that answered (nullable)
`registration_time`	string	Time when the call was registered (ISO 8601)
`start_time`	string	Time when the call started (ISO 8601)
`answered_time`	string	Time when the call was answered (nullable, ISO 8601)
`end_time`	string	Time when the call ended (ISO 8601)
`tags`	array	Tags attached to this call (id and name)

Get a Single Call

Retrieve detailed information about a specific call:

curl "https://app.sipsim.com/api/v2/calls/12345" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Practical Examples

Daily Call Report

Generate a daily summary of calls:

import requests
from datetime import datetime, timedelta
from collections import Counter

access_token = "YOUR_ACCESS_TOKEN"

# Yesterday's calls
yesterday = datetime.utcnow().date() - timedelta(days=1)
start_time = datetime.combine(yesterday, datetime.min.time())
end_time = datetime.combine(yesterday, datetime.max.time())

response = requests.get(
    "https://app.sipsim.com/api/v2/calls",
    headers={"Authorization": f"Bearer {access_token}"},
    params={
        "start_time": start_time.isoformat() + "Z",
        "end_time": end_time.isoformat() + "Z",
        "limit": 1000
    }
)

calls = response.json()["data"]

# Analyze
call_types = Counter(c["call_type"] for c in calls)
total_duration = sum(c["duration_sec"] or 0 for c in calls)

print(f"=== Call Report for {yesterday} ===")
print(f"Total calls: {len(calls)}")
print(f"  Inbound: {call_types['inbound']}")
print(f"  Outbound: {call_types['outbound']}")
print(f"  Missed: {call_types['missed']}")
print(f"  Voicemail: {call_types['voicemail']}")
print(f"Total talk time: {total_duration // 60} minutes")

Find Long Calls

Find all calls longer than 30 minutes:

import requests

access_token = "YOUR_ACCESS_TOKEN"

response = requests.get(
    "https://app.sipsim.com/api/v2/calls",
    headers={"Authorization": f"Bearer {access_token}"},
    params={
        "start_time": "2024-01-01T00:00:00Z",
        "limit": 1000
    }
)

calls = response.json()["data"]
long_calls = [c for c in calls if (c["duration_sec"] or 0) > 1800]

print(f"Found {len(long_calls)} calls longer than 30 minutes:")
for call in long_calls:
    minutes = call["duration_sec"] // 60
    print(f"  {call['id']}: {minutes} min - {call['caller_number']} -> {call['target_number']}")

Export to CSV

Export calls to CSV for further analysis:

import requests
import csv

access_token = "YOUR_ACCESS_TOKEN"

response = requests.get(
    "https://app.sipsim.com/api/v2/calls",
    headers={"Authorization": f"Bearer {access_token}"},
    params={
        "start_time": "2024-01-01T00:00:00Z",
        "end_time": "2024-01-31T23:59:59Z",
        "limit": 1000
    }
)

calls = response.json()["data"]

with open("calls_export.csv", "w", newline="") as f:
    writer = csv.DictWriter(f, fieldnames=[
        "id", "call_type", "sip_status", "caller_number", 
        "target_number", "duration_sec", "start_time", "answered"
    ])
    writer.writeheader()
    for call in calls:
        writer.writerow({
            "id": call["id"],
            "call_type": call["call_type"],
            "sip_status": call["sip_status"],
            "caller_number": call["caller_number"],
            "target_number": call["target_number"],
            "duration_sec": call["duration_sec"],
            "start_time": call["start_time"],
            "answered": call["answered"]
        })

print(f"Exported {len(calls)} calls to calls_export.csv")

Next Steps

Click-to-Call — Initiate outbound calls
AI Features — Get transcriptions and summaries
Managing Tags — Organize calls with tags

Required Scopes​

List Calls​

Required Parameters​

Optional Parameters​

Filtering Calls​

By Call Type​

By Employee​

By Tags​

By Phone Number​

Call Object​

Call Fields​

Get a Single Call​

Practical Examples​

Daily Call Report​

Find Long Calls​

Export to CSV​

Next Steps​