Before You Start

Pleased be sure to read our Terms of Use before using Next Caller®. Data from the Next Caller API can only be used to identify inbound callers. Using our data for any form of outbound solicitation is strictly prohibited and any accounts found violating our Terms of Use will be suspended without notice.

If you are ever uncertain about how you can use the data please contact us prior to proceeding.

 

Getting Started

Once you have an account we recommend that you sign in prior to proceeding. This will ensure that all of the example code uses your API username and password.

Next Caller API is available and easy to try via cURL util.

Installation

If you don't have cURL installed, use http://curl.haxx.se/docs/ as an instruction.

Copy-Paste Code Examples

You can copy and paste all examples. Your API username and password is automatically inserted in all code samples, if you are signed in.

 

Authentication

The Next Caller API authenticates via Basic access authentication. All examples will fill in your API username and password if you are signed in. If you need assistance with the authentication, please contact us

Example request

with authorization header:

curl -X GET \
-H "Authorization: Basic <base64 encoded api username:password string>" \
-H "Content-Type: application/json" \
"https://api.nextcaller.com/v3/id/?phone=%2B12125558383&format=json"

or with --user (-u) curl argument:

curl -X GET \
-u "<api username>:<api password>" \
-H "Content-Type: application/json" \
"https://api.nextcaller.com/v3/id/?phone=%2B12125558383&format=json"

ID Profile by Phone

Phone ID™ retrieves a profile using the provided phone number. Using this endpoint will count towards your monthly quota if used outside of test mode.

Arguments

FieldDefinition
"phone"
REQUIRED
Phone must be urlencoded and presented as E.164 US format (10 digits phone number is allowed).
"format"
OPTIONAL
Format of the response. "json" and "xml" are available.

 

Returns

Returns a profile object if the phone number was valid and a profile was found. If a profile has only some data fields, empty fields are not being presented in response. See example on the right sidebar.

FieldDefinition
"first_name"
string
The caller’s first name.
"last_name"
string
The caller’s last name.

Profiles provide detailed caller information about a particular phone number. The data returned will vary based on your billing plan, and is marked accordingly below.

If a profile can not be found for the provided phone number, 404 error code is returned.

Otherwise an error will be returned if the phone number was not valid, or if there was an error on the server.

 

Definition

GET https://api.nextcaller.com/v3/id/?phone=%2B1<10 digit phone>&format=<format>

or

GET https://api.nextcaller.com/v3/id/?phone=<10 digit phone>&format=<format>

Example request

curl -X GET \
-u "<api username>:<api password>" \
-H "Content-Type: application/json" \
"https://api.nextcaller.com/v3/id/?phone=%2B12125558383&format=json"

Full Raw Response Examples

{
  "first_name": "Jerry",
  "last_name": "Allen",
}

Partial Raw Response Examples

{
  "last_name": "Allen",
}

Validate Profile

Validate Profile provides possibility to check belonging of name, address, email and phone to one person. You might even check one association, e. g.: name and email, or phone and email.

Arguments

Please, use POST http method to send this data in body of request as hashed array:

FieldDefinition
“first_name“
 string
The complete first name of the person.
e.g. “Jerry”
“last_name“
 string
The complete last name of the person.
e.g. “Seinfeld”
“phone“
 string
Phone is a freeform string with at least 10 digits.
e.g. "2125558383", "+12125558383", "+1 (212) 555-83-83"
“email“
  string
The complete email address you want to look up a profile for
“delivery_address_line“
  string
The first address line of the address. Do not include any address line 2 data such as apartment number or floor.
e.g. “129 West 81st Street”
“secondary_address“
  string
The second address line of the address. Do not include any address line 1 data.
e.g. “Apt 5A”
“city“
  string
The city of the person.
e.g. “New York”
“state“
  string
The 2 letter state code of the person.
e.g. “NY”
“zip_code“
  string
The 5 digit zip code of the person.
e.g. “10024”
“plus_four_code“
  string
The 4 digit zip of the person.
e.g. “2344”

If one of these arguments is missed, 400 http error code is generated.

In order to skip one of arguments, leave it as null. Example:

{
    "phone": null, 
    "email": "jerry@example.org",
    ...
}

Returns

Validate Profile request returns hashed array with the next keys:

FieldDefinition
"phone"
array of hashes
Phone hash attributes: 
"valid"
boolean
true if string contains 10 digits of valid US phone number, otherwise false
"comments"
array
Array of keywords to describe validation status. Possible values: invalid, unallocated.
"associations"
array
Array of strings to list associations, that describe how this phone is connected to a person with specified name, address and email.
"email"
array of hashes
Email hash attributes: 
"valid"
boolean
true if this email is deliverable, otherwise false
"comments"
array
Array of keywords to describe validation status. Possible values: invalid, invalid_domain, role_address, disposable, rejected, other.
"associations"
array
Array of strings to list associations, that describe how this email is connected to a person with specified name, address and phone.
"name"
array of hashes
Name hash attributes: 
"valid"
boolean
true if this name is valid, otherwise false
"comments"
array
Array of keywords to describe validation status. Possible values: invalid.
"associations"
array
Array of strings to list associations, that describe how this name is connected to a person with specified address, phone and email.
"address"
array of hashes
Address hash attributes: 
"valid"
boolean
true if this address is exist building, otherwise false
"comments"
array
Array of keywords to describe validation status. Possible values: invalid, incomplete, inactive, vacant.
"associations"
array
Array of strings to list associations, that describe how this address is connected to a person with specified name, phone and email.

 If association isn't passed in request, key should has a null value. Example: if "phone" argument is not passed, like in the above example, "phone" association will be null:

{
    "phone": null,
    "email": {
        "valid": true,
        "comments": [],
        "associations": [
             "address",
             "name",
             "phone"
        ]
     },
     ...
}

 

Definition

POST https://api.nextcaller.com/v3/validate/?format=<format>

Example of full request

curl -X POST \
-u "<api username>:<api password>" \
-H "Content-Type: application/json" \
-d '{
    "first_name": "Jerry",
    "last_name": "Seinfeld",
    "phone": "2125558383",
    "email": "jerry@example.org",
    "delivery_address_line": "129 West 81st Street",
    "secondary_address": "Apt 5A",
    "city": "New York",
    "state": "NY",
    "zip_code": "10024",
    "plus_four_code": "2344"
}' \
"https://api.nextcaller.com/v3/validate/?format=json"

Response:

{
  "phone": {
    "valid": true,
    "comments": [],
    "associations": [
      "name", 
      "address"
    ]
  },
  "email": {
    "valid": false,
    "comments": [
        "disposable",
        "invalid_domain"
    ],
    "associations": []
  },
  "name": {
    "valid": true,
    "comments": [],
    "associations": [
      "phone",
      "address"
    ]
  },
  "address": {
    "valid": true,
    "comments": [],
    "associations": [
        "phone", 
        "name"
    ]
  }
}

Error message:

If you miss one of arguments, next error response will be generated:

{
  "error": "'email' is a required property",
  "schema": {
    "type": "object",
    "required": [
      "phone",
      "first_name",
      "last_name",
      "plus_four_code",
      "delivery_address_line",
      "city",
      "zip_code",
      "state",
      "secondary_address",
      "email"
    ],
    "properties": {
      "phone": {
        "type": [
          "string",
          "null"
        ]
      },
      "first_name": {
        "type": [
          "string",
          "null"
        ]
      },
      "last_name": {
        "type": [
          "string",
          "null"
        ]
      },
      "plus_four_code": {
        "type": [
          "string",
          "null"
        ]
      },
      "delivery_address_line": {
        "type": [
          "string",
          "null"
        ]
      },
      "city": {
        "type": [
          "string",
          "null"
        ]
      },
      "zip_code": {
        "type": [
          "string",
          "null"
        ]
      },
      "state": {
        "type": [
          "string",
          "null"
        ]
      },
      "secondary_address": {
        "type": [
          "string",
          "null"
        ]
      },
      "email": {
        "type": [
          "string",
          "null"
        ]
      }
    }
  }
}

 

Errors

If you provide invalid parameters to the Next Caller API you may receive an error.

Fields Specification

Each error looks like hashed list with "error" field, that includes one more hashed list with error data.

FieldDefinition
"message"
string
REQUIRED
An error message designed to be understandable for a human.
This field is always present in an error.
"code"
string
OPTIONAL
This field is not always present in an error.
"type"
string
OPTIONAL
This field is not always present in an error.
"description"
hash
OPTIONAL
Additional information about the error.
Keys of the hash correspond to arguments of the request, and the value for each key is an array of errors specific to that argument. An example is shown to the right.
This field is not always present in an error.

Error Responses

Error CodeHTTP Status CodeTypeDefinition
400 400 Bad Request Media type error
401 401 Authentication Basic or OAuth Authorization Required
404 404 Bad Request Resource hasn't been found
415 415 Bad Request Content type you have requested is not supported
416 400 Bad Request Malformed request
422 400 Unprocessable Entity Validation Error
500 500 Internal Error Sorry, all extensions are busy
555 400 Bad Request The number you have entered is invalid
1046 401 Authentication Your consumer key is invalid
1047 401 Authentication Your credentials are no longer valid
1049 401 Authentication Your consumer key has expired
1052 405 Authentication This HTTP method is not allowed
1053 405 Authentication This operation is not allowed
1054 400 Validation There are validation errors
1060 403 Authentication Your account does not have an active plan
1061 429 Too Many Requests API calls per second limit is exceeded
1062 403 Authentication Your subscription has been locked
8643 402 Authentication Your trial has expired
8644 402 Authentication We're unable to charge your account

Example error request

curl -X GET \
-u "<api username>:<api password>" \
-H "Content-Type: application/json" \
"https://api.nextcaller.com/v3/id/?phone=2125&format=json"

Example error response

{
    "error": {
        "message": "User Error: The number you have entered is invalid. Please ensure your number contains 10 digits or is urlencoded and presented as E.164 US format: +1xxxxxxxxxx.",
        "code": "555",
        "type": "Bad Request"
    }
}