Input Parameters - Person Search API

Detailed information on the input parameters for the Person Search API

Required Parameters

You must provide either the query or the sql parameter (but not both) to receive a successful response. We recommend using the Elasticsearch query parameter for most use cases.

When you execute an API request, the query runs directly against our Person Dataset without any cleaning or preprocessing. This means that you have a lot of freedom to explore the dataset and return the perfect records for your particular use case. It also means that you will need to understand the available fields to make successful queries.

You can find field descriptions here and the Elasticsearch mapping underlying them here.

To help you identify how to best query for specific sub-entities (schools, companies, and locations), we offer a suite of Cleaner APIs.

We also provide a free Query Builder Tool to help write and test Elasticsearch queries for our Search APIs.


Optional Parameters

query

TypeDescriptionExample
ObjectAn Elasticsearch (v7.7) query involving our person fields.

See our underlying Elasticsearch mapping for reference.
{"query": {"term": {"job_company_name": "people data labs"}}}

Elasticsearch Query Limitations

The query value should align directly with the Elasticsearch DSL.

We accept the following Elasticsearch query types:

We've disabled most specialized options, such as boosting and custom scoring, and we do not allow aggregations.

Any array in a query (such as a terms array) will have a hard limit of 100 elements. If a request goes over this limit, it will fail.


sql

TypeDescriptionExample
StringA SQL query of the format: SELECT * FROM person WHERE XXX, where XXX is a standard SQL boolean query involving our person fields.SELECT * FROM person WHERE job_company_name='people data labs'

SQL Query Limitations

We execute SQL queries using Elasticsearch SQL.

We accept any SQL query that translates to the above Elasticsearch query types through the ES SQL translate API.

We will ignore any use of column selections or the LIMIT keyword.

We limit the number of wildcard terms (using LIKE with %) to 20 per request. If a request goes over this limit, it will fail.


size

TypeDescriptionDefaultExample
IntegerThe maximum number of matched records to return for this query if they exist. Must be between 1 and 100.1100

from

❗️

Legacy Field

The from parameter is deprecated. Use scroll_token instead.

TypeDescriptionDefaultExample
Integer[LEGACY] An offset value for paginating between batches, which must between 0 and 9999. We will execute pagination for a maximum of 10,000 records per query.

Note: You cannot use from and scroll_token in the same request.
0100

scroll_token

TypeDescriptionDefaultExample
StringEach search API response returns a scroll_token. Include it in the next request to fetch the next size matching records.

Unlike the legacy from parameter, you can use this parameter for any number of records.

Note: You cannot use from and scroll_token in the same request.
104$14.278746

A scroll_token returns in every Person Search API response and serves as a placeholder or bookmark for the last record received. For queries with more results than can fit in a single API response (see the size field), use the scroll_token to get the next batch of results.

For example, if you send a query to the Person Search API that has 10,000 matches, you will need multiple API calls to retrieve all the records. The scroll_token represents how far along you are in that list of records.

Generally, the way to use scroll_token is:

  1. Send a query to the Person Search API.
  2. Get a response back containing one batch of records as well as a scroll_token response value (if you have already retrieved all the available records in this batch, then the scroll_token value will be null).
  3. Use the same query from Step 1 and the scroll_token you just received to make another request to the Person Search API.
  4. Get another response back with the next batch of records and a new scroll_token value.
  5. Repeat steps 3 and 4 until you have gotten the desired number of records back or until the scroll_token value is null.

For a detailed working example of this process, see the following code example: Bulk Retrieval.


dataset

TypeDescriptionDefaultExample
Enum (String)Specifies which dataset(s) the API should search against.resumeall

You can input multiple datasets by separating each with a comma.

Valid dataset names are:

  • all
  • resume
  • email
  • phone
  • mobile_phone
  • street_address
  • consumer_social
  • developer

See Person Stats for details about each dataset.

You can exclude dataset(s) by using - as the first character. Entering - will exclude all of the comma-separated datasets following the character and needs to be entered only once. For example, "all,-phone,consumer_social" will include search results from every dataset except the phone and consumer_social datasets.


titlecase

TypeDescriptionDefaultExample
BooleanAll text in API responses returns as lowercase by default. Setting titlecase to true will titlecase any records returned instead.falsetrue

pretty

TypeDescriptionDefaultExample
BooleanWhether the output should have human-readable indentation.falsetrue

api_key

TypeDescriptionDefaultExample
StringYour secret API key.

Your API Key must be included in either the request header or the api_key parameter. For more information about request authentication, see the Authentication page.