Twilio Verify API

The Twilio Verify REST API allows you to verify that a user has a claimed device in their possession. The API lets you request a verification code to be sent to the user and to verify that a received code is valid. The REST API is designed to use HTTP response codes to indicate status.

Your api_key can be obtained by logging into the Twilio Console and selecting the app for which you are authenticating users

Production API locations

The Twilio Verify API server base URL is: https://api.authy.com

Phone Verification Quickstart

Try our Phone Verification Quickstart, which allows you to quickly build a demo phone verification application. When you're done, the same codebase supports Two-factor authentication as well.

cURL API Examples

You can also clone our cURL API repo which implements all features of the Twilio account security APIs including Verify. We've included a Postman collection and environment as well.

Request and Verify a Verification Code

When you want to verify a user's phone you start by requesting a verification code for that user's phone number. The verification code is valid for 10 minutes. Subsequent calls to the API within the expiration time will send the same verification code.

The response will includes the carrier, whether the number is a cellphone or not, the verification code expiration time, the request UUID and the request status.

Twilio supports multiple languages for SMS and phone calls. Simply specify a desired country code for localization.

NOTE: You can use dashes, periods, spaces or simply nothing to format a phone number.

POST https://api.authy.com/protected/{json,xml}/phones/verification/start

Parameters

Name Type Description
api_key String The Verify application API key.
via String Either "sms" or "call".
country_code Integer The phone's country code.
phone_number String The phone number to send the verification code.
code_length Integer(optional) Optional value to change the number of verification digits sent. Default is 4. Allowed values are 4-10.
locale String The language of the message received by user. If no locale is given, Twilio will try to autodetect it based on the country code. In case that no locale is autodetected, English will be used. Supported languages are: Afrikaans (af), Arabic (ar), Catalan (ca), Chinese (zh), Chinese (Mandarin) (zh-CN), Chinese (Cantonese) (zh-HK), Croatian (hr), Czech (cs), Danish (da), Dutch (nl), English (en), Finnish (fi), French (fr), German (de), Greek (el), Hebrew (he), Hindi (hi), Hungarian (hu), Indonesian (id), Italian (it), Japanese (ja), Korean (ko), Malay (ms), Norwegian (nb), Polish (pl), Portuguese - Brazil (pt-BR), Portuguese (pt), Romanian (ro), Russian (ru), Spanish (es), Swedish (sv), Tagalog (tl), Thai (th), Turkish (tr), Vietnamese (vi). We support the format country-region as described in IETF's BPC 47. If no region is given (or supported), there will be a default by country.
custom_message String Not enabled by default. Overwrites the default message sent sms or phone call. To request access please contact Twilio Sales with a business use case that requires a nonstandard message. You can inject a phone verification code in the message by using the string {{code}} were you'd like to insert it. IMPORTANT: If the via parameter is set to "call", the locale parameter is mandatory. The following languages are supported for call custom_messages: Catalan (ca), Chinese (zh), Chinese (Mandarin) (zh-CN), Chinese (Cantonese) (zh-HK), Danish (da), Dutch (nl), English (en), Finnish (fi), French (fr), German (de), Italian (it), Japanese (ja), Korean (ko), Polish (pl), Portuguese - Brazil (pt-BR), Portuguese (pt), Russian (ru), Spanish (es), Swedish (sv). We support the format country-region as described in IETF's BPC 47. If no region is given (or supported), there will be a default by country.

Response

Name Type Description
success Bool Whether the request was succesful or not.
message String A message indicating the result of the operation.
is_ported Bool Whether the phone number was ported or not.
is_cellphone Bool Whether the phone number is a cellphone or not.

Examples

Sending code via phone call using default language
curl 'https://api.authy.com/protected/json/phones/verification/start?api_key=XXX' \
-d via='call' \
-d phone_number='111-111-1111' \
-d country_code=1

Sample response:

{
    "carrier":"AT&T Mobility (New Cingular Wireless PCS, LLC)",
    "is_ported":false,
    "is_cellphone":true,
    "message":"Call to +1 111-111-1111 initiated.",
    "success":true
}
Send a code via SMS using a supported language (Spanish)
curl 'https://api.authy.com/protected/json/phones/verification/start?api_key=XXX' \
-d via='sms' \
-d phone_number='111-111-1111' \
-d country_code=1 \
-d locale='es'

Sample response

{
    "carrier":"AT&T Mobility (New Cingular Wireless PCS, LLC)",
    "is_ported":false,
    "is_cellphone":true,
    "message":"Text message sent to +1 111-111-1111",
    "success":true
}

Verify a Code Sent to the User

To verify the verification code simply pass the code along with the phone number.

GET https://api.authy.com/protected/{json,xml}/phones/verification/check

Parameters

Name Type Description
api_key String The Verify Application API key.
country_code Integer The phone's country code.
phone_number String The phone number to send the verification code.
verification_code String The verification code that is being validated.

Response

Name Type Description
success Bool Whether the operation was successful or not.
message String A message indicating the result of the operation.

Example

curl 'https://api.authy.com/protected/json/phones/verification/check?api_key=XXX…&phone_number=111-111-111&country_code=1&verification_code=1234'

Sample response

{
    "message":"Verification code is correct.",
    "success":true
}

Overwriting the default message

If you need to overwrite the default message sent to the user you can use the custom_message parameter. This is not enabled by default and you should contactSales to request this feature.

Once enabled, you must manage the localization of the messages sent and you need to insert the one-time password (TOTP) into your message using the macro shown in the parameter below. Due to the challenges of natural voice and written word translation, we do not translate the custom message into all available locales. See the custom_message entry in the parameters above for supported locales.

When using custom messaging, the {{code}} value is a required parameter.

Send a Custom Message via Sms
curl 'https://api.authy.com/protected/json/phones/verification/start?api_key=XXX' \
-d via='sms' \
-d phone_number='111-111-1111' \
-d country_code=1 \
-d custom_message='Your phone verification pin for Owl Bank is {{code}}'

Sample response

{
    "carrier":"AT&T Mobility (New Cingular Wireless PCS, LLC)",
    "is_ported":false,
    "is_cellphone":true,
    "message":"Text message sent to +1 111-111-1111",
    "success":true
}
Sending a Custom Message via Phone Call
curl 'https://api.authy.com/protected/json/phones/verification/start?api_key=XXX' \
-d via='call' \
-d phone_number='111-111-1111' \
-d country_code=1 \
-d locale='es' \
-d custom_message='Su código de verificación para Owl Bank es {{code}}'

Sample response

{
    "carrier":"AT&T Mobility (New Cingular Wireless PCS, LLC)",
    "is_ported":false,
    "is_cellphone":true,
    "message":"Text message sent to +1 111-111-1111",
    "success":true
}

Handle an Invalid Code

Here is a sample response for invalid verification codes.

Sample response

{
    "message":"Verification code is incorrect.",
    "success":false
}

Response Codes

The following status codes are used:

200: Response is correct. The body of the response will include the data requested.

400: There was an error with the request. The body of the response will have more information.

401: Verification Code is invalid. If your API key is incorrect a 401 will also be served. Check the response body for a message, it might be that the API_KEY is invalid.

503: Service Unavailable Many possible reasons, body will include details. An internal error on Twilio. Your application is accessing an API call you do not have access to. API usage limit. If you reach API usage limits a 503 will be returned, please wait until you can do the call again.

Error codes

When the API returns a status other than 200, we add an error code in the message body. For further information, please check the error codes page for a complete list of errors.

Need some help?

We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd browsing the Twilio tag on Stack Overflow.