Phone Verification API

  Authy uses a REST API. The API is designed to use HTTP response codes
  to indicate status. The body of the response will also include more
  information.

Return 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 info

401: Verification Code is invalid.
              If your API key is wrong a 401 will also be served, so check the response body, it might be that the API_KEY is invalid.

503: Service Unavailable
              Many reasons, body will include details
              An internal error on Authy.
              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.


Any /protected/ api call requires you to pass an X-Authy-API-Key as an HTTP header
The api key can be obtained by logging into the Authy dashboard and selecting the app for which you are authenticating users

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 possible errors.

Production URL

Authy api server is at: https://api.authy.com

Sending the verification code

When you want to verify a user's phone or cellphone you start by sending them a verification code.
The verification code is valid until is used and subsequent calls to the API will send the same value.

The response will include information about the carrier and whether this number has been ported or not.

Authy has world-wide support for SMS and phone calls. Simply specify the right country code.

NOTE: You can use dashes, periods, spaces or nothing to separate number.

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 must contact [email protected] to request this parameter. Once enabled, it will allow you to send virtually any message you'd like in over 160 languages for SMS and 26 for automated voice calls. However you must manage the localization of the messages sent and you need to insert the Authy code into your message using the macro show in the parameter below.

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

Parameters

Name Type Description
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.
locale String The language of the message received by user. If no locale is given, Authy will try to autodetect it based on the country code. In case that no locale is autodetected, English will be used. Supported languages include: English (en), Arabic (ar), Catalan (ca), Danish (da), German (de), Spanish (es), Greek (el), Finnish (fi), French (fr) , Hebrew (he), Hindi (hi), Hungarian (hu), Indonesian (id), Italian (it), Japanese (ja), Korean (ko), Norwegian (nb), Dutch (nl), Polish (pl), Portuguese (pt), Romanian (ro), Russian (ru), Swedish (sv), Thai (th), Tagalog (tl), Turkish (tr), Vietnamese (vi), Mandarin (zh-CN),Cantonese (zh-HK). 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, to enable, please contact [email protected]. Overwrites the default message sent sms or phone call. 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: English (en), Spanish (es), Portuguese (pt), German (de), French (fr),Italian (it), Daniesh (da),German (de),Finish (fi), Japanese (ja), Korean (ko), Norwegian (nb), Deutch (nl), Polish (pl), Russian (ru), Swedish (sv), Mandarin (zh-CN),Cantonese (zh-HK). 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.

Example

Sending phone verification in spanish
curl 'https://api.authy.com/protected/json/phones/verification/start?' \
-d via='sms' \
-d phone_number='111-111-1111' \
-d country_code=1 \
-d locale='es' \
-H "X-Authy-API-Key: d57d919d11e6b221c9bf6f7c882028f9"
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 code via phone call with default language
curl https://api.authy.com/protected/json/phones/verification/start \
-d via='call' \
-d phone_number='111-111-1111' \
-d country_code=1 \
-H "X-Authy-API-Key: d57d919d11e6b221c9bf6f7c882028f9"
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
}
Sending verification code to an invalid number
curl https://api.authy.com/protected/json/phones/verification/start \
-d via='call' \
-d phone_number='282-23' \
-d country_code=1 \
-H "X-Authy-API-Key: d57d919d11e6b221c9bf6f7c882028f9"
Sample response
{
    "message":"Phone verification couldn't be created: Phone number is invalid",
    "success":false
}
Sending a custom message via sms
curl 'https://api.authy.com/protected/json/phones/verification/start \
-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}}' \
-H "X-Authy-API-Key: d57d919d11e6b221c9bf6f7c882028f9"
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 \
-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}}' \
-H "X-Authy-API-Key: d57d919d11e6b221c9bf6f7c882028f9"
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
}

Verifying the verification code

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

GET https://api.authy.com/protected/{FORMAT}/phones/verification/check?phone_number={NUMBER}&country_code={COUNTRY_CODE}&verification_code={VERIFICATION_CODE}

Parameters

Name Type Description
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 -i 'https://api.authy.com/protected/json/phones/verification/check?phone_number=111-111-111&country_code=1&verification_code=1234' \
-H "X-Authy-API-Key: d57d919d11e6b221c9bf6f7c882028f9"
Sample response
{
    "message":"Verification code is correct.",
    "success":true
}
When verification code is invalid
curl -i 'https://api.authy.com/protected/json/phones/verification/check?phone_number=111-111-111&country_code=1&verification_code=4321' \
-H "X-Authy-API-Key: d57d919d11e6b221c9bf6f7c882028f9"
Sample response
{
    "message":"Verification code is incorrect.",
    "success":false
}