API Documentation

Quick Start


Create Your Account


Before you start to dive in to actually use the API, you'll need to first create an account, once you have done that, visit the dashboard. Find your Account SID and Auth Token in the dashboard -- you'll need these for the next section.

Let's walk you through some EveryoneAPI examples, to show you how the API works, and what you can do with it.

The API Call


From the command line, you can use cURL (illustrated below) or simply click the link in your browser:

curl https://api.everyoneapi.com/v1/phone/+15551234567?account_sid=[SID]&auth_token=[TOKEN]&pretty=true

The cURL request above would generate this output:

  {
      "data": {
        "address": "15 Robin Hood Lane",
        "carrier": {
          "id": "214",
          "name": "Growing Wireless Inc."
        },
        "carrier_o": {
            "id": "213",
            "name": "Paine Mobile Inc."
        },
        "cnam": "MICHAEL SEAVER",
        "gender": "M",
        "linetype": "mobile",
        "location": {
          "city": "Long Island",
          "geo": {
            "latitude": 40.799787,
            "longitude": -73.971421
          },
          "state": "NY",
          "zip": "10003"
        },
        "name": "Michael Seaver",
        "image": {
            "cover": "//teloimg-pub.com.s3.amazonaws.com/cover.jpg",
            "large": "//teloimg-pub.com.s3.amazonaws.com/large.jpg",
            "med": "//teloimg-pub.com.s3.amazonaws.com/med.jpg",
            "small": "//teloimg-pub.com.s3.amazonaws.com/small.jpg"
        }
      },
      "pricing": {
        "breakdown": {
          "address": -0.08,
          "carrier": -0.006,
          "carrier_o": -0.0,
          "cnam": -0.005,
          "gender": -0.001,
          "image": -0.05,
          "linetype": -0.001,
          "location": -0.0,
          "name": -0.01
        },
        "total": -0.153
      },
      "status": true,
      "type": "person"
    }

EveryoneAPI Data Points


Each data point is optional and all data points are returned by default, unless otherwise specified.
The data points that are available are listed below:

DATA POINTCOST PER QUERY API IDENTIFIERNOTE
Name$.01name
CNAM$.005cnam
Gender$.001gender
Image$.05imageLinks expire in 30 days
Address$.08address(Includes Location, FREE)
Location (City + State + Zip + Geocode)$.005 (FREE with Address)location
Current Carrier$.006carrier(Includes Original Carrier, FREE)
Original Carrier$.003 (Free with Current Carrier)carrier_o
Linetype$.001linetype

All accounts are prepaid by making deposits to maintain a positive balance or by adding a card for automatic top-ups.

Selecting Data


EveryoneAPI allows you to specify the data points for which you would like to recieve results. If no data points are selected, EveryoneAPI will return all available data. To select which points to return, attach a comma seperated list of identifiers to the query paramater "data", like so:

curl https://api.everyoneapi.com/v1/phone/+15551234567?data=name,carrier,gender&account_sid=[SID]&auth_token=[TOKEN]&pretty=true
  {
       "data": {
         "carrier": {
           "id": "214",
           "name": "Growing Wireless Inc."
         },
         "carrier_o": {
           "id": "213",
           "name": "Paine Mobile Inc."
         },
         "gender": "M",
         "name": "Michael Seaver"
       },
       "pricing": {
         "breakdown": {
           "carrier": -0.006,
           "carrier_o": -0.0,
           "gender": -0.001,
           "name": -0.01
         },
         "total": -0.017
       },
       "status": true,
       "type": "person"
     }

If we wanted to select just a name, we could make this call:

curl https://api.everyoneapi.com/v1/phone/+15551234567?data=name&account_sid=[SID]&auth_token=[TOKEN]&pretty=true
  {
       "data": {
         "name": "Michael Seaver"
       },
       "pricing": {
         "breakdown": {
           "name": -0.01
         },
         "total": -0.01
       },
       "status": true,
       "type": "person"
     }

Integration


Integrating EveryoneAPI into your application is a straightforward process. This section describes exactly what you need to do to get EveryoneAPI working with your application.

How EveryoneAPI Works


Here's are the basic things to keep in mind while integrating EveryoneAPI:

When making requests against the EveryoneAPI, you should always check the HTTP status code to determine whether or not the request was successful. A 200 OK status code indicates the request was successful, and data was found.

Phone Number Formats


Any of the following phone numbers will work:

Phone Number Formats
16502530000
6502530000
650-253-0000
(650)253-0000
650.253.0000

If you make an API request and specify an invalid phone number, you'll receive an HTTP 400 BAD REQUEST status code, indicating the number was not valid.

Handling Responses


Handling HTTP responses properly is the most important part of working with EveryoneAPI. The API follows a strict REST protocol, and tries to return the correct HTTP status codes for every request.

This is important as you'll need to use these status codes to determine what response you've got, and how you want to use it.

A successful API request will return a HTTP 200 OK response, indicating that data was successfully retrieved.

If the request was an invalid phone number, you'll receive an HTTP 400 BAD REQUEST status code.

If the phone number you queried does not have any data available, you'll received an HTTP 404 NOT FOUND status code.

If our service has errors processing your request, you'll receive an HTTP 503 SERVICE UNAVAILABLE error.

We take uptime and availability very seriously, and work our best to never have outages for our customers.

Putting it All Together


In short, to integrate EveryoneAPI into your application you need to:

A. Make an HTTP GET request to our API endpoint using HTTP Basic Auth or Query String based auth (paramaters "account_sid" and "auth_token"):

https://api.everyoneapi.com/v1/phone/<number>

B. Parse the HTTP status code returned. If the status code is NOT an HTTP 200 OK response, it means the request failed for some reason, and data was not included.

That's it! If you have any questions, please shoot us an email, we'd love to help.

REST API Reference


This section contains a full breakdown of our REST API. If you're considering writing your own client library, or integration toolset of any kind, this will be helpful.

EveryoneAPI Request URI


When making API requests, there's only a single URI you need to worry about:

https://api.everyoneapi.com/v1/phone/<number>

The <number> variable can be any valid phone number (as long as we can successfully parse out a valid NANPA phone number).

When you pass us a number, we remove common formatting and ensure that the country code is "+1".

Below are sample <number> values you could use:
+16502530000
+1-650-253-0000
6502530000
16502530000
(650)253-0000

API Status Codes


When making API requests, there are several different HTTP status codes you may receive. The preferred way to handle EveryoneAPI responses is by parsing the HTTP status code.

200 OK - If your API request was successful, you will receive a 200 OK response.

400 BAD REQUEST - If the phone number being queried isn't a valid phone number, you will receive a 400 BAD REQUEST response.

401 UNAUTHORIZED - If you incorrectly specify your account credentials, you will receive a 401 UNAUTHORIZED response. This means you need to check that you have the correct Account SID and Auth Token specified.

402 PAYMENT REQUIRED - If your account balance is too low to complete the requested API query, you will receive a 402 PAYMENT REQUIRED response.

403 FORBIDDEN - In general, we don't rate limit, but if we detect malicous activity you will recieve a 403 FORBIDDEN response.

404 NOT FOUND - If the phone number you are querying isn't covered by our dataset, you will receive a 404 NOT FOUND response.

API Serialization Formats

We currently support JSON and JSONP return formatting. To specify a format, include the query paramater "format" in your request.

json (application/json) - This is the default serialization format. You do not need to explicitly request it, but if you super want to you can do: ?data=name,address&format=json

jsonp (application/javascript) - If requesting jsonp, you must also provide a callback via the query paramater "callback". A full jsonp request might look like: ?data=location,gender&format=jsonp&callback=myCallback

Handling EveryoneAPI Errors

If the EveryoneAPI request you've made is not successful for one reason or another, you will receive an error status, please refer to the error documentation here.

You should always check the HTTP status code of the request if possible, to determine whether or not your request was successful. If you receive anything other than an HTTP 200 OK, the request has failed.

EveryoneAPI Response Times

EveryoneAPI is a realtime service. Queries can take between 40ms and 350ms to complete.