Skip to main content


The Person Search API is perfect for finding specific segments of people that you need to power your projects and products. It gives you direct access to our full Person Dataset and provides many degrees of freedom, which allow you to find any kind of person(s) with a single query.


The endpoint for the Person Search API is

Person Search API Access and Billing

We charge per record retrieved. Each person record in the data array of the response counts as a single credit against your total package.


See Authentication and Requests to learn how to input requests. We recommend using a JSON object to capture request parameters and will do so in the examples.

Rate Limiting

The current default rate limit is 10 requests per minute.

Input Parameters

query An Elasticsearch (v7.7) query. See our underlying Elasticsearch mapping for reference.   {"query": {"term": {"job_company_name": "people data labs"}}}
sql An SQL query of the format: SELECT * FROM person WHERE XXX, where XXX is a standard SQL boolean query involving our person fields. We will ignore any use of column selections or the LIMIT keyword.   SELECT * FROM person WHERE job_company_name='people data labs'
size The batch size or the maximum number of matched records to return for this query if they exist, which must be between 1 and 100. 1 100
from [LEGACY] An offset value for paginating between batches, which can be a number between 0 and 9999. You can execute pagination for a maximum of 10,000 records per query. NOTE: YOU CANNOT USE FROM WITH SCROLL_TOKEN IN THE SAME REQUEST. 0 0, 100, 200 ...
scroll_token An offset key for paginating between batches. Unlike the legacy from parameter, you can use this parameter for any number of records. Each Person Search API response returns a scroll_token, which you can use to fetch the next size records. None 104$14.278746
dataset Specifies which dataset the API should search against. You can input multiple datasets by separating them with a comma. Valid names are resume, email, phone, mobile_phone, street_address, consumer_social, developer and all. You can also exclude datasets by using - as the first character. resume all
titlecase All text in the data of API responses returns as lowercase by default. Setting titlecase to true will titlecase any records returned. false true
pretty Whether the output should have human-readable indentation. false true
api_key Your secret API key.

Note: you can also provide this in the request header instead, as shown on the Authentication page.

Output Response

The API will return an HTTP response code of 200 for any valid request, regardless of whether it found records for your query or not. For that reason, pay close attention to the total value in your response object to understand query success. Each person record in the data array of the response counts as a single credit against your total package.

Response Fields

status The API response code (see a description of our error codes). Integer
data The person response objects that match the input query (see the example person record). Array (Object)
total The number of records matching a given query or sql input. Integer
scroll_token The scroll token to use to fetch the next batch of results for the query. String
Response Data Structure

The response from the Person Search API will be in this format:

{ "status": 200, "data": [ { "id": "qEnOZ5Oh0poWnQ1luFBfVw_0000", "full_name": "sean thorne", ... }, ... ], "scroll_token": "1117$12.176522", "total": 99 }

See Example Person Record for a full example of the fields included in the data object.


If the request encounters an error, it will instead return an Error Response in the format described in Errors

All Data Field Descriptions

See the Person Schema.

Need an API Key?

If you don't have an API key, you can easily create one by signing up for a self-serve account. For more information, check out our Quickstart Guide, which walks you through the sign-up process as well as shows you how to use the self-serve API dashboard.

Cookie Notice

We and third parties such as our customers, partners, and service providers use cookies and similar technologies (\"cookies\") to provide and secure our Services, to understand and improve their performance, and to serve relevant information. For more information, see our Cookie Policy.

Back to top