Verify Phone Verification 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 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.

検証コードを送信する

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

PARAMETERS

例

This example requests a verification code with a custom code_length be sent to the phone number provided. The user will receive a text message with a 6 digit verification code. Make sure you update the placeholders with your API Key and phone number for testing locally. Please verify that you are not specifying the country code twice - once in the country_code parameter and then once again in the phone_number

curl -XPOST 'https://api.authy.com/protected/json/phones/verification/start' \
-H "X-Authy-API-Key: d57d919d11e6b221c9bf6f7c882028f9" \
-d via='sms' \
-d phone_number='987-654-3210' \
-d country_code=1 \
-d code_length=6 \
-d locale='en'

サンプルレスポンス:

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

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)

Example request using custom_code:

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

サンプルレスポンス:

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

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

PARAMETERS

例

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

レスポンス例

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

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

PARAMETERS

レスポンス

サンプル

This example checks the status of the request using the uuid.

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

レスポンス例

{
  "message": "Phone Verification status.",
  "status": "verified",
  "seconds_to_expire": 474,
  "success": true
}

This example checks the status of the request using country_code and phone_number. Note that this method only works for pending verifications. If the request is not pending the response will indicate that No pending verifications for +1 987-654-3210 found with no additional status information.

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

レスポンス例

{
  "message": "Phone Verification status.",
  "status": "pending",
  "seconds_to_expire": 598,
  "success": true
}

利用制限

You may request the status of a phone verification no more than:

• 60 requests in one minute
• 180 requests in one hour
• 250 requests in one day