Input Parameters - Person Search API

Detailed information on the input parameters used for the Person Search API

Note: While all input parameters are optional, you must provide either a query or an sql parameter (but not both.)

Optional Parameters

query

Parameter Name

Required

Description

Default

Example

query

No

An Elasticsearch (v7.7) query. See our underlying Elasticsearch mapping for reference.

{"query": {"term": {"job_company_name": "people data labs"}}}

Building a Query

You must provide a value for either the query or the sql parameter to receive a successful response. The query value should align directly with the Elasticsearch DSL. SQL queries are executed using Elasticsearch SQL. Most typical query types are available but some are excluded. For all available query types, see below.

When an API request is executed, the query runs directly against our API dataset without doing any additional cleaning or pre-processing. This means that you have a ton of freedom to explore the dataset and return the perfect records. It also means that understanding the available fields can be very helpful to making successful queries.

You can find field descriptions here and the Elasticsearch mapping underlying this here. To help you identify how to best query for specific sub-entities (schools, companies, and locations), we offer a suite of enrichment APIs for these sub-entities called the Cleaner APIs

Query Limitations

The following Elasticsearch query types will be accepted:

Most specialized options are disabled, such as boosting and custom scoring. No aggregations are allowed.

Any SQL query that translates to the above query types through the ES SQL translate API will be accepted. This means most basic SQL, NO JOIN and GROUP BY commands, and so forth.

Any array found in the query (such as a terms array) will have a hard limit of 100 elements. Any query containing an array surpassing this limit will be rejected.

sql

Parameter Name

Required

Description

Default

Example

sql

No

A SQL query of the format: SELECT * FROM person WHERE XXX, where XXX is a standard SQL boolean query involving PDL fields. Any use of column selections or the LIMIT keyword will be ignored.

SELECT * FROM person WHERE job_company_name='people data labs'

size

Parameter Name

Required

Description

Default

Example

size

No

The batch size or the maximum number of matched records to return for this query if they exist. Must be between 1 and 100.

1

100

from

Parameter Name

Required

Description

Default

Example

from

No

[LEGACY] An offset value for paginating between batches. This can be a number between 0 and 9999. Pagination can be executed up to 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

Parameter Name

Required

Description

Default

Example

scroll_token

No

An offset key for paginating between batches. Unlike the legacy from parameter, you can use this parameter for any number of records. Each search API response returns a scroll_token, which you use to fetch the next size records.

None

104$14.278746

dataset

Parameter Name

Required

Description

Default

Example

dataset

No

Specifies which dataset the API should search against. You can input multiple datasets by separating with a comma. Valid names are resume, email, phone, mobile_phone, street_address, consumer_social, developer and all. You can also exclude datasets dataset(s) using - as the first character.",
character. Entering - will exclude all of the comma separated datasets following the character and needs to only be entered once.

resume

all

titlecase

Parameter Name

Required

Description

Default

Example

titlecase

No

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

Parameter Name

Required

Description

Default

Example

pretty

No

Whether the output should have human-readable indentation.

false

true

api_key

Parameter Name

Required

Description

Default

Example

api_key

No

Your API key.

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



Did this page help you?