> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mycpaas.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Make and manage voice calls with mycpaas

> Initiate outbound calls, control call flow with LaML XML, track status with webhooks, and filter call records using the mycpaas Voice API.

The mycpaas Voice API lets you initiate outbound phone calls programmatically and control exactly what happens during each call using LaML XML documents. You can speak text, play audio, collect input, and receive real-time status updates via webhooks—all from a single API endpoint.

## Make an outbound call

Send a `POST` request to the Calls resource to initiate an outbound call. mycpaas dials the destination number, then fetches the LaML XML document at the URL you provide to determine how the call is handled.

```
POST /api/laml/2010-04-01/Accounts/{AccountSid}/Calls.json
```

### Required parameters

<ParamField path="AccountSid" type="string" required>
  Your account SID. Found in the mycpaas dashboard. Included in the URL path.
</ParamField>

<ParamField body="To" type="string" required>
  The destination phone number to dial, in E.164 format (e.g. `+491234567890`).
</ParamField>

<ParamField body="From" type="string" required>
  Your mycpaas phone number to use as the caller ID, in E.164 format (e.g. `+491098765432`). The number must be active in your account.
</ParamField>

<ParamField body="Url" type="string" required>
  A publicly accessible URL that returns a LaML XML document. mycpaas fetches this URL once the call connects and follows the instructions in the document to control the call.
</ParamField>

### Optional parameters

<ParamField body="StatusCallback" type="string">
  A URL that mycpaas sends a webhook `POST` request to when call status changes. Use this to track call progress in your application.
</ParamField>

<ParamField body="StatusCallbackEvent" type="string">
  A space-separated list of call events that trigger a webhook to `StatusCallback`. Defaults to `completed` if omitted. See the tip below for all available values.
</ParamField>

<Tip>
  `StatusCallbackEvent` accepts any combination of these values: `initiated`, `ringing`, `answered`, `completed`. For example, to receive a webhook at every stage of the call lifecycle, set `StatusCallbackEvent` to `"initiated ringing answered completed"`.
</Tip>

### Example request

```bash theme={null}
curl -X POST https://developer.mycpaas.io/api/laml/2010-04-01/Accounts/ACxxx/Calls.json \
  -u ACxxx:AUTH_TOKEN \
  -d "To=+491234567890" \
  -d "From=+491098765432" \
  -d "Url=https://example.com/voice.xml" \
  -d "StatusCallback=https://example.com/call-status" \
  -d "StatusCallbackEvent=initiated ringing answered completed"
```

## Control the call with LaML XML

The `Url` parameter points to a LaML XML document that mycpaas fetches when the call connects. The document tells mycpaas what to do during the call—speak text, play audio, collect digits, and more.

Your server must respond with a `Content-Type` of `application/xml` or `text/xml`.

### Speak text with `<Say>`

Use `<Say>` to convert text to speech and play it to the caller.

```xml theme={null}
<?xml version="1.0" encoding="UTF-8"?>
<Response>
  <Say voice="alice" language="en-US">Hello! Thanks for calling mycpaas. Please hold while we connect you.</Say>
</Response>
```

### Play an audio file with `<Play>`

Use `<Play>` to stream an audio file (MP3 or WAV) to the caller instead of synthesized speech.

```xml theme={null}
<?xml version="1.0" encoding="UTF-8"?>
<Response>
  <Play>https://example.com/audio/welcome.mp3</Play>
</Response>
```

## Response fields

A successful `POST` returns HTTP `201` with a JSON object representing the created call.

<ResponseField name="sid" type="string">
  The unique identifier for this call (e.g. `CAxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx`). Use this SID to look up or update the call later.
</ResponseField>

<ResponseField name="to" type="string">
  The destination phone number that was dialed.
</ResponseField>

<ResponseField name="from" type="string">
  The caller ID phone number used for this call.
</ResponseField>

<ResponseField name="status" type="string">
  The current status of the call. See the table below for all possible values.
</ResponseField>

<ResponseField name="direction" type="string">
  Indicates how the call was initiated. `outbound-api` for calls you create via the API; `inbound` for calls made to your mycpaas number.
</ResponseField>

### Example response

```json theme={null}
{
  "sid": "CA1234567890abcdef1234567890abcdef",
  "to": "+491234567890",
  "from": "+491098765432",
  "status": "queued",
  "direction": "outbound-api",
  "date_created": "2026-04-19T10:00:00Z",
  "uri": "/api/laml/2010-04-01/Accounts/ACxxx/Calls/CA1234567890abcdef1234567890abcdef.json"
}
```

### Call status values

| Status        | Description                                           |
| ------------- | ----------------------------------------------------- |
| `queued`      | The call is waiting to be dialed.                     |
| `initiated`   | mycpaas has started dialing the destination number.   |
| `ringing`     | The destination phone is ringing.                     |
| `in-progress` | The call has been answered and is active.             |
| `completed`   | The call ended normally.                              |
| `failed`      | The call could not be completed due to an error.      |
| `busy`        | The destination number was busy.                      |
| `no-answer`   | The call was not answered before the timeout elapsed. |

## List and filter calls

Use `GET` on the Calls resource to retrieve a list of calls associated with your account. You can filter by status, direction, phone number, and paginate through large result sets.

```
GET /api/laml/2010-04-01/Accounts/{AccountSid}/Calls.json
```

### Query parameters

| Parameter  | Type    | Default | Description                                                                  |
| ---------- | ------- | ------- | ---------------------------------------------------------------------------- |
| `Page`     | integer | `0`     | Page number to retrieve (zero-indexed).                                      |
| `PageSize` | integer | `50`    | Number of records per page.                                                  |
| `To`       | string  | —       | Filter calls by destination phone number (E.164 format).                     |
| `From`     | string  | —       | Filter calls by originating phone number (E.164 format).                     |
| `Status`   | string  | —       | Filter calls by status. See [call status values](#call-status-values) above. |

### Example: list recent calls

```bash theme={null}
curl -X GET "https://developer.mycpaas.io/api/laml/2010-04-01/Accounts/ACxxx/Calls.json?PageSize=10&Status=completed" \
  -u ACxxx:AUTH_TOKEN
```

### Example: filter calls to a specific number

```bash theme={null}
curl -X GET "https://developer.mycpaas.io/api/laml/2010-04-01/Accounts/ACxxx/Calls.json?To=%2B491234567890&Page=0&PageSize=25" \
  -u ACxxx:AUTH_TOKEN
```

### Example response

```json theme={null}
{
  "page": 0,
  "page_size": 10,
  "calls": [
    {
      "sid": "CA1234567890abcdef1234567890abcdef",
      "to": "+491234567890",
      "from": "+491098765432",
      "status": "completed",
      "direction": "outbound-api",
      "date_created": "2026-04-19T10:00:00Z",
      "uri": "/api/laml/2010-04-01/Accounts/ACxxx/Calls/CA1234567890abcdef1234567890abcdef.json"
    }
  ]
}
```