Skip to content Skip to navigation Skip to topbar

On this page

Verify Phone Verification API V1

(warning)

Warning

Verify v1 API has reached End of Sale. It is now closed to new customers and will be fully deprecated in the future.

For new development, we encourage you to use the Verify v2 API. v2 has an improved developer experience and new features, including:

Twilio helper libraries in multiple languages
PSD2 Secure Customer Authentication Support
Improved Visibility and Insights

Existing customers will not be impacted at this time until Verify v1 API has reached End of Life. For more information about migration, see Migrating from 1.x to 2.x.

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 check that a received code is valid.

Phone verification is an important first step in your online relationship with a user. To learn more about best practices and recommended registration flows, please consult Twilio Verify Best Practices.

Send a Verification Code

To verify a user's phone number, you will start by requesting to send a verification code to their device. Each verification code is valid for 10 minutes. Subsequent calls to the API before the code has expired will send the same verification code. You cannot modify the amount of time a verification code is valid. You can query the status endpoint to check if a verification code is still valid.

Note that you may use dashes, periods, spaces or nothing to format a phone number.

POST https://api.authy.com/protected/{FORMAT}/phones/verification/start

URL

Name	Type	Description
FORMAT	String	The format to expect back from the REST API call. `json` or `xml`.

PARAMETERS

Name	Type	Description
via	String	The method of delivering the code to the user. `sms` or `call`. (🏢 not PII )
country_code	Integer	The phone's country code. (🏢 not PII )
phone_number	String	The phone number to send the verification code. (📇 PII )
locale	String (recommended)	The language of the message received by user. If no region is given (or supported) there will be a default by country. Depending on the country, this will either be the official language of the country or English. We highly recommend that you test your region or use the locale parameter to ensure that your desired language is used. See supported languages for a list of available options. (🏢 not PII )
code_length	Integer (optional)	Optional value to change the number of verification digits sent. Default value is 4. Allowed values are 4-10. (🏢 not PII )
custom_code	Integer (optional)	Pass in a pre-generated code. Code length can be between 4-10 characters. Contact Twilio Sales to have this feature enabled. (🏢 not PII )

Start a phone verification.

1// npm install authy
2const authy = require("authy")("YOUR_AUTHY_API_KEY");
3
4authy
5  .phones()
6  .verification_start("5551234567", "1", "sms", function(err, res) {
7    if (err) {
8      console.log(err);
9    }
10
11    console.log(res.message);
12  });

Output

1{
2  "carrier": "AT&T Wireless",
3  "is_cellphone": true,
4  "message": "Text message sent to +1 987-654-3210.",
5  "seconds_to_expire": 599,
6  "uuid": "b8ebcd40-1234-5678-3fb5-0e5d6a065904",
7  "success": true
8}

(information)

Info

Please note: For some regions, we are unable to return carrier and cellphone data by default. You need to contact our support team to switch on those regions. More information on our support site.

Supported Languages (Recommended)

Please reference Supported Languages for full documentation. 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. Supported languages for the locale parameter are af, ar, ca, zh, zh-CN, zh-HK, hr, cs, da, nl, en, fi, fr, de, el, he, hi, hu, id, it, ja, ko, ms, nb, pl, pt-BR, pt, ro, ru, es, sv, tl, th, tr, vi.

For more information, please reference our full guide to Supported Languages.

Custom Verification Codes (Optional)

If you already have token generation and validation logic and would like to keep those systems in place, you can do so. We have a feature where you can submit your code to us and utilize our pre-screened message templates and localizations for both text and voice.

With this modified setup, you will be charged on each attempted customer verification (requests for a verification code). Due to situations like abandoned requests and users who eagerly request multiple codes, we typically see 30% more /start verifications than /check verifications. This means that you can expect to pay 30% more for this feature. Keep this in mind as you are considering your options.

If you're using custom verification codes you must also provide feedback that lets us know whether or not the user verified the code. This allows us to proactively monitor our global routing and stay operational. You can send feedback to our system with the Verify Feedback API.

Contact Twilio Sales and we'll help you enable this option.

Start a phone verification with custom code.

1curl -X POST 'https://api.authy.com/protected/json/phones/verification/start' \
2-H "X-Authy-API-Key: d57d919d11e6b221c9bf6f7c882028f9" \
3-d via='sms' \
4-d phone_number='987-654-3210' \
5-d country_code=1 \
6-d locale=en \
7-d custom_code=3333

Output

1{
2  "carrier": "AT&T Wireless",
3  "is_cellphone": true,
4  "message": "Text message sent to +1 987-654-3210.",
5  "seconds_to_expire": 599,
6  "uuid": "b8ebcd40-1234-5678-3fb5-0e5d6a065904",
7  "sms_id": "cafd7a60-6d03-1234-5678-0eb34144aeb2", # You'll use this ID to send feedback
8  "success": true
9}

Following a request using custom_code you will then submit a request to our Feedback API. Head over to the Feedback API docs for example requests.

Check a Verification Code

To check if a verification code is correct, pass the code along with the phone number to the API.

GET https://api.authy.com/protected/{FORMAT}/phones/verification/check

URL

Name	Type	Description
FORMAT	String	The format to expect back from the REST API call. `json`, or `xml`.

PARAMETERS

Name	Type	Description
country_code	Integer	The phone's country code. (🏢 not PII )
phone_number	String	The phone number to send the verification code. (📇 PII )
verification_code	String	The verification code from the user that is being validated. (🏢 not PII )

Check a Verification Code.

1authy.phones().verification_check('111-111-1111', '1', '1234', function (err, res) {
2  if (err) {
3    // invalid token  
4    console.log(err);
5  }
6
7  console.log(res);
8});

Output

1{
2  "message":"Verification code is correct.",
3  "success":true
4}

Get the Status of a Verification Code Sent to the User

Each verification code is valid for 10 minutes. Subsequent calls to the API before the code has expired will send the same verification code. Use this status API to determine how much time remains for an active or pending verification request.

GET https://api.authy.com/protected/{FORMAT}/phones/verification/status

Name	Type	Description
FORMAT	String	The format to expect back from the REST API call. `json`, or `xml`.

PARAMETERS

Name	Type	Description
uuid	String	The uuid from the original request. (🏢 not PII )
country_code	Integer (Optional)	The phone's country code. Alternative to `uuid` when combined with `phone_number`. (🏢 not PII )
phone_number	String (Optional)	The phone number to send the verification code. Alternative to `uuid` when combined with `country_code`. (📇 PII )

Response

Name	Type	Description
status	String	The status of the original request to the user. `expired`, `verified` or `pending`. (🏢 not PII )
seconds_to_expire	Integer	The amount of time in seconds remaining before the verification code expires. (🏢 not PII )
success	Boolean	Returns `true` if the request was successful. (🏢 not PII )
message	String	A message indicating what happened with the request. (🏢 not PII )

Check Verification Status using Verification UUID.

1curl 'https://api.authy.com/protected/json/phones/verification/status?uuid=b8ebcd40-1234-5678-3fb5-0e5d6a065904' \
2-H "X-Authy-API-Key: d57d919d11e6b221c9bf6f7c882028f9"

Output

1{
2  "message": "Phone Verification status.",
3  "status": "verified",
4  "seconds_to_expire": 474,
5  "success": true
6}

This example checks the status of the request using country_code and phone_number.

Check Verification Status using Phone Number.

1curl 'https://api.authy.com/protected/json/phones/verification/status?country_code=1&phone_number=987-654-3210' \
2-H "X-Authy-API-Key: d57d919d11e6b221c9bf6f7c882028f9"

Output

1{
2  "message": "Phone Verification status.",
3  "status": "pending",
4  "seconds_to_expire": 598,
5  "success": true
6}