Get Started

Welcome to the Peoplestacks Developer Documentation! PeopleStacks is an all in one A.I enabled data and communication platform for your business and individual needs. Get up and running with our API libraries and start developing your PeopleStacks integration.

You can view code examples in the dark area to the right; switch the programming language of the examples with the tabs in the top right.

Authentication

Peoplestacks authenticates your API requests using your account’s API key and API token. You can register a new API key and API token at our developer portal. If you do not include your key & token when making an API request, or use one that is incorrect or outdated, PeopleStacks will return an error.

You can obtain the API token and the key from your dashboard. Alternatively, this can be accessed by going to settings > API Token.

https://peoplestacks.com/api/{version}/{resource}?api_key=YOUR_API_KEY&api_token=YOUR_API_TOKEN

People

The People Identity graph provides a way to retrieve additional information from a phone number. The following types of data endpoints are openly available for the developers.

• Caller name
• Carrier name
• Number details & formats
• Gender details
• Trust score
• Email Details
• Social Media Profiles
• Profile Images

Identity Graph

curl --request GET \
  --url 'https://peoplestacks.com/api/v1/lookup/people/%7Bphone_number%7D?api_key=YOUR_API_KEY&api_token=YOUR_API_TOKEN&number_details=true&email_details=true' \
  --header 'accept: application/json' \
  --header 'content-type: application/json'

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://peoplestacks.com/api/v1/lookup/people/%7Bphone_number%7D?api_key=YOUR_API_KEY&api_token=YOUR_API_TOKEN&number_details=true&email_details=true",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => array(
    "accept: application/json",
    "content-type: application/json"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

import requests

url = "https://peoplestacks.com/api/v1/lookup/people/%7Bphone_number%7D"

querystring = {"api_key":"YOUR_API_KEY","api_token":"YOUR_API_TOKEN","number_details":"true","email_details":"true"}

headers = {
    'accept': "application/json",
    'content-type': "application/json"
    }

response = requests.request("GET", url, headers=headers, params=querystring)

print(response.text)

var settings = {
  "async": true,
  "crossDomain": true,
  "url": "https://peoplestacks.com/api/v1/lookup/people/%7Bphone_number%7D?api_key=YOUR_API_KEY&api_token=YOUR_API_TOKEN&number_details=true&email_details=true",
  "method": "GET",
  "headers": {
    "accept": "application/json",
    "content-type": "application/json"
  }
}

$.ajax(settings).done(function (response) {
  console.log(response);
});

The above command returns JSON structured like this:

{
    "data": {
        "cuid": "cjj097be00001alt469e9hqwq",
        "key": "+9193572XXXX",
        "md5_hash": "511091bdfa15379329f52c9a19e052d2",
        "caller_name": {
            "caller_name": "John Doe",
            "error_code": null
        },
        "number_details": {
            "is_valid": true,
            "formats": {
                "E164": "+9193572XXXXX",
                "national": "093572 XXXXX",
                "international": "+91 93572 XXXXX"
            },
            "number": "93572XXXXX",
            "calling_code": 91,
            "country_code": "IN",
            "location": "India",
            "number_type": "MOBILE",
            "carrier": "Reliance Jio",
            "time_zone": [
                "Asia/Calcutta"
            ]
        },
        "email_details": {
            "email": "john.doe@gmail.com"
        }
    }
}

People's identify graph accepts phone number path and other parameters as query strings. The data availability will be depend on the query number and you will be billed as per the account settings. The query is counted as a successful hit, if the response returns with a caller name. Additional parameters should be used to access other data points. Make sure that your account has access to the data endpoints you are accessing. Each data endpoint has its own additional pricing and you will be billed if the response has a requested response to the query. Since all the requests are routed through the base caller name endpoint, you will be charged the base pricing if the other requested query parameters are unavailable in the response. Contact your account manager to enable the parameters which are not activated on your account.

HTTP Request

GET https://peoplestacks.com/api/v1/lookup/people/{E.164_phone_number}

E.164 is an international telephone numbering format. E.164 numbers are formatted [+] [country code] [subscriber number including area code] and can have a maximum of fifteen digits. You can match a E.164 by using the following RegEx. ^\+?[1-9]\d{1,14}$. However, note that the given RegEx can also matches E.164 numbers that are not valid phone numbers. You can use the peoplestacks phone validator API to verify valid numbers.

The base path by default will fetch the caller name (no additional parameters required) and if the name is available, it will be counted as a successful event and billed according to your account settings.

Examples of E.164 Numbers

Query Parameters

Verify

Validate a phone number and reduce fraud and increase customer engagement.

Indian Numbers

curl --request GET \
  --url 'https://peoplestacks.com/api/v1/verify/IN/%7Bphone_number%7D?api_key=YOUR_API_KEY&api_token=YOUR_API_TOKEN' \
  --header 'accept: application/json' \
  --header 'content-type: application/json'

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://peoplestacks.com/api/v1/verify/IN/%7Bphone_number%7D?api_key=YOUR_API_KEY&api_token=YOUR_API_TOKEN",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => array(
    "accept: application/json",
    "content-type: application/json"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

import requests

url = "https://peoplestacks.com/api/v1/verify/IN/%7Bphone_number%7D"

querystring = {"api_key":"YOUR_API_KEY","api_token":"YOUR_API_TOKEN","number_details":"true","email_details":"true"}

headers = {
    'accept': "application/json",
    'content-type': "application/json"
    }

response = requests.request("GET", url, headers=headers, params=querystring)

print(response.text)

var settings = {
  "async": true,
  "crossDomain": true,
  "url": "https://peoplestacks.com/api/v1/verify/IN/%7Bphone_number%7D?api_key=YOUR_API_KEY&api_token=YOUR_API_TOKEN",
  "method": "GET",
  "headers": {
    "accept": "application/json",
    "content-type": "application/json"
  }
}

$.ajax(settings).done(function (response) {
  console.log(response);
});

The above command returns JSON structured like this:

{
    "data": {
        "cuid": "cjj328ovo00010iovq3apyb8m",
        "key": "+9196055XXXXX",
        "md5_hash": "58c30a553af4ea4f9a81edb14af0be8d",
        "number_details": {
            "is_valid": true,
            "formats": {
                "E164": "+9196055XXXXX",
                "national": "096055 XXXXX",
                "international": "+91 96055 XXXXX"
            },
            "number": "96055XXXXX",
            "calling_code": 91,
            "country_code": "IN",
            "number_type": "MOBILE",
            "time_zone": [
                "Asia/Calcutta"
            ]
        },
        "verify": {
            "is_ported": true,
            "circle": "Karnataka",
            "operator": "Airtel"
        }
    }
}

Verify API helps to identify the operator and the region of a mobile number. This particular endpoint only accepts a standard mobile number and returns the number details and operator - circle information even if the number is ported.

HTTP Request

GET https://peoplestacks.com/api/v1/verify/IN/{E.164_phone_number}

E.164 is an international telephone numbering format. E.164 numbers are formatted [+] [country code] [subscriber number including area code] and can have a maximum of fifteen digits. You can match a E.164 by using the following RegEx. ^\+?[1-9]\d{1,14}$. However, note that the given RegEx can also matches E.164 numbers that are not valid phone numbers. You can use the peoplestacks phone validator API to verify valid numbers.

Examples of E.164 Numbers

Supported Operators

• Airtel
• BSNL
• Idea
• Jio
• MTNL
• Tata DOCOMO
• Telenor
• Vodafone

Supported Regions

• Andhra Pradesh
• Assam
• Bihar Jharkhand
• Chennai
• Delhi NCR
• Gujarat
• Haryana
• Himachal Pradesh
• Jammu Kashmir
• Karnataka
• Kerala
• Kolkata
• Madhya Pradesh Chhattisgarh
• Maharashtra
• Mumbai
• North East
• Orissa
• Punjab
• Rajasthan
• Tamil Nadu
• UP East
• UP West
• West Bengal

Errors

Peoplestacks has two set of error codes available. The standard http response codes and platform response codes. The http error are send in headers whereas platform respose codes are available in the API response.

Platform Codes

HTTP Codes