# Phone call

Use the **phone call** delivery method to place a call that reads a one-time code aloud. The
user enters the code in your application, and your application reports it to the Verification
API. This method is useful when SMS is unavailable or for landline numbers.

Note

In API requests, the phone call delivery method is identified by the value `callout`.

---

## How it works

1. You start a verification with `delivery_method` set to `callout`, optionally choosing
   the announcement language.
2. The Verification API places a call to the destination and reads a newly generated numeric
   code aloud in the selected language. The code length is set on the OTP application.
3. The user enters the code they heard in your application.
4. Your application reports the `code` to the
   [report endpoint](../api-reference/report-verification.html#otp-verification-api-report).
5. If the code matches, the verification status becomes `verified`.

## Start a phone call verification

Set `delivery_method` to `callout`. Use the optional `callout` object to choose the
announcement language.

The following example uses HTTP Basic authentication to start a phone call verification:

http

```
POST /api/v1/verifications HTTP/1.1
Host: verification.didww.com
Content-Type: application/json
Accept: application/json
Authorization: Basic eW91cl9hcHBfa2V5OnlvdXJfYXBwX3NlY3JldA==

{
  "data": {
    "destination": "+4915112345678",
    "delivery_method": "callout",
    "callout": {
      "languages": ["de-DE"]
    }
  }
}
```

curl

```
curl -i -X POST https://verification.didww.com/api/v1/verifications -H "Accept: application/json" -H "Content-Type: application/json" --data-raw '{"data": {"callout": {"languages": ["de-DE"]}, "delivery_method": "callout", "destination": "+4915112345678"}}' --user your_app_key:your_app_secret
```

response

```
HTTP/1.1 201 Created
Content-Type: application/json

{
  "data": {
    "id": "2b3c4d5e-6f70-4b3c-9d0e-1f2a3b4c5d6e",
    "destination": "4915112345678",
    "delivery_method": "callout",
    "fee": "0.08",
    "status": "pending",
    "error_code": null,
    "error_detail": null,
    "expires_at": "2026-07-15T10:05:00.000Z",
    "callout": {
      "language": "de-DE",
      "code_length": 6
    }
  }
}
```

This response shows an approved start with `status` `pending`. A `201 Created` response
can also contain `status` `denied` when a request callback rejects the verification.
Always inspect `status` and `error_code`.

A `pending` status means the verification was accepted for delivery. It does not confirm
that the call was answered or the code was heard.

The response includes a `callout` object containing `language`, the language the
announcement is played in, and `code_length`, the number of digits in the code that is read
aloud, from 4 to 8. Use `code_length` to size the code input field. The code itself is read
aloud to the user and is never returned in the API response.

## Supported languages

Pass `callout.languages` as BCP 47 tags, most preferred first. The first supported tag
wins; if none of them is supported, the announcement is played in `en-US`.

Tags are matched **exactly**, so the region subtag is required: `pt` does not match
`pt-PT` and falls back to `en-US`. A tag that is not a well-formed BCP 47 tag is
rejected with [languages\_invalid](../api-reference/errors.html#otp-verification-api-errors) instead.

Read `callout.language` from the response to see which language was actually used.

The following language tags are supported:

| BCP 47 tag | Language |
| --- | --- |
| `af-ZA` | Afrikaans (South Africa) |
| `ar-AE` | Arabic (United Arab Emirates) |
| `ar-EG` | Arabic (Egypt) |
| `ar-SA` | Arabic (Saudi Arabia) |
| `bg-BG` | Bulgarian (Bulgaria) |
| `bs-BA` | Bosnian (Bosnia and Herzegovina) |
| `cs-CZ` | Czech (Czechia) |
| `da-DK` | Danish (Denmark) |
| `de-DE` | German (Germany) |
| `el-GR` | Greek (Greece) |
| `en-GB` | English (United Kingdom) |
| `en-US` | English (United States) |
| `es-419` | Spanish (Latin America) |
| `es-ES` | Spanish (Spain) |
| `et-EE` | Estonian (Estonia) |
| `fi-FI` | Finnish (Finland) |
| `fr-FR` | French (France) |
| `he-IL` | Hebrew (Israel) |
| `hi-IN` | Hindi (India) |
| `hr-HR` | Croatian (Croatia) |
| `hu-HU` | Hungarian (Hungary) |
| `id-ID` | Indonesian (Indonesia) |
| `is-IS` | Icelandic (Iceland) |
| `it-IT` | Italian (Italy) |
| `ja-JP` | Japanese (Japan) |
| `lt-LT` | Lithuanian (Lithuania) |
| `lv-LV` | Latvian (Latvia) |
| `mk-MK` | Macedonian (North Macedonia) |
| `ms-MY` | Malay (Malaysia) |
| `nb-NO` | Norwegian Bokmål (Norway) |
| `nl-NL` | Dutch (Netherlands) |
| `pl-PL` | Polish (Poland) |
| `pt-BR` | Portuguese (Brazil) |
| `pt-PT` | Portuguese (Portugal) |
| `ro-RO` | Romanian (Romania) |
| `sk-SK` | Slovak (Slovakia) |
| `sl-SI` | Slovenian (Slovenia) |
| `sr-RS` | Serbian (Serbia) |
| `sv-SE` | Swedish (Sweden) |
| `sw-KE` | Swahili (Kenya) |
| `th-TH` | Thai (Thailand) |
| `tl-PH` | Tagalog (Philippines) |
| `tr-CY` | Turkish (Cyprus) |
| `tr-TR` | Turkish (Turkey) |
| `uk-UA` | Ukrainian (Ukraine) |
| `ur-PK` | Urdu (Pakistan) |
| `vi-VN` | Vietnamese (Vietnam) |
| `zh-CN` | Chinese Simplified (China) |
| `zh-HK` | Chinese Traditional (Hong Kong) |

## Reporting the code

Submit the code the user heard. The `delivery_method` must be `callout`. The following
example reports a correct code and returns `status` `verified`:

http

```
PATCH /api/v1/verifications/2b3c4d5e-6f70-4b3c-9d0e-1f2a3b4c5d6e HTTP/1.1
Host: verification.didww.com
Content-Type: application/json
Accept: application/json
Authorization: Basic eW91cl9hcHBfa2V5OnlvdXJfYXBwX3NlY3JldA==

{
  "data": {
    "delivery_method": "callout",
    "code": "123456"
  }
}
```

curl

```
curl -i -X PATCH https://verification.didww.com/api/v1/verifications/2b3c4d5e-6f70-4b3c-9d0e-1f2a3b4c5d6e -H "Accept: application/json" -H "Content-Type: application/json" --data-raw '{"data": {"code": "123456", "delivery_method": "callout"}}' --user your_app_key:your_app_secret
```

response

```
HTTP/1.1 200 OK
Content-Type: application/json

{
  "data": {
    "id": "2b3c4d5e-6f70-4b3c-9d0e-1f2a3b4c5d6e",
    "destination": "4915112345678",
    "delivery_method": "callout",
    "fee": "0.08",
    "status": "verified",
    "error_code": null,
    "error_detail": null,
    "expires_at": "2026-07-15T10:05:00.000Z",
    "callout": {
      "language": "de-DE",
      "code_length": 6
    }
  }
}
```

The response above shows a successful report. The API returns `200 OK` with `status`
`verified` when the submitted code matches.

If the submitted code is incorrect, the API returns the following response:

```
HTTP/1.1 422 Unprocessable Content
Content-Type: application/json

{
  "errors": [
    {
      "code": "code_invalid",
      "detail": "code is invalid"
    }
  ]
}
```

After an incorrect report, the verification remains `pending`, and the user can submit
another code until the attempt limit is reached. After three unsuccessful reports, the
verification becomes `failed` with `error_code` `too_many_attempts`.

## Next steps

- [Start a verification](../api-reference/start-verification.html#otp-verification-api-start): Review all start-request and
  response fields.
- [Report a verification](../api-reference/report-verification.html#otp-verification-api-report): Review all report-request and
  response fields.

On this page