Copy page

Programmable Voice

Quickstart

This guide walks you through placing your first outbound call with the Calls API. The call speaks a short message, so you do not need a web server yet.

Before you begin

You need:

• Your Voice Account AccountSid and auth token. In the Signals console, open Developers, then Voice Account. Copy the AccountSid, then choose Show to see the auth token. Admins and engineers can view it at any time. Store it in a secrets manager.
• A phone number your Signals project owns, to use as the caller ID (From). See Numbers and routing.
• A Nigerian number to call (To). Your own phone works for testing.

Make your first call

The following examples create an outbound call that speaks a greeting. The call script is passed inline with Twiml, so Signals does not need to request a URL on your server.

Try it in the playground

The response

A successful request returns 201 with the new call resource. The call starts in the queued status, and direction is outbound-api because it was created through the API:

Code
{
  "sid": "CA5388f7a5e04d0ed71cac5cdf1ea17a53",
  "account_sid": "AC9ce1cd445308e3ec5080c6126288aa09",
  "api_version": "2010-04-01",
  "date_created": "Thu, 02 Jul 2026 12:00:00 +0000",
  "date_updated": "Thu, 02 Jul 2026 12:00:00 +0000",
  "to": "+2348031234567",
  "to_formatted": "+2348031234567",
  "from": "+2342013300100",
  "from_formatted": "+2342013300100",
  "direction": "outbound-api",
  "status": "queued",
  "start_time": null,
  "end_time": null,
  "duration": null,
  "price": null,
  "price_unit": null,
  "queue_time": "0",
  "phone_number_sid": "PN9992109eed74a671cdc4e192a934d43e",
  "parent_call_sid": null,
  "annotation": null,
  "answered_by": null,
  "caller_name": null,
  "forwarded_from": null,
  "group_sid": null,
  "trunk_sid": null,
  "subresource_uris": {
    "recordings": "/2010-04-01/Accounts/AC9ce1cd445308e3ec5080c6126288aa09/Calls/CA5388f7a5e04d0ed71cac5cdf1ea17a53/Recordings.json",
    "events": "/2010-04-01/Accounts/AC9ce1cd445308e3ec5080c6126288aa09/Calls/CA5388f7a5e04d0ed71cac5cdf1ea17a53/Events.json"
  },
  "uri": "/2010-04-01/Accounts/AC9ce1cd445308e3ec5080c6126288aa09/Calls/CA5388f7a5e04d0ed71cac5cdf1ea17a53.json"
}

Save the sid. It identifies this call in every later request.

Verify the result

Fetch the call resource to check its progress:

Code
curl -u "ACCOUNT_SID:AUTH_TOKEN" \
  "https://api.signals.pressone.africa/2010-04-01/Accounts/ACCOUNT_SID/Calls/CA5388f7a5e04d0ed71cac5cdf1ea17a53.json"

Try it in the playground

The status field moves through these values as the call progresses:

Status	Meaning
queued	The call was accepted and is waiting to be placed.
ringing	The destination phone is ringing.
in-progress	The call was answered and is connected.
completed	The call ended normally.

If the destination does not answer within the ring timeout (60 seconds by default, set with the Timeout field), the status becomes no-answer instead. A busy line ends as busy, and a call that could not be placed ends as failed. Poll the call resource, or set a status callback to be notified instead.

Troubleshooting

401 with code unauthenticated

The Authorization header is missing, is not HTTP Basic, or its username is not the AccountSid in the path. Send exactly one Basic credential whose username matches the path.

401 with a plain-text or 20003 body

The username matched, but the auth token is wrong or was rotated. Use the current token from the console.

404 with code voice_route_not_proxied

The AccountSid is unknown or the Voice Account is not active yet, or the path is not one the Calls API serves. Check the AccountSid in the console and the path spelling, including the .json suffix on Calls.json.

400 with code 21210

From is not a number your project owns. Use a number listed in the console under Numbers.

Next steps

• Receiving calls: answer inbound calls and build a menu.
• OneML overview: every verb available for scripting a call.
• Calls API reference: every endpoint, parameter and error.