Calls

Calls are the core resource for voice interactions. The API supports creating, retrieving, updating, and deleting calls, and accessing call metadata, state, and participants.

A Call resource represents a connection between a voice channel and Sinch.

Using this resource, customers can initiate a call, fetch information about a completed call, fetch a list of calls made to and from the Voice service, and redirect or end a call in progress.

A call always has a direction, either inbound or outbound. The direction of the call dictates when and how the call can be controlled.

An outbound call is created when a DIAL command is invoked. Outbound calls can be controlled by supplying SVAMLv2 commands when creating the call, via the responses to the call's webhooks, or by sending a PATCH request.

An inbound call is created when the service receives a call via one of the Sinch voice channels [Phone, In-App, SIP, Streams]. To handle incoming calls, a service webhook must be configured via the services API or the dashboard.

Operations

List calls made with Sinch Voice API

Request

List and filter calls made with Sinch

Security

BasicAuth or SinchOAuth2

Path

projectIdstring, (uuid)(Project ID)required

The ID of the project.

Example:5c5bf2b1-35ae-4825-ab89-457e07bb60e6

Query

serviceIdstring, (uuid)(Service ID)

The ID of the service.

Example:serviceId=6e124178-c29d-46a5-943c-5c2ae544aade

fromstring

Only include calls where from matches this origin. For inbound calls, this is the caller; for outbound calls, this is the calling party.

Example:from=+15551234567

tostring

Only include calls where to matches this destination. For inbound calls, this is the called party; for outbound calls, this is the callee/recipient.

Example:to=+15551234568

callTypestring(Call Type)

Only include calls of the specified type.

If omitted, calls of all types are included.

Enum Value	Description
PHONE	A call from or to the telephone network.
SIP	A call from or to a SIP endpoint.
STREAM	A call to a stream.
VOICE_RELAY	A call to voice relay service.

Example:callType=PHONE

startTimestring, (date-time)

Only include calls that started at or after startTime.

Use a more precise timestamp to narrow the results. For example:

2025-02-01 matches calls starting from 2025-02-01T00:00:00Z
2025-02-01T14:00:00Z matches calls starting from 14:00:00Z on 2025-02-01

Example:startTime=2025-02-01T14:00:00Z

endTimestring, (date-time)

Only include calls that ended before endTime (exclusive).

Use a more precise timestamp to narrow the results. For example:

2025-03-01 matches calls ending up to 2025-03-01T00:00:00Z
2025-03-01T14:00:00Z matches calls ending up to 14:00:00Z on 2025-03-01

Example:endTime=2025-03-01T14:00:00Z

callResultstring(Call Result)

Filter results to only include calls whose callResult matches the specified value.

If omitted, calls with any result are included.

Enum Value	Description
QUEUED	The call is queued for initiation. This is a transitional state.
INITIATED	The call is connecting but the recipient has not yet answered. This is a transitional state.
IN_PROGRESS	The call has been answered and is in progress. This is a transitional state.
COMPLETED	The call was answered and is ended. This is a final state.
REJECTED	The call was rejected by the recipient.
NO_ANSWER	The call was not answered by the recipient.
CANCEL	The call was cancelled.
BUSY	The call was not answered because the recipient was busy.
FAILED	The call could not be completed.

Example:callResult=IN_PROGRESS

callReasonstring(Call Reason)

Filter results to only include calls whose callReason matches the specified value.

If omitted, calls with any reason are included.

Enum Value	Description
OK	The call was completed successfully.
NOT_AVAILABLE	The callee was not available.
CALLER_HANGUP	The caller hung up the call.
CALLEE_HANGUP	The callee hung up the call.
MANAGER_HANGUP	The call was ended by the call manager.
DID_NOT_FOUND	The DID number was not found.
INVALID_SCRIPT	The SVAML script was invalid.
UNKNOWN_PRODUCT	The product associated with the call is unknown.
NO_MORE_ROUTES	There are no more routes to complete the call.
ERROR	An error occurred during the call.

Example:callReason=OK

pageSizeinteger, [ 1 .. 100 ]

Number of items to be returned on each page.

Default:20

pageinteger, >= 1

Page number (1-based)

Default:1

curl -i -X GET \
  -u '<username>:<password>' \
  'https://voice.api.sinch.com/v2/projects/{projectId}/calls'

Responses

A list of calls

Bodyapplication/json

callsArray of objects(Call Resource)required

Array of call resources

linksobject(Pagination Links)required

Pagination links for navigating through pages of results in a paginated list response.

Available link properties:

first - Absolute URI of the first page
last - Absolute URI of the last page
next - Absolute URI of the next page (omitted if this is the last page)
prev - Absolute URI of the previous page (omitted if this is the first page)
self - Absolute URI of the current page

metaobject(Pagination Metadata)required

Metadata about the paginated list response.

Response

{
  "calls": [
    { … },
    { … }
  ],
  "links": {
    "first": "https://voice.api.sinch.com/v2/projects/5c5bf2b1-35ae-4825-ab89-457e07bb60e6/calls?page=1&pageSize=20",
    "last": "https://voice.api.sinch.com/v2/projects/5c5bf2b1-35ae-4825-ab89-457e07bb60e6/calls?page=5&pageSize=20",
    "prev": "https://voice.api.sinch.com/v2/projects/5c5bf2b1-35ae-4825-ab89-457e07bb60e6/calls?page=1&pageSize=20",
    "self": "https://voice.api.sinch.com/v2/projects/5c5bf2b1-35ae-4825-ab89-457e07bb60e6/calls?page=2&pageSize=20",
    "next": "https://voice.api.sinch.com/v2/projects/5c5bf2b1-35ae-4825-ab89-457e07bb60e6/calls?page=3&pageSize=20"
  },
  "meta": {
    "totalCount": 100,
    "pageCount": 5
  }
}