Authy Phone Verification API

The Authy Phone Verification API allows you to verify that the user has the device in their possession. The Authy Phone Verification API lets you request a verification code to be sent to the user and also verify that the code received by the user is valid. The REST API is designed to use HTTP response codes to indicate status. The body of the response will also include more information.

The api_key can be obtained by logging into the Authy dashboard and selecting the app for which you are authenticating users

Production API locations

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

Demo AngularJS/NodeJS Implementation

You can clone and run our demo app repo. This full-stack implementation demonstrates both Authy 2FA and Phone Verification.

cURL API Examples

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

Requesting and Verifying the 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.

Authy supports multiple languages for SMS and phone calls. Simply specify the desired country code.

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

Response

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
}

Sending 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
}

Verifying 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

Response

Example

curl 'https://api.authy.com/protected/json/phones/verification/check?api_key=XXX' \
-d phone_number='111-111-111' \
-d country_code=1 \
-d 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 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 shown in the parameter below.

Sending 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
}

When verification code is invalid

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

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.