YouMail Spam Caller API


API v2.0

Guide v0.10

Last Updated: Oct. 5, 2016




The YouMail Spam Caller API operates as a simple RESTful web service, returning simple OK/Caution/Danger indications of how likely it is that a given phone number is used for spamming or other nuisance calls.

This initial version is very lightweight, with most successful responses on the order of 100 bytes for JSON and just over 200 bytes for XML, with response times typically around 100 ms. Upcoming versions may supply additional information, but the option for stripped down responses will remain.

For example, calling:

If JSON is desired, a successful reponse will look like:

				    "statusCode": 10000,
				    "recordFound": true,
				    "phoneNumber": 9991002000,
				    "spamRisk": {
				        "level": 1
				    "timestamp": "2016-10-06T00:31:04.362Z"

If XML is desired, a succesful resopnse will look like:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

(Actual responses omit the formatting whitespace included here.)

The API can be instructed which response format to use through either a “format=” argument in the URL or by providing the format in the standard HTTP Accept header. For more information on specifying the response format, see Response Types below.

Response Types


The Data API can provide responses in both XML and JSON.


To determine what format the response will be returned in, the Data API first looks for a format= query parameter in the URL and failing that, looks for an Accept HTTP header in the request.



URL Argument:



HTTP Header:

Accept: application/json



URL Argument:



HTTP Header:

Accept: application/xml


If no response content type is specified, the reponse format for all requests will default to JSON.


Note: XML and JSON responses from the server will not necessarily be formatted with newlines and indentations as shown in the examples in this documentation.


When you sign up at, you will be given a Security ID (SID) and an API key. The SID is a permanent, unique identifier for your account. The api key serves an an authentication token, and should be kept secret. If it becomes compromised, a new one can be generated, but in most cases, API keys will also remain unchanged.

Both the SID and the API key are required for every API request. It is recommended that you put them in HTTP header fields “DataApiSid” and “DataApiKey”. URL query parameters apiSid and apiKey are also accepted, but this is not recommended as it is less secure.

User Agent

We require that your requests include a user agent, though the format is up to you. It is recommended that you identify your organization and the version of the API that you are using.

Additional Request Fields

There are two additional fields that can optionally be provided as query parameters in the URL: callee and callerId. Providing these fields is optional, but it can help YouMail to better analyze call patterns for making spam risk determinations. Note that callee should be URL encoded.

Putting it All Together

Thus, a full request might look like this:

With headers:
DataApiSid: 977222...5605
DataApiKey: ba2227d...bb7f333380

Response Fields

				    "statusCode": 10000,
				    "recordFound": true,
				    "phoneNumber": 9991002000,
				    "spamRisk": {
				        "level": 1
				    "timestamp": "2016-10-06T00:31:04.362Z"

statusCode: 10000 indicates success. Other status codes are described below

recordFound: true or false, indicating whether YouMail has sufficient data to make a spam risk determination for this number.

phoneNumber: the phone number you queried.

level: 0 = This number appears to be valid. 1 = This number appears to be a spammer, but the data is inconclusive, so those concerned about false positives may wish to accept calls from this number. 2 = There is very strong evidence that this number is a spammer.

timestamp: The time at which the YouMail server generated this response.

Status Codes & Error Messages

When making requests to the Data API, the following statuses, status codes and error messages may be returned.

Success codes (10xxx)


Successful query

We were able to retrieve the data you requested.


Successful update

We were able to process the data you submitted.

Payment error codes (20xxx)


Payment error

General payment error not covered by other codes.


Insufficient balance

Your credit balance was not sufficient to complete the request.


Credit card expired

The card provided for this payment has expired.


Credit card declined

The card provided for this payment was declined by the processing agency or bank.

Authentication and authorization error codes (30xxx)


Authorization error

General authorization error not covered by other codes.


No data module permission

Your account does not have permission to access the requested data module.


Invalid credentials

The username and password supplied were incorrect.


Auth token expired

The auth token provided has expired. Your client must re-authenticate to access the API.


Auth token invalid

The auth token provided is not recognized.


Auth token missing

There was no auth token provided in the request.

Request error codes (40xxx)


Request error

General request error not covered by other codes.


Request format error

The request was in an invalid format and could not be processed.

Internal error codes (50xxx)


Internal error

General internal error not covered by other codes.


Request timed out

We were unable to process your request in an acceptable time frame.