Truecaller API Documentation

Authentication

The one thing to keep in mind is that all requests to our API require authentication. For that, you will need to use a User Key (userKey) along with your requests. These access details basically associate, your server, script or program with a specific application. All requests to the API must be made over SSL (https:// not http://).

API Endpoints

Once you have your account, it’s easy to start requesting data from Truecaller. All existing and future endpoints are only accessible via https and are located at api.truecaller.com

The Parameters

Phone numbers must be in their full format (including international code) and be with accordance with the E.164 specification.

Example:
+46XXXXXXXXX - Ok
467XXXXXXXX - Ok
046XXXXXXXXX - Not ok
0046XXXXXXXXX - Not ok

The two main parameters needed so you can start using and get valid responses from our API are:

userKey­ - This is basically your “Identification” in our system. It is necessary so your calls/requests can be valid. Through this userKey we will also make sure you have all the information needed (statistics), related to your usage within our API. Click here to request an account and get your user key.

phone -­ This is the phone number to get information from. The phone number should always be in its complete format (info above).

Please note that the above parameters are case­-sensitive.

Request methods

Only GET methods are available for API calls/requests.

Structure

The Envelope

Every response is contained by an envelope. That is, each response has a predictable set of keys with which you can expect to interact.

URIs

You can make a name search by accessing the following URL with your application credentials (replace APP­-KEY with your own), and passing the phone number (NUMBER) which you would like to search for.

https://api.truecaller.com/v1.0/search.json?userKey=APP­KEY&phone=NUMBER

The above request, will then result in the following response:

{
	"name": "John Doe",
	"trueScore": 64,
	"spamScore": 2 
}

The above structure is the one you can count with and parse/retrieve the needed information from. The name key is of the type String and trueScore/ spamScore are Integers.

If all goes well, you'll only ever see the above structure as a result. However, sometimes things go wrong, and in that case you might see one of the following error responses / results:

Situation: A request with an invalid phonenumber.
Additional HTTP header response: 400 Bad Request

{
	"code": 1001,
	"message": "Failed to parse the phone number parameter" 
}	

Situation: A request with an invalid userKey.
Additional HTTP header response: 401 Unauthorized

{
	"code": 1002,
	"message": "Failed to authenticate the user"
}	

Situation: A request where no data / information could be found for the given phone number.
Additional HTTP header response: 404 Not Found

{
	"code": 1003,
	"message": "No name found for the given phone number" 
}

The above, is the structure for any error result. The code key (Integer) is always associated with the type of the error. For instance, you might want to present users with a different error message (e.g. in another language), or just provide a different text instead. For that, you can then look for the correspondent error code.