Skip to content
Voice/
API Reference
/
/
Get Numbers

Voice API | Sinch (1.0.1)

API Overview

This document provides a detailed user guide and reference documentation on the Sinch Voice REST API. For information on how to authenticate API requests, please check the Authentication page.

Contact Sinch support here: Support@sinch.com

Calling API

When using Sinch for voice calling, the Sinch dashboard works as a big telephony switch. The dashboard handles incoming phone calls (also known as incoming call “legs”), sets up outgoing phone calls (or outgoing call “legs”), and bridges the two. The incoming call leg may come in over a data connection (from a smartphone or web application using the Sinch SDKs) or through a local phone number (from the PSTN network). Similarly, the outgoing call leg can be over data (to another smartphone or web application using the Sinch SDKs) or the PSTN network.

For most calls, you can use the Sinch In-app Voice & Video SDKs on a smartphone or web client to establish calls without the need of additional integration. For more control or flexibility of the calls, you can use the Sinch REST APIs to manage the calls.

Controlling a call from your application is done by responding to callbacks from the Sinch platform and/or by calling REST APIs in the Sinch platform from your application. For more details on the callbacks triggered from the Sinch platform see the Callback API.

Example callout request for text-to-speech call

const fetch = require("node-fetch");

const resp = await fetch(`https://calling-use1.api.sinch.com/v1/callouts/`, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization:
      "Basic " + Buffer.from("<username>:<password>").toString("base64"),
  },
  body: JSON.stringify({
    method: "ttsCallout",
    ttsCallout: {
      cli: "14155552223333",
      destination: {
        type: "number",
        number: "+14045555000",
      },
      domain: "pstn",
      custom: "customData",
      locale: "en-US",
      prompts: "This is a phone call from Sinch",
    },
  }),
});

const data = await resp.json();
console.log(data);

These are the typical call scenarios that you can control with the Sinch Callback and Calling APIs:

API Quick Reference

The following sections give a brief overview of the Voice REST API methods.

Endpoints

The Calling API uses a variety of endpoints depending on where in the world you are located.

When using API methods concerning individual calls, you can define what regional endpoint you want to use for the call. The following regional endpoints are available:

EndpointDescription
https://calling.api.sinch.com/calling/v1Global - redirected by Sinch to the closest region
https://calling-euc1.api.sinch.com/calling/v1Europe
https://calling-use1.api.sinch.com/calling/v1North America
https://calling-sae1.api.sinch.com/calling/v1South America
https://calling-apse1.api.sinch.com/calling/v1South East Asia 1
https://calling-apse2.api.sinch.com/calling/v1South East Asia 2

For cases where the call is the result of an incoming PSTN, SIP or data call, the endpoint to use for managing that call is supplied in the ICE event. ICE callbacks will also provide region-specific URLs in the callResourceUrl property.

When using API methods for configuring or managing applications, where region doesn't matter, use the following global endpoint:

EndpointDescription
https://callingapi.sinch.com/calling/v1Global endpoint

Methods

The API is developed using the following REST style operations:

[GET] - Fetch / Query
[POST] - Create / New / Start
[PUT] - 'Full' Update / Alter / Modify
[PATCH] - 'Partially' Update / Alter / Modify
[DELETE] - Remove / Stop / Cancel

Errors

The API uses the HTTP status code to indicate failure and the body contains more information.

[Error]
  int - errorCode
  string - message

Example

HTTP Status Code: 401 (Unauthorized)
  {
    "errorCode":40102,
    "message":"Invalid Signature"
  }

Error Codes

An error code contains five digits. The first three digits are the same as the HTTP Status Code.

[BadRequest - 400]
  40001 - Parameter Validation

[Unauthorized - 401]
  40100 - Authorization Header
  40101 - Timestamp Header
  40102 - Invalid Signature

[InternalServerError - 500]
  50000 - Internal Server Error

[ServiceUnavailable - 503]
  50300 - Temporary Down

Callback API

To use callback events you need to assign a callback URL in the Sinch portal under your app settings.

EventHTTP VerbFunctionality
ICEPOSTIncoming Call Event callback
ACEPOSTAnswered Call Event callback
DiCEPOSTDisconnect Call Event callback
PIEPOSTPrompt Input Event callback
NotifyPOSTNotify Event callback

Phone to phone calls

Voice numbers can call phone numbers on the fixed or mobile phone network. You can rent and configure voice numbers from the Sinch dashboard by following these steps:

  1. Rent a Voice number from the Sinch Dashboard, under the Numbers tab.
  2. Assign the number to your application. Under the Apps tab, select your app and assign the number under the app Voice settings.
  3. Configure a callback URL under your app's Voice settings, where Sinch will send call-related events.

When a user calls your configured voice number, the Sinch platform will trigger an Incoming Call Event callback towards your callback URL. The destination number - where the call will be connected to - has to be specified in your response to the Incoming Call Event callback. Similarly to app to phone calls, the Sinch platform will trigger additional events for call control.

For more information please check the Callback API. The callback events that are used in phone to phone calls are the Incoming Call Event callback, the Answer Call Event callback and the Disconnect Call Event callback.

Text to speech calls

With the text-to-speech REST API, you can trigger a call to be placed to a fixed or mobile phone number and play a synthesized text message.

For more information please check the Callouts operation.

App to phone calls

Apps using the iOS, Android or Javascript SDK can call phone numbers on the fixed or mobile phone network. For additional call control, you can configure a callback URL under your app's voice settings in the Sinch dashboard, where Sinch will send call-related events. By capturing and responding to these events from your app, you can allow or deny calls to go through. Events will also be triggered when the calls are answered or disconnected.

For more information please check the Callback API. The callback events that are used in app to phone calls are the Incoming Call Event callback, the Answer Call Event callback, and the Disconnect Call Event callback.

App to App calls

Apps can call other apps using the iOS, Android or Javascript SDK. Both call legs are established over the data connection of the smartphone or computer (VoIP). For additional call control, you can specify a callback URL where Sinch will send call-related events. By capturing and responding to these events from your app you can allow, deny, and control the calls. You can configure the callback URL under your app's voice settings in the Sinch dashboard.

For more information please check the Callback API. The callback event that's used in app to app calls is the Incoming Call Event callback.

Conference calls

The Sinch dashboard supports a variety of different ways of initiating a conference call and connecting participants.

By using the Sinch Voice SDKs, you can allow your users to call in a conference from a mobile or web app. For more information please check the Voice SDKs documentation.

If you haven't specified a callback URL under your app settings for voice, the participants will be directly added to the conference that's uniquely identified by the conference ID specified in the SDK client method.

If you have specified a callback URL under your app settings for voice, an Incoming Call Event callback will be triggered towards your URL, containing information on the conference ID that the caller wants to connect to. By responding to this event you can allow or deny the connection to the conference, or even specify a different conference ID.

You can also allow users to dial in a conference by calling a fixed phone number. To do this, first follow the steps mentioned in Phone to phone calls to configure a number in your app and set a callback URL. Every time a user calls your configured number, an Incoming Call Event callback will be triggered towards your URL. By responding to this event with the ConnectConf action, you can connect the call to a conference.

For more information check the Incoming Call Event callback and the ConnectConf action.

By using the conference callout endpoint, you can trigger calls to fixed or mobile phones and connect them all to the same conference room.

The Voice API allows you to control an ongoing conference. There are several conference-control options available, such as muting/unmuting participants or kicking out a participant or all participants from the conference when the conference ends.

The Voice API also allows recording of conference calls. For more information on how to record a conference, please check the ConnectConf action in the SVAML Actions page.

Important!

Conference rooms have regional scope. If you want to connect multiple participants from different regions (Continents) on the same conference, you must “force” all members to be on the same region.

This can be done by selecting the same Sinch Voice API regional endpoints for Callout requests and/or the Sinch In-App regional endpoint/hostname to be used on your Mobile or Web Apps.

Download OpenAPI description
voice.json
voice.yaml
Overview
URL

https://www.sinch.com

Support

support@sinch.com

License

MIT

Languages
Servers
redirected by Sinch to an appropriate region

https://calling.api.sinch.com/

United States

https://calling-use1.api.sinch.com/

Europe

https://calling-euc1.api.sinch.com/

South America

https://calling-sae1.api.sinch.com/

Southeast Asia 1

https://calling-apse1.api.sinch.com/

Southeast Asia 2

https://calling-apse2.api.sinch.com/

Callouts

A callout is a call made to a phone number or app using the API.

Operations

Calls

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

Operations

Conferences

Using the Conferences endpoint, you can perform tasks like retrieving information about an on-going conference, muting or unmuting participants, or removing participants from a conference.

Operations

Applications

You can use the API to manage features of applications in your project.

Operations

Get Numbers

Request

Get information about your numbers. It returns a list of numbers that you own, as well as their capability (voice or SMS). For the ones that are assigned to an app, it returns the application key of the app.

Security
Basic or Signed
curl -i -X GET \
  -u <username>:<password> \
  https://callingapi.sinch.com/v1/configuration/numbers

Responses

A success response, or an Error.

Bodyapplication/json
numbersArray of objects

The object type. Will always be list of numbers, associated application keys and capabilities

Response
application/json
{
  "numbers": [
    { … },
    { … },
    { … }
  ]
}

Update Numbers

Request

Assign a number or a list of numbers to an application.

Security
Basic or Signed
Bodyapplication/json
numbersArray of strings[ 1 .. 100 ] items

The phone number or list of numbers in E.164 format.

Example: ["+14151112223333"]
applicationkeystring

indicates the application where the number(s) will be assigned. If empty, the application key that is used to sign the request will be used.

Example: "11983f76-12c8-1111-9515-4785c7b67ca8"
capabilitystring

Valid values are voice and sms

Enum ValueDescription
voice

Able to make Voice calls.

sms

Able to send SMS messages.

Example: "voice"
curl -i -X POST \
  -u <username>:<password> \
  https://callingapi.sinch.com/v1/configuration/numbers \
  -H 'Content-Type: application/json' \
  -d '{
    "numbers": [
      "+14151112223333"
    ],
    "applicationkey": "11983f76-12c8-1111-9515-4785c7b67ca8",
    "capability": "voice"
  }'

Responses

A success response, or an Error.

Un-assign number

Request

Un-assign a number from an application.

Security
Basic or Signed
Bodyapplication/json
numberstring

The phone number in E.164 format (https://community.sinch.com/t5/Glossary/E-164/ta-p/7537)

Example: "+14151112223333"
applicationkeystring

Indicates the application where the number(s) was assigned. If empty, the application key that is used to sign the request will be used.

Example: "11983f76-12c8-1111-9515-4785c7b67ca8"
capabilitystring

Valid values are voice and sms

Enum ValueDescription
voice

Able to make Voice calls.

sms

Able to send SMS messages.

Example: "voice"
curl -i -X DELETE \
  -u <username>:<password> \
  https://callingapi.sinch.com/v1/configuration/numbers \
  -H 'Content-Type: application/json' \
  -d '{
    "numbers": "+14151112223333",
    "applicationkey": "11983f76-12c8-1111-9515-4785c7b67ca8",
    "capability": "voice"
  }'

Responses

A success response, or an Error.

Get Callback URLs

Request

Returns any callback URLs configured for the specified application.

Security
Basic or Signed
Path
applicationkeystringrequired

The unique identifying key of the application.

Example: 94983f76-1161-6655-9515-4785c7b67dd8
curl -i -X GET \
  -u <username>:<password> \
  https://callingapi.sinch.com/v1/configuration/callbacks/applications/94983f76-1161-6655-9515-4785c7b67dd8

Responses

A success response, or an Error.

Bodyapplication/json
urlobject

Contains primary and or fallback callback URLs

Response
application/json
{
  "url": {
    "primary": "http://primarycallback.com",
    "fallback": "http://fallbackcallback.com"
  }
}

Update Callbacks

Request

Update the configured callback URLs for the specified application.

Security
Basic or Signed
Path
applicationkeystringrequired

The unique identifying key of the application.

Example: 94983f76-1161-6655-9515-4785c7b67dd8
Bodyapplication/json
urlobject

Contains primary and or fallback callback URLs

curl -i -X POST \
  -u <username>:<password> \
  https://callingapi.sinch.com/v1/configuration/callbacks/applications/94983f76-1161-6655-9515-4785c7b67dd8 \
  -H 'Content-Type: application/json' \
  -d '{
    "url": {
      "primary": "http://primarycallback.com",
      "fallback": "http://fallbackcallback.com"
    }
  }'

Responses

A success response, or an Error.

Query numberDeprecated

Request

Returns information about the requested number.

Security
Basic or Signed
Path
numberstringrequired

The phone number you want to query.

Example: +46730170101
curl -i -X GET \
  -u <username>:<password> \
  'https://callingapi.sinch.com/v1/calling/query/number/+46730170101'

Responses

A success response, or an Error.

Bodyapplication/json
numberobject

The number item object.

Response
application/json
{
  "method": "numberItem",
  "numberItem": {
    "countryId": "SE",
    "numberType": "Mobile",
    "normalizedNumber": "+14151112223333",
    "restricted": false,
    "rate": { … }
  }
}

Callbacks

Controlling a call from your application backend is done by responding to callbacks from the Sinch platform and/or by calling REST APIs in the Sinch platform from your application's backend.

Read more about how callbacks work here.

Webhooks