Authy Phone Intelligence API

The Authy Phone Intelligence API provides information about a phone number. We return 3 key pieces of information.

  • type of phone number [cell phone | landline | voip]
  • provider of the number, e.g. "AT&T Wireless" or "
  • If the number has been ported from a previous provider.

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

cURL API Examples

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

Resource URI

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

Where {format} is either JSON or XML. Any /protected/ api call requires you to pass an api_key as a parameter which is obtained from the Authy administrative dashboard. The rest of the parameters are described in the following table.

Parameters

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

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.

Examples

curl -i 'https://api.authy.com/protected/json/phones/info?api_key=KEY&phone_number=7754615609&country_code=1'

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?api_key=KEY&phone_number=1&country_code=15'

Sample response

{
"message": "Couldn't get phone information: Country code is not supported, Phone number is invalid",
"success": false,
}

Return Codes

The API uses HTTP response codes to indicate status. The body of the response will also include more information.

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.

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.

Need some help?

We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd browsing the Twilio tag on Stack Overflow.