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.

  3. The user enters the code they heard in your application.

  4. Your application reports the code to the report endpoint.

  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:02:00.000Z",
    "callout": {
      "language": "de-DE"
    }
  }
}

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. 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 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:02:00.000Z",
    "callout": {
      "language": "de-DE"
    }
  }
}

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#