YouMail Spam Risk API

 

API v2.0

Guide v0.10

Last Updated: Oct. 5, 2016

 

Introduction

 

The YouMail Spam Risk 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:

https://dataapi.youmail.com/api/v2/phone/9991002000

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"?>
				<response>
				    <statusCode>10000</statusCode>
				    <recordFound>true</recordFound>
				    <phoneNumber>9991002000</phoneNumber>
				    <spamRisk>
				        <level>1</level>
				    </spamRisk>
				    <timestamp>2016-10-06T00:17:59.402Z</timestamp>
				</response>

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

 

For JSON

URL Argument:

format=json

..or..

HTTP Header:

Accept: application/json

 

For XML

URL Argument:

format=xml

..or..

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.

Authentication

When you sign up at https://data.youmail.com, 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:


https://dataapi.youmail.com/api/v2/9991002000?format=json&callee=9991992999&callerId=Joe%27s+Pizza

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)

10000

Successful query

We were able to retrieve the data you requested.

10100

Successful update

We were able to process the data you submitted.

Payment error codes (20xxx)

20000

Payment error

General payment error not covered by other codes.

20100

Insufficient balance

Your credit balance was not sufficient to complete the request.

20200

Credit card expired

The card provided for this payment has expired.

20300

Credit card declined

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

Authentication and authorization error codes (30xxx)

30000

Authorization error

General authorization error not covered by other codes.

30100

No data module permission

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

30200

Invalid credentials

The username and password supplied were incorrect.

30300

Auth token expired

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

30400

Auth token invalid

The auth token provided is not recognized.

30500

Auth token missing

There was no auth token provided in the request.

Request error codes (40xxx)

40000

Request error

General request error not covered by other codes.

40100

Request format error

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

Internal error codes (50xxx)

50000

Internal error

General internal error not covered by other codes.

50100

Request timed out

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