#Our Platform
Think of Next Caller’s API as your company’s secondary database. When you don’t know who’s calling, simply ping our database. With over 220 million records, we can help you ID the names, addresses and even emails of your inbound callers.

##Getting Started
To start using the Next Caller API, sign up for a free trial. Once your account is created, you will be able to access our Advanced Caller ID database. Our API is based on REST principles and uses OAuth 1.0a for Authentication. Please make sure to read our Terms of Use before using the API. Next Caller data can only be used to identify inbound callers; any accounts violating our terms of use will be suspended.

##Authentication
###Authorizing a request
The NextCaller API uses the OAuth 1.0a protocol for Authorization. If your language of choice has a library for OAuth 1.0a, we recommend using that. If you are implementing your own client code to construct the required Authorization header, please refer to our detailed documentation:

###Overview

This document will show you how to modify HTTP requests for the purpose of sending authorized requests to the Next Caller API.

For example, a request to get users profile whose phone number is (212) 555-8383 will look something like this:

GET /v2/records/?phone=2125558383&format=json HTTP/1.1
Host: api.nextcaller.com
Cache-Control: no-cache

All HTTP libraries should be able to generate and issue the above request with very little difficulty. However, this request is considered invalid, since there is no way of knowing:

• Which user is making the request
• If the request has been altered by a third party while in transit

Next Caller’s API relies on the OAuth 1.0a protocol to allow applications to provide this information. Our implementation requires that requests needing authorization contain an additional HTTP Authorization header with enough information to answer the questions listed above. A version of the HTTP request shown above, modified to include this header, looks like this (normally the Authorization header would need to be on one line, but has been wrapped for legibility here):

GET /v2/records/?phone=2125558383&format=json HTTP/1.1
Host: api.nextcaller.com
Authorization: 
    OAuth realm="https%3A%2F%2Fapi.nextcaller.com%2F",
          oauth_consumer_key="EG2D22B98D2232253SE3",
          oauth_token="",
          oauth_signature_method="HMAC-SHA1",
          oauth_timestamp="1392040900",
          oauth_nonce="685JkT",
          oauth_version="1.0",
          oauth_signature="DiVaj6S3DbzIXJZrPp8fBlj4osY%3D"
Cache-Control: no-cache

If this request were created, it would have been accepted by the Next Caller API as valid, and created this response:

{
    "records": [
        {
            "fraud_threat": "low", 
            "email": "demo@nextcaller.com", 
            "member": "true", 
            "phone": [
                {
                    "number": "2125558383"
                }
            ], 
            "carrier": "VERIZON NEW YORK, INC.", 
            "address": [
                {
                    "line1": "129 West 81st Street", 
                    "line2": "Apt 5A", 
                    "city": "New York", 
                    "state": "NY", 
                    "zip_code": "10024", 
                    "extended_zip": "", 
                    "country": "USA"
                }
            ], 
            "department": "not specified", 
            "id": "97d949a413f4ea8b85e9586e1f2d9a", 
            "billing_info_on_file": "true"
        }
    ]
}

###Collecting parameters
You will note that the header contains seven key/value pairs, where all keys begin with the string “oauth_”. Collecting these seven values and creating a similar header will allow you to specify authorization for any given Next Caller API request. The way in which each value was created is described below:

####Consumer key
The oauth_consumer_key identifies which application is making the request. Obtain this value from checking the settings page for your application on dev.nextcaller.com/profile/api-usage.

oauth_consumer_key	EG2D22B98D2232253SE3

####Nonce
The oauth_nonce parameter is a unique token, which should be generated by your application for each unique request. Next Caller will use this value to determine whether a request has been submitted multiple times. Random alphanumeric string should be OK here.

oauth_nonce	685JkT

####Signature
The oauth_signature parameter contains a value that is generated by running all of the other request parameters and secret key through a signing algorithm. This signature is important because it allows Next Caller to verify that the request has not been modified in transit, that it is the application sending the request, and that the application has authorization to interact with the user’s account.

Here, you will find the process for creating the oauth_signature for this request.

oauth_signature	DiVaj6S3DbzIXJZrPp8fBlj4osY%3D

####Signature method
The oauth_signature_method used by Next Caller is HMAC-SHA1. This value should be used for any authorized request sent to Next Caller’s API.

oauth_signature_method	HMAC-SHA1

####Timestamp
The oauth_timestamp parameter indicates when the request was created. This value should be the number of seconds since the Unix epoch at the point the request is generated, which should be easy in most programming languages. Because Next Caller will reject requests that were created too far in the past, it is important to keep the clock of the computer generating requests in sync with NTP.

oauth_timestamp	1392040900

####Token
The oauth_token parameter typically represents a user’s permission to share access to their account with your application. We use an empty string here, as we are working with OAuth 1.0a

oauth_token

####Version
The oauth_version parameter should be 1.0 for any request sent to the Next Caller API.

oauth_version	1.0

###Building the header string
To build the header string, imagine writing to a string named nextcaller_header_string.

1. Append the string "OAuth " (including the space at the end) to nextcaller_header_string.
2. For each key/value pair of the seven parameters listed above:
   1. Percent encode the key and append it to nextcaller_header_string.
   2. Append the equals character ‘=’ to nextcaller_header_string.
   3. Append a double quote ‘"’ to nextcaller_header_string.
   4. Percent encode the value and append it to nextcaller_header_string.
   5. Append a double quote ‘"’ to nextcaller_header_string.
   6. If there are key/value pairs remaining, append a comma ‘,’ and a space ’ ’ to nextcaller_header_string.

Pay particular attention to the percent encoding of the values when building this string. For example, the oauth_signature value of tnnArxj06cWHq44gCs1OSKk/jLY= must be encoded as tnnArxj06cWHq44gCs1OSKk%2FjLY%3D.

Performing these steps on the parameters collected above results in the following string:

OAuth realm="https%3A%2F%2Fapi.nextcaller.com%2F", oauth_consumer_key="EG2D22B98D2232253SE3", oauth_token="", oauth_signature_method="HMAC-SHA1", oauth_timestamp="1392040900", oauth_nonce="685JkT", oauth_version="1.0", oauth_signature="DiVaj6S3DbzIXJZrPp8fBlj4osY%3D"

This value should be set as the Authorization header for the request.

##GET Profile
GET Profile provides the profile information Next Caller has about a number. A user’s profile may have any or all of these fields:

Field	Definition
“first_name”	Caller’s first name.
“last_name”	Caller’s last name.
“name”	Caller’s full name.
“language”	Caller’s preferred language.
“fraud_threat”	Next Caller uses an algorithm to assess all calls for fraud threat. For example, we may detect that a caller is “spoofing” his or her number (that is, calling from a phone other than the one identified by the transmitted phone number) and therefore presents a “High” level of fraud threat. When everything looks normal with an inbound call, and that number has not been reported by any agents as a potential fraudulent caller, the caller will receive a “Low” threat level.
“email”	The email address associated with the user_id for verification purposes. Using this information to send unsolicited “spam” emails is in violation of our Terms of Service and will result in your account being terminated.
“member”	Boolean. True if the user_id belongs to a Next Caller member who requires priority routing.
“phone”	All phone numbers known to be associated with the specified user_id.
“carrier”	The name of the phone carrier associated with the user_id.
“address”	Caller’s mailing address(es).
“billing_info_on_file”	Boolean. True if the caller has billing information on file with their Next Caller account, which may be accessed with the caller’s 4-digit PIN via the Billing endpoint. Billing component in private beta.
“id”	The unique identifier which Next Caller uses to reference the record. You may need it to process “POST Profile” request.
“department”	Departments indicates where the caller wants to be routed.

###Parameters
phone number (digits only, no extensions)

###Resource URL

https://api.nextcaller.com/v2/records/?phone=XXXXXXXXXX&format=json

###Example Request

https://api.nextcaller.com/v2/records/?phone=2125558383&format=json

###Formats
By appending a format parameter to your query, you can change the data output format. You can append json or xml. If you need a custom format, contact support@nextcaller.com

####json

{
    "records": [
        {
            "fraud_threat": "low", 
            "first_name": "Jerry", 
            "last_name": "Seinfeld", 
            "name": "Jerry Seinfeld", 
            "language": "English", 
            "billing_info_on_file": "true", 
            "member": "true", 
            "phone": [
                {
                    "number": "2125558383"
                }
            ], 
            "carrier": "Verizon Wireless", 
            "address": [
                {
                    "city": "New York", 
                    "extended_zip": "", 
                    "country": "USA", 
                    "line2": "Apt 5a", 
                    "line1": "129 West 81st Street", 
                    "state": "NY", 
                    "zip_code": "10024"
                }
            ], 
            "department": "not specified", 
            "id": "97d949a413f4ea8b85e9586e1f2d9a", 
            "email": "demo@nextcaller.com"
        }
    ]
}

####xml

<response>
    <records>
        <object>
            <name>Jerry Seinfeld</name>
            <first_name>Jerry</first_name>
            <last_name>Seinfeld</last_name>
            <language>English</language>
            <fraud_threat>low</fraud_threat>
            <email>demo@nextcaller.com</email>
            <member>true</member>
            <phone>
                <object>
                    <number>2125558383</number>
                </object>
            </phone>
            <carrier>Verizon Wireless<carrier/>
            <address>
                <object>
                    <line1>129 West 81st Street</line1>
                    <line2>Apt 5a</line2>
                    <city>New York</city>
                    <state>NY</state>
                    <zip_code>10024</zip_code>
                    <extended_zip/>
                    <country>USA</country>
                </object>
            </address>
            <department>not specified</department>
            <id>97d949a413f4ea8b85e9586e1f2d9a</id>
            <billing_info_on_file>true</billing_info_on_file>
        </object>
    </records>
</response>

##POST Profile
On occasion, you may find that the profile data is incorrect or out-of-date. In this case, we ask that you kindly let us know by POSTing the altered data back to us.
Example with all available fields:

{
    "first_name":"Clark",
    "last_name":"Kent",
    "email":"clarkkent@supermail.com",
    "phone1":"1234567890",
    "phone2":"2345678901",
    "phone3":"3456789012",
    "shipping_address1":{
        "line1":"223 Kryptonite Ave.",
        "line2":"",
        "city":"Smallville",
        "state":"KS",
        "zip_code":"66002"
    },
    "shipping_address2":{
        "line1":"224 Kryptonite Ave.",
        "line2":"",
        "city":"Smallville",
        "state":"KS",
        "zip_code":"66002"
    }
}

You can omit any of these parameters; omitted parameters won’t change.

###Parameters
The ID of the user whose profile you wish to edit, e.g. 97d949a413f4ea8b85e9586e1f2d9a

###Resource URL

https://api.nextcaller.com/v2/users/id/?format=json

###Example Request

POST  https://api.nextcaller.com/v2/users/97d949a413f4ea8b85e9586e1f2d9a/?format=json
Content-Type	application/json; charset=utf-8
{
    "first_name":"Clark",
    "last_name":"Kent",
    "shipping_address1":{
        "line1":"225 Kryptonite Ave.",
        "line2":"",
    }
}

###Example Responce

{"success": true}

##POST Accuracy
Next Caller only bills your account when a profile is 100% accurate. If any data we provide is incorrect, tell us and we’ll credit your account.

###Parameters

Field	Definition
“id”	The ID of the user whose profile you wish to edit, e.g. 97d949a413f4ea8b85e9586e1f2d9a
“accuracy”	must be ‘valid’ or ‘invalid’

###Resource URL

https://api.nextcaller.com/v2/accuracy/id/?format=json

###Example Request

POST  https://api.nextcaller.com/v2/accuracy/97d949a413f4ea8b85e9586e1f2d9a/?format=json
Content-Type	application/json; charset=utf-8
{
    "accuracy":"invalid"
}

###Example Responce

{"success": true}

###GET Billing
With Next Caller, agents can quickly access your caller’s billing information. Our GET Billing request is currently in beta and is not available to all clients. If you would like access to GET Billing, please email us at support@nextcaller.com and we will consider your request.

###Error Responses
If you provide invalid or nonsensical parameters to a Next Caller API endpoint, you may receive a response that looks like this:

{
  "error": {
     "message": "The number you have entered is invalid. Please ensure your number contains 10 digits.",
     "type": "Authentication",
     "code": 555
  }
}

Error Code	Definition
“1046”	Invalid consumer key
“1047”	Inactive consumer key and secret
“1048”	No consumer key in request
“1049”	Expired consumer key
“8643”	Billing fail
“8644”	Expired trial
“555”	Invalid phone number
“405”	Invalid UID

###Support
We recommend that all Next Caller API developers subscribe to our Google Group and our Twitter account @NextCallerAPI. We use these channels to alert developers of new features and breaking changes, as well as for feedback and error reports.