Phone Intelligence

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: OK
    Response is correct. The body of the response will
    include the data requested.

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

401: Unauthorized
    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.


  • Both JSON and XML formats are supported by all API calls

  • You always need to specify a format (json | xml)

  • 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

Requesting phone number information.

With this API you can get information about a phone number, It can tell you if the number is voip, landline or cell phone.
Also, this API can tell you what's the carrier or provider of the phone number.

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

Parameters

Name Type Description
user_ip String IP of the user requesting the information about the phone number.
country_code Integer Phone country code.
phone_number String Phone number to query.

Response

Name Type Description
message String A message indicating the result of the operation.
type String Phone number type. It can be voip, landline, cellphone, unknown.
provider String Name of the service provider.
ported Bool Whether the phone number was ported or not.
success Bool Whether the request was successful or not.

Example

curl -i 'https://api.authy.com/protected/json/phones/info?phone_number=7754615609&country_code=1' \
-H "X-Authy-API-Key: d57d919d11e6b221c9bf6f7c882028f9"
Sample response
{
  "message":"Phone number information as of 2014-07-02 20:40:05 +0000",
  "type":"voip",
  "provider":"Pinger/TextFree",
  "ported": false,
  "success": true
}
Invalid request example
curl -i 'https://api.authy.com/protected/json/phones/info?phone_number=1&country_code=15' \
-H "X-Authy-API-Key: d57d919d11e6b221c9bf6f7c882028f9"
Sample response
{
    "message": "Couldn't get phone information: Country code is not supported, Phone number is invalid",
    "success": false,
}