The Pipl API Developer Hub

Welcome to the Pipl API developer hub. You'll find comprehensive guides and documentation to help you start working with Pipl API as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    Discussions
 
 

There is a single endpoint to all Search API requests: https://api.pipl.com/search/

Note

We require SSL, so change any URL prefix to HTTPS instead of HTTP.
HTTPS API Endpoint: https://api.pipl.com/search/

The API Endpoint accepts either one of:

  • GET request
  • POST request with Content-Type: application/x-www-form-urlencoded

3 Searches

There are 3 different ways to make a search:

  1. A list of Search parameters
  2. A Person object
  3. A Search pointer

All parameters should be UTF-8 and URL Encoded.

Output is always in JSON format. See Response

Note

The minimal requirement to run a search is to have at least one:

  • full name
  • email
  • phone
  • username
  • user_id
  • URL
  • a single valid US address (down to a house number).

We can’t search for a job title or location alone. We’re not a directory and can't provide bulk lists of people, rather we specialize in identity resolution of single individuals.

Suggest Edits

Search configuration parameters

 

The API accepts the following request (configuration) parameters:

Parameter
Default
Type
Description

key

null

String

Your API key, this is our way to identify you and authorize your call.

pretty

true

Boolean

Indicates whether you want the response to be “pretty-printed” (with indentation).

minimum_probability

0.9

Float

0 – 1. The minimum acceptable probability for inferred data.

infer_persons

false

Boolean

whether the API should return persons made up solely from data inferred by statistical analysis from your search query.

minimum_match

0.0

Float

0 – 1. The minimum required match score for possible persons to be returned.

show_sources

false

String

true/false/all/matching. all - all sources are shown. matching or true - only sources from the person. false - don’t show sources.

hide_sponsored

false

Boolean

Whether to omit results marked "sponsored" (when additional data from this source is available behind a website paywall).

live_feeds

true

Boolean

Whether to use live data sources.

match_requirements

none

String

A condition to specify what fields you must get back. Responses not meeting the criteria will return empty and won’t be charged.

source_category_requirements

none

String

A condition to specify what source categories you must get back. Responses with no persons that meet the criteria will return empty and won’t be charged.

callback

none

String

For JSONP support in JavaScript applications. Only alphanumeric characters and underscores are allowed

false

Boolean

"top_match=true" returns the best high-ranking Person match to your search. The API will only return a highly probable Person OR a No Match (when no highly probable profile is found). It never returns a Possible Persons’ response.

For more details, click here.

Global search configuration parameters (all requests in your app)

SearchAPIRequest.set_default_settings(api_key=u'YOURKEY', minimum_probability=None,
    show_sources=None, minimum_match=None, hide_sponsored=None, live_feeds=None)
Pipl.configure do |c|
  c.api_key = 'YOURKEY'
  c.show_sources = 'all'
  c.minimum_probability = 0.7
  c.minimum_match = 0.5
  c.strict_validation = true
end
import com.pipl.api.search.SearchAPIRequest;
import com.pipl.api.search.SearchConfiguration;

SearchConfiguration defaultConfiguration = SearchAPIRequest.getDefaultConfiguration();
defaultConfiguration.apiKey = "YOURKEY";
defaultConfiguration.minimumProbability = null;
defaultConfiguration.showSources = null;
defaultConfiguration.possibleResults = null;
defaultConfiguration.hideSponsored = null;
defaultConfiguration.liveFeeds = null;
PiplApi_SearchAPIRequest::get_default_configuration()->api_key = "YOURKEY";
PiplApi_SearchAPIRequest::get_default_configuration()->minimum_probability = 0.9;
PiplApi_SearchAPIRequest::get_default_configuration()->minimum_match = 0.8;
PiplApi_SearchAPIRequest::get_default_configuration()->hide_sponsored = true;
PiplApi_SearchAPIRequest::get_default_configuration()->live_feeds = false;
PiplApi_SearchAPIRequest::get_default_configuration()->show_sources = "all";
SearchConfiguration defaultConfiguration = SearchAPIRequest.DefaultConfiguration;
defaultConfiguration.ApiKey = "YOURKEY";
defaultConfiguration.MinimumProbability = null;
defaultConfiguration.ShowSources = null;
defaultConfiguration.MinimumMatch = null;
defaultConfiguration.HideSponsored = null;
defaultConfiguration.LiveFeeds = null;
Suggest Edits

Using search parameters

 

Use any combination of the parameters below. Each parameter may be used only once. A search request has to contain at least one valid name, email address, phone, username, user id, URL or a full US address (including a house number).

Parameter
Example
Description

email

clark.kent@example.com

Email address

phone

+1 (999) 888-777

Home/work/mobile phone number. We’ll try to parse the number using libphonenumber.

username

superman

Username/screen-name, minimum 3 characters. There’s an advanced option to search by username or user-id at a specific service like superman@facebook.

user_id

11231@facebook

Unique ID in a supported service, must include the service name.

url

Profile URL in a supported service. This URL will be parsed to a username or user_id object.

first_name

Clark

First name, minimum 2 characters.

last_name

Kent

Last name, minimum 2 characters.

middle_name

Joseph

Middle name or middle initial.

raw_name

Clark Joseph Kent

Full Name. Use this parameter if the accurate name parts (first/middle/last) are not available, this parameter will only be used in absence of first_name and last_name.

country

US

A two-letter, Alpha-2 ISO-3166 country code.

state

KS

A United States, Canada, Great Britain or Australia state code. If a US state is provided and no country specified, we’ll assume the country to be US.

city

Smallville

City.

street

Hickory Lane

Street.

house

10

House number.

zipcode

66605

ZIP Code.

raw_address

10-1 Hickory Lane, Smallville, Kansas

Full Address. Use this parameter if the accurate address parts (country/state/city…) are not available.

age

26-29

String, an exact (YY) or approximate (YY-YY) age.

Example

https://api.pipl.com/search/?email=clark.kent@example.com&key=YOURKEY
from piplapis.search import SearchAPIRequest
request = SearchAPIRequest(email='clark.kent@example.com', api_key='YOURKEY')
response = request.send()
require 'pipl'
response = Pipl::client.search email: 'clark.kent@example.com', api_key: 'YOURKEY'
import com.pipl.api.search.SearchAPIRequest;
import com.pipl.api.search.SearchAPIResponse;
import com.pipl.api.search.SearchConfiguration;

SearchAPIConfiguration configuration = new SearchConfiguration();
configuration.apiKey = 'YOURKEY'

SearchAPIRequest request = new SearchAPIRequest.Builder()
                                               .email("clark.kent@example.com")
  																						 .configuration(configuration)
                                               .build();
SearchAPIResponse response = request.send();
<?php

require_once './piplapis/search.php';

$configuration = new PiplApi_SearchRequestConfiguration();
$configuration->api_key = 'YOURKEY';
  
$request = new PiplApi_SearchAPIRequest(array('email' => 'clark.kent@example.com',
'first_name' => 'Clark',
'last_name' => 'Kent'), $configuration);
$response = $request->send();
using Pipl.APIs.Search;

SearchConfiguration searchConfiguration = new SearchConfiguration(apiKey: "YOURKEY");
SearchAPIRequest request = new SearchAPIRequest(email: "clark.kent@example.com",
firstName: "Clark",
lastName: "Kent", requestConfiguration: searchConfiguration);
SearchAPIResponse response = await request.SendAsync();
curl https://api.pipl.com/search/\?email=clark.kent@example.com\&key=YOURKEY
Suggest Edits

Full Person

 

While the parameters list way is straightforward, it is not enough for advanced searches.

The person search allows you to search with multiple data fields of the same type, and also components that are not available in the basic search parameters search.

Let’s say, for example, you want to search for a person for which you have two addresses: Metropolis, KS and Smallville, KS. Using the simple search, you can’t do that.

For this kind of situations we allow you to search by a fully fledged person object. If you are using one of the client libraries then just build a person object and pass it to the request. Otherwise you need to send a url-encoded JSON string of the person you are looking for.

Rule of thumb

The more data you bring in, the better results you get out.

Example

Say for example we wish to send a Person object with 1 email address and 2 addresses.

{
	"emails": [{
		"address": "clark.kent@example.com"
	}],
	"addresses": [{
		"country": "US",
		"state": "KS",
		"city": "Metropolis"
	}, {
		"country": "US",
		"state": "KS",
		"city": "Smallville"
	}]
}

Example response:

{
    "@http_status_code": 200, 
    "@visible_sources": 2, 
    "@available_sources": 2,
    "@persons_count": 1,
    "@search_id": "0", 
    "query": {
        "emails": [
            {
                "address": "clark.kent@example.com", 
                "address_md5": "2610ee49440fe757e3cc4e46e5b40819"
            }
        ],
        "addresses": [
            {
                "country": "US", 
                "state": "KS", 
                "city": "Metropolis", 
                "display": "Metropolis, Kansas"
            }, 
            {
                "country": "US", 
                "state": "KS", 
                "city": "Smallville", 
                "display": "Smallville, Kansas"
            }
    },
    "available_data": {
       "premium": {
           "jobs": 1,
           "addresses": 2,
           "phones": 1,
           "landline_phones": 1,
           "educations": 1,
           "social_profiles": 2,
           "names": 2,
           "dobs": 1,
           "images": 1,
           "genders": 1,
           "emails": 1,
        }
    },
    "person": {
        "@id": "f10e8171-6caa-4c45-9553-f14122c762e7", 
        "names": [
            {
                "first": "Clark", 
                "middle": "Joseph", 
                "last": "Kent", 
                "display": "Clark Joseph Kent"
            }, 
            {
                "first": "Kal", 
                "last": "El", 
                "display": "Kal El"
            }
        ], 
        "emails": [
            {
                "address": "clark.kent@example.com", 
                "address_md5": "2610ee49440fe757e3cc4e46e5b40819"
            }
        ], 
        "phones": [
            {
                "@type": "home_phone", 
                "country_code": "1", 
                "number": "9785550145", 
                "display": "(978) 555-0145", 
                "display_international": "+1 978-555-0145"
            }
        ], 
        "gender": {
            "content": "male"
        }, 
        "dob": {
            "date_range": {
                "start": "1986-01-01", 
                "end": "1987-05-13"
            }, 
            "display": "28 years old"
        },
        "addresses": [
            {
                "country": "US", 
                "state": "KS", 
                "city": "Smallville", 
                "street": "Hickory Lane", 
                "house": "10", 
                "apartment": "1", 
                "zip_code": "66605", 
                "display": "10-1 Hickory Lane, Smallville, Kansas"
            }, 
            {
                "@type": "work", 
                "country": "US", 
                "state": "KS", 
                "city": "Metropolis", 
                "street": "Broadway", 
                "house": "1000", 
                "apartment": "355", 
                "display": "1000-355 Broadway, Metropolis, Kansas"
            }
        ], 
        "jobs": [
            {
                "title": "Field Reporter", 
                "organization": "The Daily Planet", 
                "industry": "Journalism", 
                "date_range": {
                    "start": "2000-12-08", 
                    "end": "2012-10-09"
                }, 
                "display": "Field Reporter at The Daily Planet (2000-2012)"
            }
        ], 
        "educations": [
            {
                "degree": "B.Sc Advanced Science", 
                "school": "Metropolis University", 
                "date_range": {
                    "start": "2005-09-01", 
                    "end": "2008-05-14"
                }, 
                "display": "B.Sc Advanced Science from Metropolis University (2005-2008)"
            }
        ], 
        "images": [
            {
                "url": "http://vignette1.wikia.nocookie.net/smallville/images/e/ea/Buddies_forever.jpg", 
                "thumbnail_token": "AE2861B242686E7BD0CB4D9049298EB7D18FEF66D950E8AB78BCD3F484345CE74536C19A85D0BA3D32DC9E7D1878CD4D341254E7AD129255C6983E6E154C4530A0DAAF665EA325FC0206F8B1D7E0B6B7AD9EBF71FCF610D57D"
            }
        ], 
        "urls": [
            {
                "@domain": "linkedin.com", 
                "@category": "professional_and_business", 
                "url": "https://www.linkedin.com/pub/superman/20/7a/365"
            }, 
            {
                "@domain": "facebook.com", 
                "@category": "personal_profiles", 
                "url": "https://www.facebook.com/superman"
            }
        ]
    }
}

Example request:

https://api.pipl.com/search/?person={"emails":[{"address": "clark.kent@example.com"}],"addresses":[{"country":"US", "state": "KS", "city": "Metropolis"},{"country":"US", "state": "KS", "city": "Smallville"}]}&key=YOURKEY
from piplapis.search import SearchAPIRequest
from piplapis.data import Person
from piplapis.data.fields import Address, Email

person = Person()
person.emails.append(Email("clark.kent@example.com"))
person.addresses.extend([Address(city="Metropolis", country="US", state="KS"),
                         Address(city="Smallville", country="US", state="KS")])
request = SearchAPIRequest(person=person, api_key='YOURKEY')
response = request.send()
require 'pipl'
person = Pipl::Person.new
person.add_field Pipl::Name.new(first: 'Clark', last: 'Kent')
person.add_field Pipl::Address.new(country: 'US', state: 'KS', city: 'Smallville')
person.add_field Pipl::Address.new(country: 'US', state: 'KS', city: 'Metropolis')

response = Pipl::client.search person: person, api_key: 'YOURKEY'
import java.util.ArrayList;
import java.util.List;
import com.pipl.api.search.SearchAPIRequest;
import com.pipl.api.search.SearchConfiguration;
import com.pipl.api.data.containers.Person;
import com.pipl.api.data.fields.*;

SearchAPIConfiguration configuration = new SearchConfiguration();
configuration.apiKey = 'YOURKEY'

List<Field> fields = new ArrayList<Field>();
fields.add(new Name.Builder().first("Clark").last("Kent").build());
fields.add(new Address.Builder().country("US").state("KS").city("Smallville").build());
fields.add(new Address.Builder().country("US").state("KS").city("Metropolis").build());
fields.add(new Job.Builder().title("Field Reporter").build());
Person person = new Person(fields);
SearchAPIRequest request = new SearchAPIRequest(person, configuration);
SearchAPIResponse response = request.send()
<?php

require_once './piplapis/search.php';
$configuration = new PiplApi_SearchRequestConfiguration();
$configuration->api_key = 'YOURKEY';

$fields = array(new PiplApi_Address(array("country" => "US", "state" => "KS", "city" => "Metropolis")),
                new PiplApi_Address(array("country" => "US", "state" => "KS", "city" => "Smallville")),
                new PiplApi_Name(array("first" => "Clark", "middle" => "Joseph", "last" => "Kent")),
                new PiplApi_Job(array("title" => "Field Reporter")),
);
$person = new PiplApi_Person($fields);
$request = new PiplApi_SearchAPIRequest(array('person' => $person), $configuration);
$response = $request->send();
using Pipl.APIs.Data.Containers;
using Pipl.APIs.Data.Fields;
using Pipl.APIs.Search;

SearchConfiguration searchConfiguration = new SearchConfiguration(apiKey: "YOURKEY");

var fields = new List<Field>()
{
    new Name(first: "Clark", last: "Kent"),
    new Address(country: "US", state: "KS", city:"Smallville"),
    new Address(country: "US", state: "KS", city:"Metropolis"),
    new Job(title: "Field Reporter")
};

Person person = new Person(fields);
var request = new SearchAPIRequest(person: person, requestConfiguration: configuration);
var response = request.SendAsync().Result;
curl https://api.pipl.com/search/ \
 -d person='{"emails":[{"address": "clark.kent@example.com"}],"addresses":[{"country":"US", "state": "KS", "city": "Metropolis"},{"country":"US", "state": "KS", "city": "Smallville"}]}' \
 -d key=YOURKEY
Suggest Edits

Search pointer

 

Each person returned in an API response, will have a special attribute called “search pointer”. This string can be used for two purposes:

  • If the person was a possible person - run a follow-up search, which will pull up more data about this person.
  • If the person was a match - use the search pointer to cache a reference to this person. Searching by the search pointer will almost always return the same person again.

To search using the search pointer, send it as a POST parameter to the API endpoint. Using HTTP GET is also possible, but will not work with the longer search pointers.

Example

Replace SEARCH_POINTER_STRING with a valid search pointer

curl http://api.pipl.com/search/ \
 -d search_pointer='SEARCH_POINTER_STRING' \
 -d key=YOURKEY
from piplapis.search import SearchAPIRequest

request = SearchAPIRequest(search_pointer='SEARCH_POINTER_STRING', api_key="YOURKEY")
response = request.send()
require 'pipl'

response = Pipl::client.search search_pointer: 'SEARCH_POINTER_STRING', api_key: 'YOURKEY'
import com.pipl.api.search.SearchAPIRequest;
import com.pipl.api.search.SearchAPIResponse;
import com.pipl.api.search.SearchConfiguration;

SearchAPIConfiguration configuration = new SearchConfiguration();
configuration.apiKey = 'YOURKEY'

SearchAPIRequest request = new SearchAPIRequest("SEARCH_POINTER_STRING", configuration);
SearchAPIResponse response = request.send()
<?php

require_once './piplapis/search.php';

$configuration = new PiplApi_SearchRequestConfiguration();
$configuration->api_key = 'YOURKEY';

$request = new PiplApi_SearchAPIRequest(array('search_pointer' => 'SEARCH_POINTER_STRING'), $configuration);
$response = $request->send();
using Pipl.APIs.Search;

SearchConfiguration searchConfiguration = new SearchConfiguration(apiKey: "YOURKEY");
var request = new SearchAPIRequest(searchPointer: "SEARCH_POINTER_STRING", requestConfiguration: searchConfiguration);
var response = request.SendAsync().Result;
http://api.pipl.com/search/?search_pointer=SEARCH_POINTER_STRING&key=YOURKEY
Suggest Edits

Match criteria

 

Normally, you would pay for each API request that resulted in a match, where a match is either a perfect match, or a list of possible persons.

You can exercise control over your bill by specifying a minimum criteria which a person must meet, in order to be returned. If the criteria isn’t met, you will receive an empty response and won’t be charged.

There are two search parameters to define criteria:

  • match_requirements, and
  • source_category_requirements

MATCH REQUIREMENTS

You can use any one (or more) of these field names in your condition as the most atomic expression:

  • name
  • address
  • phone
  • email
  • job
  • education
  • image
  • username
  • user_id
  • dob
  • url
  • gender
  • ethnicity
  • language
  • origin_country
  • social_profile

The criteria will be met if the response contains the requested field.

ATOMIC EXPRESSION VARIATIONS

  • You can prefix any field name with “new_”, in which case the criteria will only be met if the response includes data of that type which was not included in the original query.
  • You can append “.TYPENAME” to any field name, where TYPENAME is any recognized @type value of the data field. For example phone.mobile or address.work

Example

If your query is clark.kent@example.com, and you ask for new_emails - you’ll only get a response if it contains emails other than clark.kent@example.com.

SOURCE CATEGORY REQUIREMENTS

You can use any of the source categories as the atomic expression. The criteria will be met if the response contains at least one person (perfectly matching or a possible person) which includes a source of the requested category (please note that in order to see the sources, you will need to set the show_sources parameter).

PARSING

When we receive a match requirement criteria, we parse it based on the following rules:

  • An expression is either one atomic expression (field name or source category), or a combination of many, using the following operators.
    • Parenthesis allow creating more complex rules. Whatever is inside a parenthesis will be evaluated to a truth value before the outer condition.

Operators

  • & or AND: Both the preceding and the following expressions must be met.
  • | or OR: Either the preceding or the following expression must be met.

Structuring rules

An expression may be either one atomic expression, or two or more atomic expressions combined using operators and parenthesis.

curl http://api.pipl.com/search/ \
    -d email=clark.kent@example.com
    -d match_requirements=emails
    -d source_category_requirements=publications or personal_profiles


curl http://api.pipl.com/search/ \
    -d email=clark.kent@example.com
    -d match_requirements=(emails or phones)


curl http://api.pipl.com/search/ \
    -d email=clark.kent@example.com
    -d match_requirements=(emails and jobs)
    -d source_category_requirements=professional_and_business

curl http://api.pipl.com/search/ \
    -d email=clark.kent@example.com
    -d match_requirements=(names and addresses) or emails
 

A search response may contain either a person object, or a list of possible persons, depending on our confidence level that we can match your search to a single person.

Typically, a single person response will contain more data about the person than a possible person object. To pull up all the data about a possible person, you’ll need to run a search using its search pointer.

 

A search response contains the following top-level fields:

Property
Type
Explanation

@http_status_code

Integer

The HTTP status code of the response. Successful calls will be 200.

@visible_sources

Integer

The number of sources returned in the sources array (if show_sources is not false).

@available_sources

Integer

The number of sources we know of that are relevant to the search.

@persons_count

Integer

The number of persons returned in this API response

@search_id

String

An internal ID which identifies the search on our systems. Useful for debugging.

query

Person

A person object representing your search parameters. Useful to see how we understood your search

match_requirements

String

The canonical way to express the match requirement you’ve sent. Useful to see how we’ve parsed your criteria.

available_data

An available_data object. A summary of the data we have for this search.

error

String

An error message, explaining an error that prevented your search from being run.

warnings

Array

An array of warning strings.

person

Person

A person object containing the data about the person you are searching for - if a single person was matched to your query.

possible_persons

Array

An array of person objects containing possible matches.

sources

Array

An array of source objects, in case you need to see where the data came from.

Metadata

Metadata is prefixed with the '@' character

 

Sometimes the API encounters errors which do not prevent it from running the search. In this case, we will return a warning. The warnings may also include useful hints on how to optimize searches and get better results.

It is a good practice to log the warnings and review them every once in a while.

In some circumstances the search query cannot be executed. In this case the API will return an error.

Error codes you can expect to see:

Status Code
Description

400

Bad Request - either we could not decode your search request, or it did not contain enough data for a search.

403

Calls Exceeded - you have either been rate limited or you’ve reached your key quota, organization spend limit, or your account has been suspended.

500

Any other internal error.

Below is a table indicating the error message to expect to see for each error type:

Status Code
Error Type
Error
Resolution

400

Bad Request

The query does not contain any valid name/username/phone/email to search by

Check the warnings returned, and make sure the search request meets the minimum requirement

403

Spend Limit reached

You have reached your monthly spend limit.

Please contact your account manager

403

Account suspended

Your API usage has been suspended. Please contact your account manager or support@pipl.com

Please contact your account manager or support@pipl.com

403

Rate Limited: Per second limit reached (without live feeds)

Per second limit for total calls reached.

You are making too many calls per second. Implement a throttling mechanism. Use the HTTP headers and adhere to the rate limits

403

Rate Limited: Per second limit reached (with live feeds)

Per second limit for live calls reached.

You are making too many calls per second. Implement a throttling mechanism. Use the HTTP headers and adhere to the rate limits

403

Daily API key quota reached

Daily quota reached.

Change your key quota limit as required, or wait until the quota resets the following month

403

Weekly API key quota reached

Weekly quota reached.

Change your key quota limit as required, or wait until the quota resets the following month

403

Monthly API key quota reached

Monthly quota reached.

Change your key quota limit if required, or wait until the quota resets the following month

403

Demo quota reached

You have exceeded your demo usage allowance.

Enter a payment method and upgrade to production ready keys

403

Rate Limited: Per second limit reached on demo key

Per second limit for demo calls reached.

Enter a payment method and upgrade to production ready keys

403

SSL required

SSL is required to perform this operation. Please use https.

Change your protocol to use HTTPS. If you are using one of Pipl's Code Libraries please upgrade and/or set the flag to use https in configuration

500

Internal error

Internal Server Error

Please contact your integration specialist

Example Request: First name without last name

curl http://api.pipl.com/search/\?key=YOURKEY\&first_name=Clark
from piplapis import search
search.SearchAPIRequest(first_name="Clark", api_key="YOURKEY").send()
require 'pipl'
response = Pipl::client.search first_name: 'Clark', api_key: "YOURKEY"
import com.pipl.api.search.SearchAPIRequest;
import com.pipl.api.search.SearchAPIResponse;
import com.pipl.api.search.SearchConfiguration;

SearchAPIConfiguration configuration = new SearchConfiguration();
configuration.apiKey = 'YOURKEY'

SearchAPIRequest request = new SearchAPIRequest.Builder().firstName("Clark").configuration(configuration).build();
SearchAPIResponse response = request.send()
<?php

require_once './piplapis/search.php';

$configuration = new PiplApi_SearchRequestConfiguration();
$configuration->api_key = 'YOURKEY';

$request = new PiplApi_SearchAPIRequest(array('first_name' => 'Clark'), $configuration);
$response = $request->send();
using Pipl.APIs.Search;

SearchConfiguration searchConfiguration = new SearchConfiguration(apiKey: "YOURKEY");

var request = new SearchAPIRequest(firstName: "Clark", requestConfiguration: searchConfiguration);
var response = request.SendAsync().Result;
http://api.pipl.com/search/?first_name=Clark&key=YOURKEY

Example Response: Error 400 - Bad Request

{
    "@http_status_code": 400, 
    "warnings": [
        "Parameter `first_name` ignored"
    ], 
    "error": "The query does not contain any valid name/username/phone/email to search by"
}

Example Response: Error 403 - Spend limit reached

{
    "@http_status_code": 403, 
    "error": "You have reached your monthly spend limit."
}

Example Response: Error 403 - Demo key quota reached

{
    "@http_status_code": 403, 
    "error": "You have exceeded your demo usage allowance."
}

Example Response: Error 403 - Account suspended

{
    "@http_status_code": 403, 
    "error": "Your API usage has been suspended. Please contact your account manager or support@pipl.com"
}
{
    "@http_status_code": 500, 
    "warnings": [], 
    "error": "Internal Server Error"
}
Suggest Edits

Rate Limiting Information

 

Your query may be limited in the following circumstances:

  • You have reached your monthly spend limit.
  • You are using a demo key and have exceeded your demo usage allowance.
  • You are making too many calls per second.
  • You have hit your daily, weekly or monthly key quota limit.

For your convenience, we are showing limit information as HTTP response headers:

Header
Description

X-QPS-Allotted

The number of queries you are allowed to do per second.

X-QPS-Current

The number of queries you have run this second.

X-QPS-Live-Allotted

The number of live queries you are allowed to do per second.

X-QPS-Live-Current

The number of live queries you have run this second.

X-QPS-Demo-Allotted

The number of demo queries you are allowed to do per second.

X-QPS-Demo-Current

The number of demo queries you have run this second.

X-Demo-Usage-Allotted

The number of queries you can make with demo keys

X-Demo-Usage-Current

The number of queries you made with demo keys.

X-Demo-Usage-Expiry

The time (in UTC) when your demo allowance will expire.

X-APIKey-Quota-Allotted

Your API key’s quota limit.

X-APIKey-Quota-Current

Your API key’s used quota.

X-Quota-Reset

The time (in UTC) that your quota will be reset.

Example Response: Error 403 - Per second limit reached (without live)

X-QPS-Current > X-QPS-Allotted

{
    "@http_status_code": 403, 
    "error": "Per second limit for total calls reached."
}

Example Response: Error 403 - Per second limit reached (with live)

X-QPS-Live-Current > X-QPS-Live-Allotted

{
    "@http_status_code": 403, 
    "error": "Per second limit for live calls reached."
}

Example Response: Error 403 - Per second limit reached on demo key

X-QPS-Demo-Current > X-QPS-Demo-Allotted

{
    "@http_status_code": 403, 
    "error": "Per second limit for demo calls reached."
}
Suggest Edits

Response Metadata

 
Suggest Edits

Available Data

 

This object contains the summary of the data for this search. It allows you to quickly see what data can be or was returned depending on the key you searched with.

"available_data": {
  "premium": {a FieldCount object}
}
Suggest Edits

Field Count

 

A FieldCount object is used to store the sum of data types within a person or a list of possible persons. It may be a summary of a single person, or a sum of data within a list of possible persons.

Member
Type
Description

emails

Integer

The sum of emails.

relationships

Integer

The sum of relationships.

usernames

Integer

The sum of usernames.

user_ids

Integer

The sum of user ids.

jobs

Integer

The sum of jobs.

addresses

Integer

The sum of addresses.

ethnicities

Integer

The sum of ethnicities.

phones

Integer

The sum of both mobile and landline phones.

mobile_phones

Integer

The sum of mobile phones

landline_phones

Integer

The sum of landline (non-mobile) phones.

educations

Integer

The sum of educations.

languages

Integer

The sum of languages.

social_profiles

Integer

The sum of social profile sources.

names

Integer

The sum of names.

dobs

Integer

The sum of dates of birth.

images

Integer

The sum of images.

genders

Integer

The sum of genders.

origin_countries

Integer

The sum of origin countries.

"available_data": {
        "premium": {
            "relationships": 7, 
            "usernames": 2, 
            "jobs": 14, 
            "addresses": 11, 
            "phones": 6, 
            "mobile_phones": 2, 
            "landline_phones": 4, 
            "educations": 2, 
            "languages": 1, 
            "user_ids": 6, 
            "social_profiles": 5, 
            "names": 1, 
            "dobs": 1, 
            "images": 4, 
            "genders": 1, 
            "emails": 6
        }
    }
Suggest Edits

Containers

 

This object represents a single real world person. It contains a summary of all the information we have on that person. We do our best to merge relevant pieces of information together and remove duplicates.

Attribute
Type
Description

@id

GUID

An identifier of this person in this response. To be used in conjunction with @person_id in the Source object. Only shown if the response includes a single person object.

@inferred

Boolean

Whether this person is made up solely from data inferred by statistical analysis from your search query. You can control inference using the minimum_probability parameter, and inference of persons using the infer_persons parameter.

@search_pointer

String

A special string crafted by the API for follow up searches.

@match

Float

0-1. The level of confidence we have that this is the person you’re looking for.

DATA

Member
Type
Description

names

Array of names

emails

Array of emails

usernames

Array of usernames

phones

Array of phones

gender

A gender object

dob

A date of birth object

languages

Array of languages

ethnicities

Array of ethinicities

origin_countries

addresses

Array of addresses

jobs

Array of jobs

educations

Array of educations

relationships

Array of relationships

user_ids

Array of user ids

images

Array of images

urls

Array of urls

A Person object

{
  "@id": GUID,
  "@search_pointer": "string",
  "@match": float,
  "names": [],
  "emails": [],
  "usernames": [],
  "phones": [],
  "gender": {},
  "dob": {},
  "languages": [],
  "ethnicities": [],
  "origin_countries": [],
  "addresses": [],
  "jobs": [],
  "educations": [],
  "relationships": [],
  "user_ids": [],
  "images": [],
  "urls": []
}

A Source is all the information on the person gathered from a single data source.

Source visibility

In order to get source objects in response, set the show_sources request parameter to “all” or “matching”.

If using show_sources="all", sources with a person_id are those sources used to build the response person.

METADATA

Attribute
Type
Description

@id

String

Unique identifier of this source in our systems. Useful for debugging

@name

String

Data Source name.

@category

String

Data Source category.

@domain

String

Data Source domain.

@person_id

GUID

The id of the person this source belongs to.

@sponsored

Boolean

Indicating whether additional data from this source is available behind a website paywall. Omitted if false.

@origin_url

String

The url of the web page holding this information. Only shown if the data is available online.

@match

Float

0-1. The match score of the person this source belongs to.

@premium

Boolean

Whether this is a premium data source. Omitted if false.

CATEGORIES

We categorise sources into nine categories.

Category
Examples

personal_profiles

facebook.com, pinterest.com, last.fm.

media

picasa.com, flickr.com, youtube.com

professional_and_business

linkedin.com, spoke.com, zoominfo.com

public_records

bop.gov, archives.com, ancestry.com

publications

uspto.gov, portal.acm.org, scirus.com

school_and_classmates

classmates.com, reunion.com, schoolbank.nl

email_address

intelius.com, spokeo.com

background_reports

peoplefinders.com intelius.com peoplesmart.com

contact_details

whitepages.com, addresses.com, anywho.com

web_pages

Default category, for sources that don’t match any of the above categories.

DATA

Member
Type
Description

names

Array of names

emails

Array of emails

usernames

Array of usernames

phones

Array of phones

gender

A gender object

dob

A date of birth object

languages

Array of languages

ethnicities

Array of ethinicities

origin_countries

addresses

Array of addresses

jobs

Array of jobs

educations

Array of educations

relationships

Array of relationships

user_ids

Array of user ids

images

Array of images

urls

Array of urls

tags

Array of tags

A Source object

{
  "@id": "string",
  "@name": "string",
  "@category": "string",
  "@domain": "string",
  "@person_id": "GUID",
  "@sponsored": false,
  "@origin_url": "string",
  "@match": float,
  "names": [],
  "emails": [],
  "usernames": [],
  "phones": [],
  "gender": {},
  "dob": {},
  "languages": [],
  "ethnicities": [],
  "origin_countries": [],
  "addresses": [],
  "jobs": [],
  "educations": [],
  "relationships": [],
  "user_ids": [],
  "images": [],
  "tags": []
}
Suggest Edits

Data Fields

 

Data fields present the actual data we have about the person.

Common metadata attributes to all fields:

Attribute
Type
Description

@valid_since

Date

The date we were first aware of the data in this field. Format is YYYY-MM-DD.

@last_seen

Date

The date we last saw the data in this field. Format is YYYY-MM-DD.

@current

Boolean

A Boolean indication whether this field holds data valid at the time of the request. Can be True, False, or omitted if unknown.

@inferred

Boolean

A Boolean indication whether this field was inferred using statistical analysis or was explicitly found in one of our data sources. Omitted if false.

Required plan

Available in all plans

Component
Type
Description

@type

String

Either one of ‘present’, 'maiden’, 'former’ or 'alias’. Default is 'present’

first

String

First name.

middle

String

Middle name or middle initial.

last

String

Last name.

prefix

String

A person’s title.

suffix

String

Additional information about a person.

raw

String

An unparsed person’s full name. Request only.

display

String

The full name for display purposes. Response only.

SEARCH REQUIREMENTS

The minimal requirement for a name to be sufficient for a search is that it must contain both a first and a last name of length > 1.

RAW NAME PARSING

When you don’t know the breakdown of a name string to its components, don’t worry. Just fill in the raw member of the name object and we will do name parsing for you.

Note that if you provide a raw name and, in the same time, provide both first and last names we will ignore the raw name. If you only provide one of them then we will use the raw name.

To see the final result of the parsing, take a look at the query member of the response object it holds the final person that we have searched for

{
  "@valid_since": "2012-01-01",
  "first": "Clark",
  "middle": "Joseph",
  "last": "Kent",
  "display": "Clark Joseph Kent"
}
 

Required plan

Available in all plans

Component
Type
Description

@type

String

Either one of 'home’, 'work’ or 'old’. Default is 'home’

country

String

Alpha-2 ISO 3166 country code

state

String

2 letters state code, if country is one of US, Canada or Brazil. 3 letters state code if country is Australia or UK.

city

String

City name

street

String

Street name

house

String

House number

apartment

String

Apartment number

zip_code

String

Postal zip code

po_box

String

Post Office box number

raw

String

An unparsed full address. Request only.

display

String

The full address for display purposes. Response only.

SEARCH REQUIREMENTS

The minimal requirement for an address to be helpful in a search is that it must contain a known country. If you provide only a city, or a state, we will try to complete the rest of the information.

For an address to be sufficient for a search as the single parameter, it must be a valid US address and contain a street & house number as well as a city and state. Please note that searching by multiple addresses as the only parameters is not possible, nor is searching by non-US addresses.

RAW ADDRESS PARSING

When you don’t know the breakdown of an address string to its components, don’t worry. Just fill in the raw member of the address object and we will do the parsing for you.

To see the final result of the parsing take a look at the query member of the response object, it holds the final person that we have searched for.

{
    "@valid_since": "1999-02-01", 
    "country": "US", 
    "state": "KS", 
    "city": "Smallville", 
    "street": "Hickory Lane", 
    "house": "10", 
    "apartment": "1", 
    "zip_code": "66605", 
    "display": "10-1 Hickory Lane, Smallville, Kansas"
}

Required plan

Landline phones are available in all plans, mobile phones in the BUSINESS plan only.

Component
Type
Description

@type

String

One of 'mobile’, 'home_phone’, 'home_fax’, 'work_phone’,'work_fax’ or 'pager’. No default value.

@do_not_call

Boolean

When the indicator is marked as true, this indicates that the US phone number is listed in the National Do Not Call Registry and should not to be contacted for telemarketing purposes.

This indicator can be used solely for the purpose of complying with the US law for preventing phone calls to numbers listed on the DNC list.

We constantly update the DNC registry to be current, this indication should only be used at the same day the API response was received.

country_code

Integer

International call country code. See ITU-T Recommendation E.164

number

Integer

Phone number.

extension

Integer

Extension.

raw

String

An unparsed phone. Request only.

display

String

The full national phone for display purposes. Response only.

display_international

String

The full international phone for display purposes. Response only.

SEARCH REQUIREMENTS

For a phone object to be sufficient for a search, it needs to be a valid number. It should contain either a raw phone string, or a number & country code.

RAW PHONE PARSING

To search using a raw phone number, fill in the raw member of the phone object and we will do the parsing for you. We are using libphonenumber for phone number parsing.

To see the final result of the parsing take a look at the query member of the response object, it holds the final person that we have searched for.

{
  "country_code": 1,
  "number": 9785550145,
  "@type": "home_phone",
  "display": "(978) 555-0145",
  "display_international": "+1 978-555-0145",
}

Required plan

Available only in the BUSINESS plan.

Component
Type
Description

@type

String

Either one of 'personal’ or 'work’. Default is 'personal’.

address

String

Valid email address in simple form. No brackets of any kind.

address_md5

String

MD5 hash of the address.

@disposable

Boolean

Whether this is a disposable email (for example guerillamail.com). Response only. Omitted if false.

@email_provider

Boolean

Whether this email came from a public provider (such as gmail.com). Response only.

SEARCH REQUIREMENTS

For an email object to be sufficient for a search is that it must contain a valid email address or an MD5 hash of a valid email address.

MD5 CALCULATION GUIDELINES

When sending an MD5 hash of an email address, we recommend normalizing the email before calculating the hash:

  • The entire email should be in lowercase.
  • If the username contains a plus (+) character, remove it and any trailing character (so clark.kent+something@example.com will become clark.kent@example.com).
  • For Gmail addresses only:
    • If the email domain ends with "googlemail.com", replace this with "gmail.com".
    • Remove any dots in the username.
{
	"@type": "work",
	"@email_provider": false,
	"address": "clark.kent@thedailyplanet.com",
	"address_md5": "eb3e11de3c9cefc2d9d70972350e2b28"
},
{
	"@disposable": true,
	"@email_provider": false,
	"address": "ck242@guerrillamail.com",
	"address_md5": "999e509752141a0ee42ff455529c10fc"
},
{
	"@type": "personal",
	"@email_provider": true,
	"address": "clark@gmail.com",
	"address_md5": "501548362894b9a08f071b1565d8aa14"
}
 

Required plan

Available only in the SOCIAL plan and up.

A handle / screen name / nick used to identify a user online. Note that even though in many sites the username uniquely identifies one person - it is not guaranteed as some sites allow different people to use the same username.

Component
Type
Description

content

String

A person’s username at one or more online service.

Know the service for the username?

  1. A username search allows for an optional @service suffix similar to the User ID format. The format to be used is username@service, for example superman@facebook. See User ID for a list of known services.

  2. By prefixing a username with an @ symbol, the service is considered to be twitter, for example @superman.

SEARCH REQUIREMENTS

For a username object to be sufficient for a search its content attribute should have a string without whitespace with length >= 3.

{
  "content": "superman"
}
 

Required plan

Available only in the SOCIAL plan and up.

The ID is a string that’s used by to uniquely identify a person, It’s guaranteed that in a single identity provider this string identifies exactly one person. An identity provider may be a website such as a social network, a government (for national IDs), or something else.

Component
Type
Description

content

String

A person’s user id in the format of user_id@service.

SEARCH REQUIREMENTS

For a user id to be sufficient for a search, its content attribute needs to include “@SERVICE” with service being one of the known services..

LIST OF KNOWN SERVICES

Note

The following list is a dynamic list, and new services may be added at any time.

facebook, linkedin, twitter, myspace, foursquare, ebay, google, pinterest, instagram, lastfm, flickr, youtube, digg tagged, hi5, weeworld, delicious, hyves, deviantart, douban, odnoklassniki, quora, xanga, mylife, gaia, stumbleupon, bebo, livejournal, viadeo, ning, myheritage, qzone, vkontakte, flixster, tumblr, myyearbook, badoo, habbo, xing, sonico, friendster, meetup, goodreads, classmates, renren, cyworld, netlog, soundcloud, yelp, orkut, aboutme, flavorsme, freelancer, gravatar, imgur, github, CPF.

{
  "content": "11231@facebook"
}
Suggest Edits

Date of birth

 

Required plan

Available in all plans

The date-of-birth (DOB) of the person as a Date Range. The exact date is within the range, if the exact date is known the range will simply be with start=end.

Component
Type
Description

date_range

See Date Range for more details.

display

String

The person’s estimated age represented by this DOB for display purposes. For example, '47 years old’. If age > 80 the format is 'Born 1927’. Response only.

SEARCH REQUIREMENTS

For a DOB to be useful for a search, it must contain a valid Date Range.

Both start and end must be valid dates in 'YYYY-MM-DD’ format, start <= end.

If you have a specific date just put it in both the start and the end of the Date Range.

{
  "date_range": {
    "start": "1986-01-01",
    "end": "1987-05-13"
  },
  "display": "28 years old"
}

Required plan

Available only in the SOCIAL plan and up.

A handle / screen name / nick used to identify a user online. Note that even though in many sites the username uniquely identifies one person - it is not guaranteed as some sites allow different people to use the same username.

Component
Type
Description

url

String

Image URL

thumbnail_token

String

A special token that can be used with our thumbnail server.

SEARCH REQUIREMENTS

Image objects are not used by the API for search.

A NOTE ABOUT THUMBNAILS

Each image field in our API responses includes a special token which can be sent to our thumbnail servers. You can specify the exact parameters depending on your needs. The base URL of our thumbnail server is: https://thumb.pipl.com/image

Parameters for the thumbnail server:

Parameter
Type
Description

token

String

The thumbnail token. Send as is, do not url-encode it.

tokens

String

Two thumbnail tokens, separated by a comma. Either this or the token parameter is required.

height (required)

Integer

Height in pixels. Integer between 100-500.

width (required)

Integer

Width in pixels. Integer between 100-500.

favicon

Boolean

Whether to show favicon.

zoom_face

Boolean

Whether to enable face zoom.

{
  "url": "http://vignette1.wikia.nocookie.net/smallville/images/e/ea/Buddies_forever.jpg",
  "thumbnail_token": "AE2861B242686E7BD0CB4D9049298EB7D18FEF66D950E8AB78BCD3F484345CE74536C19A85D0BA3D32DC9E7D1878CD4D341254E7AD129255C6983E6E154C4530A0DAAF665EA325FC0206F8B1D7E0B6B7AD9EBF71FCF610D57D"
}

Getting the Thumbnail URL with client libraries

from piplapis.search import SearchAPIRequest
from piplapis.data import Image
response = SearchAPIRequest(email='clark.kent@example.com').send()
thumbnail_url = response.image.get_thumbnail_url(200, 100, zoom_face=True, favicon=True)
require 'pipl'
request = PiplApi::SearchAPIRequest.new({ :email => 'clark.kent@example.com' })
response = request.send()
response.image.thumbnail_url width: 200, height: 100, favicon: true, zoom_face: true
import com.pipl.api.search.SearchAPIRequest;
SearchAPIRequest request = new SearchAPIRequest.Builder().email("clark.kent@example.com").build();
SearchAPIResponse response = request.send()
String thumbUrl = response.image().getThumbnailUrl(200, 100, true, true);
<?php

require_once './piplapis/search.php';
$request = new PiplApi_SearchAPIRequest(array('email' => 'clark.kent@example.com'));
$response = $request->send();
$thumbUrl = $response->image()->get_thumbnail_url(200, 100, true, true);
using Pipl.APIs.Search;

var request = new SearchAPIRequest(email: "clark.kent@example.com");
var response = request.SendAsync().Result;
var thumbUrl = response.Image.GetThumbnailUrl(200, 100, true, true);

Required plan

Available only in the BUSINESS plan.

Component
Type
Description

title

String

Job title

organization

String

The name of the employing organization

industry

String

The employing organization industry

date_range

Period of employment. Date ranges might be partial to designate current job or an unknown start date. See Date Range for more details.

display

String

The full job headline for display purposes. Response only.

SEARCH REQUIREMENTS

For a Job object to be useful for a search, it must contain either a title or an organization.

{
  "title": "Field Reporter",
  "organization": "The Daily Planet",
  "industry": "Journalism",
  "date_range": {
    "start": "2000-12-08",
    "end": "2012-10-09"
  },
  "display": "Field Reporter at The Daily Planet (2000-2012)"
}
Suggest Edits

Education

 

Required plan

Available only in the BUSINESS plan.

Component
Type
Description

degree

String

Degree. B.Sc, PhD, etc…

school

String

Name of the educational institute.

date_range

Period of study. Date ranges might be partial to designate current study or an unknown start date. See Date Range for more details.

display

String

The full degree headline for display purposes. Response only.

SEARCH REQUIREMENTS

For an Education object to be useful for a search, it must contain at least a school.

{
  "degree": "B.Sc in Chemistry",
  "school": "Metropolis University",
  "date_range": {
    "start": "2005-09-01",
    "end": "2008-05-14"
  },
  "display": "B.Sc in Chemistry from Metropolis University (2005-2008)"
}

Required plan

Available in all plans

Component
Type
Description

content

String

Either one of 'male’ or 'female’. No default value

SEARCH REQUIREMENTS

For a Gender object to be useful for a search, it must include valid value ('male’ or 'female’).

{
  "content": "male"
}
Suggest Edits

Ethinicity

 

Required plan

Available in all plans

Coming soon

Ethnicity data is not yet available.

Component
Type
Description

content

String

One of the following: 'white’, 'black’, 'american_indian’, 'alaska_native’, 'chinese’, 'filipino’, 'other_asian’, 'japanese’, 'korean’, 'vietnamese’, 'native_hawaiian’, 'guamanian’, 'chamorro’, 'samoan’, 'other_pacific_islander’, 'other’.

SEARCH REQUIREMENTS

Ethnicity objects are not used by the API for search.

{
  "content": "white"
}
 

Required plan

Available in all plan.

Component
Type
Description

language

String

A 2-letter language code

region

String

Country code

display

String

The representation of this language (for example “en_US”)

SEARCH REQUIREMENTS

Language objects are not used by the API for search.

{
  "language": "en",
  "region": "US",
  "display": "en_US"
}
Suggest Edits

Origin Country

 

Required plan

Available in all plan.

Component
Type
Description

country

String

A country code.

SEARCH REQUIREMENTS

Origin Country objects are not used by the API for search.

{
  "country": "US"
}
Suggest Edits

Relationship

 

Required plan

Available only in the SOCIAL plan and up.

This field is a bit different as it is basically a short descriptor of another person

Member
Type
Description

@type

String

Either one of 'work’, 'family’, 'friend’ or 'other’. Default is 'friend’

@subtype

String

A free text providing further info on the association. For example, Father.

names

Array of names

emails

Array of emails

usernames

Array of usernames

phones

Array of phones

gender

A gender object

dob

A date of birth object

languages

Array of languages

ethnicities

Array of ethinicities

origin_countries

addresses

Array of addresses

jobs

Array of jobs

educations

Array of educations

relationships

Array of relationships

user_ids

Array of user ids

images

Array of images

SEARCH REQUIREMENTS

For a Relationship object to be useful for a search, it must include at least a valid name object.

{
    "@type": "family", 
    "@subtype": "Adoptive Father", 
    "names": [
        {
            "first": "Jonathan", 
            "last": "Kent", 
            "display": "Jonathan Kent"
        }
    ], 
    "emails": [
        {
            "address": "jkent@example.com", 
            "address_md5": "e81b8844517b6ab307a9e0fdf973ae3a"
        }
    ]
}

Required plan

Available only in the SOCIAL plan and up.

The ID is a string that’s used by a website to uniquely identify a person, It’s guaranteed that in a single website this string identifies exactly one person.

Component
Type
Description

@source_id

String

The source ID (if this URL is a source of data)

@domain

String

The domain

@name

String

The site name.

@category

String

One of: 'background_reports’, 'contact_details’, 'email_address’, 'media’, 'personal_profiles’, 'professional_and_business’, 'public_records’, 'publications’, 'school_and_classmates’, 'web_pages’

url

String

The actual URL

@sponsored

Boolean

Indicating whether additional data from this source is available behind a website paywall. Omitted if false.

SEARCH REQUIREMENTS

URL objects by themselves are not useful for a search, but it is possible to send URLs of a known service (see User ID). We will parse a username or user_id from those URLs, if possible.

{
    "@source_id": "5d836a4acc55922e49fc709c7a39e233", 
    "@domain": "facebook.com", 
    "@name": "Facebook", 
    "@category": "personal_profiles", 
    "url": "http://facebook.com/superman"
}

Required plan

Available in all plans

A general purpose field, holds any meaningful text that’s related to the person. Used for holding data about the person that either couldn’t be clearly classified or was classified as something different than the above fields.

Please note

Please note, tags are only available within Source objects (not persons).

Component
Type
Description

@classification

String

What the content is representing.

content

String

The text.

SEARCH REQUIREMENTS

Tag objects are not used by the API for search.

{
    "@classification": "Vulnerable to:", 
    "content": "Kryptonite"
}
Suggest Edits

Date Range

 

This is not a field, rather a field component. It is used in Date of birth, Job and Education.

Component
Type
Description

start

String

Start date of this range in 'YYYY-MM-DD’ format.

end

String

End date of this range in 'YYYY-MM-DD’ format.

SEARCH REQUIREMENTS

A valid Date Range has both a start and an end date (start <= end).

{
  "start": "2005-09-01",
  "end": "2008-05-14"
}