SMS#

Use the SMS delivery method to send a one-time code in a text message. The user enters the code in your application, and your application reports it to the Verification API.

How it works#

  1. You start a verification with delivery_method set to sms.

  2. The Verification API sends a text message containing a newly generated numeric code to the destination.

  3. The user enters the code in your application.

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

  5. If the code matches, the verification status becomes verified.

Starting an SMS verification#

Set delivery_method to sms. Add optional SMS settings in an sms object inside data. The API reads this object only when delivery_method is sms.

Use languages to select the preferred message-template languages. Use app_hash with Android SMS Retriever so a compatible Android application can capture the incoming code automatically.

The following example uses HTTP Basic authentication and requests the en-US message template:

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": "sms",
    "sms": {
      "languages": ["en-US"]
    }
  }
}

curl

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

response

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

{
  "data": {
    "id": "0f9c8b7a-1e2d-4c3b-9a8f-7e6d5c4b3a21",
    "destination": "4915112345678",
    "delivery_method": "sms",
    "fee": "0.06",
    "status": "pending",
    "error_code": null,
    "error_detail": null,
    "expires_at": "2026-07-15T10:02:00.000Z",
    "sms": {
      "template": "Your code is {{CODE}}",
      "language": "en-US",
      "interception_timeout": 120
    }
  }
}

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 text message reached the destination.

The response includes an sms object containing SMS-specific information:

  • template contains the message template. {{CODE}} marks where the generated code appears.

  • language is the language the API selected, which is not necessarily the first one requested. Compare it with the list you sent to detect a fallback to en-US.

  • interception_timeout specifies how long an on-device SMS listener should remain active. It does not control verification expiry. Manual code entry remains available until expires_at.

  • app_hash is returned only when the supplied hash was accepted and stored for the verification.

Supported languages#

Pass sms.languages as BCP 47 tags, most preferred first. The first supported tag wins; if none of them is supported, the message is sent in en-US.

Tags are matched exactly, so the region subtag is required: pl does not match pl-PL and falls back to en-US. A tag that is not a well-formed BCP 47 tag is rejected with languages_invalid instead.

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

The following language tags are supported:

BCP 47 tag

Language

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)

hr-HR

Croatian (Croatia)

hu-HU

Hungarian (Hungary)

is-IS

Icelandic (Iceland)

it-IT

Italian (Italy)

ja-JP

Japanese (Japan)

ka-GE

Georgian (Georgia)

lt-LT

Lithuanian (Lithuania)

lv-LV

Latvian (Latvia)

mk-MK

Macedonian (North Macedonia)

ms-MY

Malay (Malaysia)

mt-MT

Maltese (Malta)

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)

ru-RU

Russian (Russia)

sk-SK

Slovak (Slovakia)

sl-SI

Slovenian (Slovenia)

sq-AL

Albanian (Albania)

sr-RS

Serbian (Serbia)

sv-SE

Swedish (Sweden)

th-TH

Thai (Thailand)

uk-UA

Ukrainian (Ukraine)

zh-CN

Chinese Simplified (China)

zh-HK

Chinese Traditional (Hong Kong)

Reporting the code#

Submit the code the user received. The delivery_method must match the verification. The following example reports a correct code and returns status verified:

http

PATCH /api/v1/verifications/0f9c8b7a-1e2d-4c3b-9a8f-7e6d5c4b3a21 HTTP/1.1
Host: verification.didww.com
Content-Type: application/json
Accept: application/json
Authorization: Basic eW91cl9hcHBfa2V5OnlvdXJfYXBwX3NlY3JldA==

{
  "data": {
    "delivery_method": "sms",
    "code": "123456"
  }
}

curl

curl -i -X PATCH https://verification.didww.com/api/v1/verifications/0f9c8b7a-1e2d-4c3b-9a8f-7e6d5c4b3a21 -H "Accept: application/json" -H "Content-Type: application/json" --data-raw '{"data": {"code": "123456", "delivery_method": "sms"}}' --user your_app_key:your_app_secret

response

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

{
  "data": {
    "id": "0f9c8b7a-1e2d-4c3b-9a8f-7e6d5c4b3a21",
    "destination": "4915112345678",
    "delivery_method": "sms",
    "fee": "0.06",
    "status": "verified",
    "error_code": null,
    "error_detail": null,
    "expires_at": "2026-07-15T10:02:00.000Z",
    "sms": {
      "template": "Your code is {{CODE}}",
      "language": "en-US",
      "interception_timeout": 120
    }
  }
}

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#