Sinch Voice API v2

openapi: 3.2.0
info:
  version: 2.0.59
  title: Voice API v2
  x-sinch-standards-version: standards-2026-03-31
  summary: Make and receive voice calls with Sinch's RESTful Voice API interface.
  description: "# Core Concepts\n\nThe Voice API enables embedding voice calling into applications for virtually limitless use cases. From **number masking** for privacy, automated **appointment reminders**, and **outreach campaigns** with answering machine detection, to **bridging calls** between PSTN and SIP endpoints, the API offers the flexibility and control needed for modern communications.\n\n## Call Model\n\n{% table %}\n\n- Concept \n- Description\n\n---\n\n- **Session**\n- A session initiates as soon as the first call is created. It serves as a container for all related calls and their connections, maintaining context and state throughout the interaction. The session persists until all associated calls are terminated.\n\n---\n\n- **Call**\n- A single participant's connection in a session (e.g., caller or callee).\n    - **Inbound Call:** A call initiated from an external source (PSTN, SIP, etc.) into the service.\n    - **Outbound Call:** A call initiated by the service to an external destination.\n\n---\n\n- **Bridge**\n- A mechanism to connect one or more calls, so that participants can communicate with each other.\n    ![session bridge chart](/images/voicev2/voicev2-session-chart.png)\n\n{% /table %}\n\n### Initiating Calls\n\nThere are a few ways to create a call:\n\n1. **Inbound Calls:** Triggered by incoming traffic from PSTN, SIP, or other sources.\n2. **Outbound Calls (via Dial):** Initiated from within an existing call session using the `dial` command.\n3. **Outbound Calls (via API):** Created directly by sending an API request to the Voice API.\n4. **Call Queuing:** Calls can be queued and processed based on parameters such as priority, time, or custom logic.\n\n### Call Pacing (Batch)\n\nThe new Voice API v2 supports Call pacing via batch calling to efficiently manage high volumes of outbound calls. This is especially useful for scenarios like appointment reminders, notifications, or campaigns where customers need to reach multiple recipients in a controlled and scalable way.\n\n#### How To Initiate Batch Calls\n\nTo initiate several calls in a batch, send a POST request to the `/v2/projects/{projectId}/batches` endpoint. The request body contains a SVAML payload describing the call flow and a list of parameters for each call in the batch. The API queues and triggers calls according to the provided configuration, such as maximum calls per second (`maxCps`) and time-to-live (`ttlSeconds`).\n\n```json\n{\n  \"commands\": [\n    {\n      \"command\": \"dial\",\n      \"callName\": \"batch-notification\",\n      \"from\": { \n        \"type\": \"PHONE\",\n        \"phone\": { \"number\": \"@from\" } \n      },\n      \"to\": { \n        \"type\": \"PHONE\",\n        \"phone\": { \"number\": \"@to\" } \n      },\n      \"events\": {\n        \"onAnswer\": [\n          {\n            \"command\": \"messages\",\n            \"messages\": [\n              {\n                \"type\": \"SAY\",\n                \"say\": {\n                  \"text\": \"Hello @name, you have an appointment tomorrow at 10 AM.\",\n                  \"voiceName\": \"Emma_3\"\n                }\n              }\n            ]\n          }\n        ]\n      }\n    }\n  ],\n  \"parameters\": [\n    { \"from\": \"+46712345678\", \"to\": \"+46787654321\", \"name\": \"Alice\" },\n    { \"from\": \"+46712345678\", \"to\": \"+46781234567\", \"name\": \"Bob\" }\n  ],\n  \"batchOptions\": {\n    \"maxCps\": 10,\n    \"ttlSeconds\": 60\n  }\n}\n```\n\n- **commands:** SVAML commands describing the call flow for each call in the batch. Parameter placeholders start with `@` and can be used as variables for each call. They can be used alone as in `@from` or in combination with text in a say message (e.g., `Hello @name, your appointment is at @time`).\n- **parameters:** An array of objects, each specifying the values for the placeholders in the commands. Each object represents a call to be queued and triggered.\n- **batchOptions:** Controls how the batch is processed:\n  - `maxCps`: Maximum number of calls per second to be initiated.\n  - `ttlSeconds`: Time-to-live for the batch in seconds; calls not initiated within this time window will be skipped.\n\nThe API responds with metadata for the batch operation:\n\n- **batchId:** The batchId identifies the entire batch operation, allowing batch state and summaries to be queried, or the batch to be managed as a whole (e.g., cancel unprocessed calls).\n- **Other properties:** The response also includes the project and service the batch belongs to.\n\nEach call in the batch is assigned a unique sessionId, which can be used to track the state and progress of individual calls. The session identifiers are retrieved via the [GET] `/v2/projects/{projectId}/batches/{batchId}/details` endpoint.\n\n\n#### How Calls Are Triggered\n\nWhen a batch request is submitted:\n1. The API validates the SVAML commands and parameters.\n2. Calls are queued and triggered according to `maxCps` and `ttlSeconds` settings.\n3. Each call is processed independently, using the provided parameters to personalize the call flow.\n4. The API tracks the state of each call (e.g., `QUEUED`, `INITIATED`, `IN_PROGRESS`, `COMPLETED`).\n5. Batch progress can be monitored and summaries can be retrieved via the [GET] `/v2/projects/{projectId}/batches/{batchId}` endpoint.\n\n## Call Lifecycle\n\nA call progresses through several states from creation to completion.\n\n**Call States**\n\n{% table %}\n\n- State\n- Description\n\n---\n\n- `QUEUED` \n- Call is waiting to be processed.\n\n---\n\n- `INITIATED`\n- Call setup is in progress (ringing).\n\n---\n\n- `IN_PROGRESS`\n- Call is answered and active.\n\n---\n\n- `COMPLETED`\n- Call ended normally.\n\n---\n\n- `REJECTED`\n- Recipient rejected the call.\n\n---\n\n- `NO_ANSWER`\n- Recipient did not answer.\n\n---\n\n- `CANCEL`\n- Call was cancelled before being answered.\n\n---\n\n- `BUSY`\n- Recipient was busy.\n\n---\n\n- `FAILED`\n- Call could not be set up.\n\n{% /table %}\n\n**Call Transitions**\n\n![transition states flowchart](/images/voicev2/voicev2-transition-states.png)\n\nThis diagram shows how a call moves between states. Typically, most calls start at `QUEUED`, progress to `INITIATED`, and either get answered (`IN_PROGRESS`) or end in a final state (`COMPLETED`, `NO_ANSWER`, etc.).\n\n## Handling Events with Webhooks\n\nWhen a specific event occurs (for example, a call is answered), the Voice API v2 sends an HTTP request (usually POST) to the webhook URL configured in service settings. The request contains details about the event, such as call identifiers and timestamps. The application can then respond with [SVAML commands](/docs/voice-2.0/api-reference/svaml) to control the ongoing call or perform other actions.\n\n### Typical Request-Response Cycle\n\n1. An event (e.g., call.answered) occurs in the Voice API.\n2. The API sends a POST request to the configured webhook endpoint with event details.\n3. The server processes the event and responds with SVAML commands (e.g., play a message, gather input).\n4. The API executes the commands and updates the call state.\n\n```mermaid\nsequenceDiagram\n  participant VoiceAPI as Voice API\n  participant Backend as Application Backend\n  VoiceAPI ->> Backend: POST webhook (event details)\n  Backend ->> VoiceAPI: SVAML commands (response)\n  VoiceAPI ->> Backend: Further webhooks (if needed)\n  Backend ->> VoiceAPI: Additional SVAML commands\n```\n\nWebhook endpoints must respond within 5 seconds. If the endpoint fails or times out and a `fallbackUrl` is configured, the request is re-sent to the fallback URL. See *Timeouts and failover* in the **Webhooks** section for the algorithm and its effect on delivery guarantees.\n\n### Webhooks vs. Events\n\n- **Webhooks:** External HTTP notifications sent to the application when specific events occur.\n- **Events:** Internal API notifications about call state changes; can be exposed via webhooks for external handling or internally by predefining event handlers in SVAML commands.\n\n### Event Naming Convention\n\nEvents are named using the pattern `resource.command.event`.\n\nFor example:\n- `call.answered`: Indicates that a call was answered.\n- `call.amd.machine`: Indicates that the Answering Machine Detection (AMD) on a call detected a machine.\n\nThis convention helps clearly identify the resource, the command involved, and the specific event that occurred.\n\n#### Common Webhook Events\n\n- `call.incoming`: Triggered when a call is received from PSTN, SIP, etc.\n- `call.answered`: Triggered when a call is answered.\n- `call.hangup`: Triggered when a call is hung up.\n\n### Precedence Rules\n\nWhen handling events in call flows, the Voice API applies the following precedence rules to determine which SVAML commands are executed:\n\n- **Command-Level Event Handlers:**  \n  If an event handler (e.g., `on_answer`, `on_machine`) is defined directly within a SVAML command, the commands specified in that handler are executed first for that event.\n\n- **Service Configuration Fallback:**  \n  If the event handler is not defined in the SVAML command, the API falls back to the event handler defined in the service configuration. This allows default behaviors for events to be set at the service level.\n\n- **Execution Order:**  \n  - Command-level event handlers always take priority over service-level handlers.\n  - If neither is defined, the event is ignored and no commands are executed for that event.\n\n**Best Practice:**  \nDefine event handlers in SVAML commands for custom, per-call logic. Use service configuration event handlers for default or global behaviors across all calls.\n\n\n### Webhook Request Example\n\nWhen a call is answered, the API sends a POST request to the configured webhook endpoint that includes the event type and the current call details.\n\nThe webhook endpoint should return a valid SVAML payload specifying which commands to execute on the call. For example, the response below synthesizes a welcome message and then ends the call.\n\n```json\n{\n  \"commands\": [\n    {\n      \"command\": \"messages\",\n      \"messages\": [\n        {\n          \"type\": \"SAY\",\n          \"say\": {\n            \"text\": \"Welcome to our service!\",\n            \"voiceName\": \"Emma_3\"\n          }\n        }\n      ],\n      \"events\": {\n        \"onFinish\": [\n          {\n            \"command\": \"hangup\"\n          }\n        ]\n      }\n    }\n  ]\n}\n```\n\n### Regions\n\nThe following table displays the servers available for each region.\n\n| Region | Server |\n| ------ | ------ |\n| Global endpoint - Redirected by Sinch to the closest region. | `https://voice.api.sinch.com` |\n| North America 1 - East | `https://us1.voice.api.sinch.com` |\n| South America 1 - East | `https://br1.voice.api.sinch.com` |\n| Europe 1 - Central | `https://eu1.voice.api.sinch.com` |\n| Asia Pacific 1 - Southeast | `https://sg1.voice.api.sinch.com` |\n| Australia & Oceania 1 - Southeast | `https://au1.voice.api.sinch.com` |\n\n### Best Practices\n\n- **Respond Quickly:** Webhook requests should be processed and responded to as quickly as possible to avoid call delays.\n- **Idempotency:** A failed request is re-sent to the fallback URL, so the same event can arrive more than once. Make the handler idempotent and deduplicate on the `ce-id` and `ce-source` headers — see *Timeouts and failover* in the **Webhooks** section.\n- **Logging:** Log incoming webhook requests and responses for troubleshooting and auditing.\n- **Validation:** Validate incoming requests to ensure they are from the Voice API (see Security below).\n\n### Security\n\nTo safeguard a webhook endpoint, verify that incoming requests are genuinely sent by the Voice API and have not been altered in transit. This prevents unauthorized access and mitigates risks such as man-in-the-middle attacks.\n\n1. Each service has an identifier and a secret.\n2. When a webhook arrives, use the secret to compute a signature over the canonical request string.\n3. Compare the computed signature to the one in the request authorization header.\n4. Only process the webhook if the signatures match.\n\nFor the exact `Authorization` header format, the canonical string that is signed, the signature algorithm and a worked example, see *Request signing* on the **Call webhook** operation in the **Webhooks** section.\n\nAccess to the webhook endpoint may also be restricted by IP address, and HTTPS can be used to encrypt traffic.\n"
  contact:
    name: Sinch Support
    url: https://sinch.com/help-center/
    email: support@sinch.com
  license:
    name: Sinch License
    url: https://www.sinch.com/legal/
  termsOfService: https://www.sinch.com/terms-of-service/
servers:
- url: https://voice.api.sinch.com
  description: Endpoint which enables consuming the Voice API globally - Redirected by Sinch to the closest region.
- url: https://us1.voice.api.sinch.com
  description: North America 1 - East
- url: https://br1.voice.api.sinch.com
  description: South America 1 - East
- url: https://eu1.voice.api.sinch.com
  description: Europe 1 - Central
- url: https://sg1.voice.api.sinch.com
  description: Asia Pacific 1 - Southeast
- url: https://au1.voice.api.sinch.com
  description: Australia & Oceania 1 - Southeast
security:
- BasicAuth: []
- SinchOAuth2: []
x-tagGroups:
- name: Calls and Call Management
  tags:
  - Calls
  - Sessions
  - Batches
- name: Event-Driven Call Control
  tags:
  - Webhooks
- name: Configuration
  tags:
  - Services
- name: Controlling Calls
  tags:
  - Payloads
tags:
- name: Services
  description: 'Services represent sets of configuration values and groupings for managing calls, such as service profiles, routing rules, and project settings. Services can be created, updated, and deleted via the API to organize call flows and endpoints.


    Service is the way you can manage your voice calls. Each service has its own configuration, including webhook URLs, default caller IDs, and other settings that control how calls are handled.


    ### Default Services

    When a new project is created a default service is automatically generated under this project. A default cannot be deleted directly, in order to delete a default service you must first promote another service to be the default one.


    When performing some Voice API operations, you may choose not to specify a serviceId, in which case the default service will be used. If you have multiple services, you can specify which one to use by providing its serviceId in the request.


    **If your account was created before the release of the voice API v2**, you may not have a service created under your projects. In this case, you must create a new one and set it as the default before you can use the programmable voice product within this project. You can do this via the API or the Dashboard.


    This can be useful if customers want to point a group of numbers to a particular incoming call URL, or want to record all calls for one voice service but not for the other.


    ### Dashboard

    Voice services and their settings can be managed via the [Dashboard](https://dashboard.sinch.com/voice-v2/services).'
- name: Batches
  description: "A batch represents a group of call sessions initiated together as a single operation. \n\nBatches are useful for scenarios like outbound campaigns, notifications, or any use case requiring multiple calls to be placed concurrently with controlled pacing.\n\n### Key Features\n- **Rate limiting**: Control the maximum calls per second (CPS) to manage load and comply with carrier requirements\n- **TTL (Time-to-Live)**: Set a maximum time window for initiating queued calls\n- **Monitoring**: Track batch execution state including completed, failed, in-progress, and queued calls\n- **Cancellation**: Stop processing queued calls while allowing in-progress calls to complete"
- name: Calls
  description: '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](/docs/voice-2.0/api-reference/voice/services/), 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](/docs/voice-2.0/api-reference/svaml) 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](/docs/voice-2.0/api-reference/voice/services) or the [dashboard](https://dashboard.sinch.com/voice).'
- name: Sessions
  description: A session represents a single interaction between a user and the Sinch Voice API. Sessions can be used to track the state of a call, including its duration, participants, and any associated metadata.
- name: Payloads
  description: 'SVAML (Sinch Voice API Markup Language) is a JSON-based markup language used to define call flows and control the behavior of voice calls in the Sinch Voice API. It allows developers to specify commands that dictate how calls are handled, including dialing, playing messages, gathering input, and more.


    SVAML is used in various contexts within the Voice API, including:

    - **Call Creation**: When initiating outbound calls via the API.

    - **Webhooks**: When responding to call events with commands to control the ongoing call flow.

    - **Batch Calls**: When defining call flows for multiple calls in a batch operation.'


# --- truncated at 32 KB (306 KB total) ---
# Full source: https://artifacts.apis.io/sinch/openapi/sinch-voice-v2-api-openapi.yml