Introduction

This document details the RESTful API method for integrating Reverd.com resources, providing access to constantly updated phone numbers in our Global database of reported scam and harassing robo-calls.

Quick start

You can test the Reverd RESTful API without charge (no account required to try): Try it free.

The standard E.164 phone number format must be used, starting with a plus sign “+” and the country international dial code followed by the number e.g. +18004030864 or +5534988612722. You can try up to 3 phone numbers from any country.

A query using one of the above numbers will return the following JSON response:

[
    {
        "phone": "+18004030864",
        "blacklisted": true,
        "complaint_count": 23
    }
]

To generate your own key, sign up / log in to My account -> services. You will be provided with options to select suitable programming language of your choice:

How to use

The Reverd API operates over the HTTP / HTTPS protocol using a set of parameters to fine tune the query returning customised answers as requested. Standard E.164 phone number format must be used in requests. Requests must be sent in JSON format complete with header Content-Type: application/json and using type POST.

Both secure HTTPS requests and insecure HTTP requests are supported. HTTP requests could be used for latency sensitive applications and HTTPS requests are recommended for security sensitive applications.

Authentication

Authentication is always required. The authorization process requires that each request is signed with a personal key. Once you have created your account, a key can be easily obtained from My account -> service: Try it.

The authentication key / token must be included into the header like this: API-AUTH-TOKEN: {YOUR TOKEN}

Response Formats

All responses are delivered in the format application/json

Status Codes and Errors

When making reverd.com API requests, there are several different HTTP status codes you may receive. If the status code is 200, everything went well. All other status codes indicate an error in processing the request.

200 OK

The request was successful.

400 BAD REQUEST

The phone number or an argument (e.g. format) isn't valid.

{
    "phone": "wse"
}
{
    "error": {
        "code": 400,
        "message": "The phone number or an argument (e.g. state) isn't valid"
    }
}

401 UNAUTHORIZED

The request was missing authentication or the credentials are not valid.

402 PAYMENT REQUIRED

Authentication succeeded, but the account does not have enough funds available to complete the request.

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request.