Create and initiate a new outbound voice call

Request

Create a new outbound call associated to the project's default service or to the service specified in the serviceId query parameter.

Security

BasicAuth or SinchOAuth2

Path

projectIdstring, (uuid)(Project ID)required

The ID of the project.

Query

serviceIdstring, (uuid)(Service ID)

The ID of the service.

Idempotency-Keystring, [ 16 .. 128 ] characters

Client-generated idempotency key to safely retry requests. The server uses this key to recognize retries of the same request. If a request with the same key is received within 10 minutes, the server returns the cached response from the original request. Using a random UUID (v4) is strongly recommended.

Bodyapplication/json

commandsArray of objects(SVAML Commands)required

An ordered list of SVAML v2 (Sinch Voice Application Markup Language) commands that describe a call flow. Commands are executed sequentially in the order they are defined.

Blocking vs. non-blocking: Some commands block execution until they complete (pause, webhook, menu, gotoMenu), while others return immediately and run in parallel (dial, messages, amd, answer, hangup, startRecording, stopRecording, bridgeCall, stopMessages). Each command's description specifies its behavior.

Nesting scope: Commands that appear inside event handlers (e.g., dial.events.onAnswer, messages.events.onFinish) form independent sequences and execute in their own context — they are not continuations of the parent sequence.

parametersArray of objects(Command Parameter Sets)

An array of parameter objects that define values for dynamic placeholders in commands. Each object represents a set of parameters for a single queued call.

Use these parameters to inject customer-defined values into your SVAML commands, enabling personalized call flows without modifying the base command structure.

batchOptionsobject(Batch Options)

Options for batch dialing

curl -i -X POST \
  -u '<username>:<password>' \
  'https://voice.api.sinch.com/v2/projects/{projectId}/calls?serviceId=6e124178-c29d-46a5-943c-5c2ae544aade' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: stringstringstri' \
  -d '{
    "commands": [
      {
        "command": "dial",
        "callName": "origin",
        "from": {
          "type": "PHONE",
          "phone": {
            "number": "+15551234567"
          }
        },
        "to": {
          "type": "PHONE",
          "phone": {
            "number": "+15559876543"
          }
        },
        "dialTimeoutDurationSeconds": 30,
        "maxCallDurationSeconds": 3600,
        "events": {
          "onAnswer": [
            {
              "command": "messages",
              "messages": [
                {
                  "type": "SAY",
                  "say": {
                    "text": "Hello, your call is now connected.",
                    "voiceName": "Emma"
                  }
                }
              ]
            }
          ],
          "onHangup": [
            {
              "command": "hangup"
            }
          ]
        }
      }
    ]
  }'

Responses

Call created

Bodyapplication/json

projectIdstring, (uuid)(Project ID)required

The Id of the project associated with the call.

serviceIdstring, (uuid)(Service ID)required

The ID of the service used.

sessionIdstring, (ulid)(Session ID)required

The ID of the session.

batchIdstring, (ulid)(Batch ID)

The ID of the batch.

Response

{
  "projectId": "5c5bf2b1-35ae-4825-ab89-457e07bb60e6",
  "serviceId": "6e124178-c29d-46a5-943c-5c2ae544aade",
  "sessionId": "01BX5ZZKBKACTAV9WEVGEMMVRB"
}

We'd love to hear from you!