Calls

Using the Calls endpoint, you can manage on-going calls or retrieve information about a call.

Update a call in progress

This method is used to manage ongoing, connected calls. This method uses SVAML in the request body to perform various tasks related to the call. For more information about SVAML, see the Callback API documentation.

This method can only be used for calls that originate from or terminate to PSTN or SIP networks.

SecurityBasic or Signed
Request
path Parameters
callId
required
string

The unique identifier of the call. This value is generated by the system.

Example: 4398599d1ba84ef3bde0a82dfb61abed
Request Body schema: application/json
Array of objects (svaml.instruction)

The collection of instructions that can perform various tasks during the call. You can include as many instructions as necessary.

object (svaml.action)

The action that will control the call. Each SVAML object can only include one action.

Responses
204

A success response, or an Error.

patch/calling/v1/calls/id/{callId}
Request samples
application/json
{
  • "instructions": [
    • {
      }
    ],
  • "action": {
    • "name": "hangup"
    }
}

Get information about a call

You can retrieve information about an ongoing or completed call using a call ID. You can find the call ID of an ongoing call by viewing the response object from a callout request. You can find the call ID of a completed call by looking at your call logs in your Sinch Dashboard.

Note: You can only use this method for calls that terminate to PSTN or SIP networks from an In-app call.

SecurityBasic or Signed
Request
path Parameters
callId
required
string

The unique identifier of the call. This value is generated by the system.

Example: 4398599d1ba84ef3bde0a82dfb61abed
Responses
200

A success response, or an Error.

Response Schema: application/json
destinationMxp (object) or destinationPstn (object) or destinationSip (object)
destinationMxp (object) or destinationPstn (object) or destinationSip (object)
domain
string

Must be pstn for PSTN.

Value Description
pstn

The Public Switched Telephone Network, or a normal phone call.

callId
string

The unique identifier of the call.

duration
integer

The duration of the call in seconds.

status
string

The status of the call. Either ONGOING or FINAL

Enum Value Description
ONGOING

Call status is ONGOING

FINAL

Call status is FINAL

result
string (callResult)

Contains the result of a call.

Enum Value Description
N/A

Not applicable

ANSWERED

The call was answered.

BUSY

The line called was busy.

NOANSWER

The line called failed to answer.

FAILED

The call failed.

reason
string

Contains the reason why a call ended.

Enum Value Description
N/A

Not available.

TIMEOUT

Timed out.

CALLERHANGUP

Caller hung up.

CALLEEHANGUP

Callee hung up.

BLOCKED

The call was blocked.

NOCREDITPARTNER

No credit available.

MANAGERHANGUP

The Sinch server ended the call.

CANCEL

Call was canceled.

GENERALERROR

A general error.

INVALIDSVAMLACTION

Call could not be completed due to invalid SVAML response.

timestamp
string <date-time>

The date and time of the call.

custom
string

A string that can be used to pass custom information related to the call.

object (price)
object (price)
get/calling/v1/calls/id/{callId}
Request samples 
Response samples 
application/json
{
  • "from": {
    • "type": "username",
    • "endpoint": "myUserName"
    },
  • "to": {
    • "type": "username",
    • "endpoint": "myUserName"
    },
  • "domain": "pstn",
  • "callId": "string",
  • "duration": 0,
  • "status": "ONGOING",
  • "result": "ANSWERED",
  • "reason": "N/A",
  • "timestamp": "2019-08-24T14:15:22Z",
  • "custom": "string",
  • "userRate": {
    • "currencyId": "string",
    • "amount": 0.1
    },
  • "debit": {
    • "currencyId": "string",
    • "amount": 0.1
    }
}
Manage Call with `callLeg`
This method is used to manage ongoing, connected calls. This method is only used when using the PlayFiles and Say instructions in the request body. This method uses SVAML in the request body to perform various tasks related to the call. For more information about SVAML, see the Callback API documentation.


Note: You can only use this method for calls that originate from or terminate to PSTN or SIP networks.


SecurityBasic or Signed 
Request 
path Parameters
callId
required
string
The unique identifier of the call. This value is generated by the system.


 
 Example:  4398599d1ba84ef3bde0a82dfb61abed
callLeg
required
string
Specifies which part of the call will be managed. This option is used only by the PlayFiles and Say instructions to indicate which channel the sound will be played on. Valid options are caller, callee or both. If not specified, the default value is caller.
The callLeg identifier is ignored for calls that are part of a conference and calls initiated using the Callout API.


 Enum Value Description
caller
The outgoing call line.


callee
The receiving call line.


both
Both lines.


 
 Example:  caller
Request Body schema: application/json
Array of objects (svaml.instruction) 
The collection of instructions that can perform various tasks during the call. You can include as many instructions as necessary.


 
object (svaml.action) 
The action that will control the call. Each SVAML object can only include one action.


 
Responses 
200
A success response, or an Error.


Response Schema: application/json
 Schema not provided 
patch/calling/v1/calls/id/{callId}/leg/{callLeg}
Request samples 
application/json
{
  • "instructions": [
    • {
      }
    ],
  • "action": {
    • "name": "hangup"
    }
}
Response samples 
application/json
{
  • "content": "200 Successful response"
}
SecurityPrivacyLegal & ComplianceCookie Statement
© 2025 Sinch. All rights reserved.