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": {"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 here.

When an API request is executed, the query is run directly against our Company 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 API here.

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 company WHERE 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. Can be a number between 0 and 9999. Pagination can be executed up to a maximum of 10,000 records per query. Note: `FROM` CAN NOT BE USED WITH `SCROLL_TOKEN` IN THE SAME REQUEST.	`0`	`0`, `100`, `200` ...

Parameter Name

Required

Description

Default

Example

from

[LEGACY] An offset value for paginating between batches. Can be a number between 0 and 9999. Pagination can be executed up to a maximum of 10,000 records per query.

Note: FROM CAN NOT BE USED 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 for any number of records. Each Company Search API response returns a `scroll_token` that you can use to fetch the next `size` records.	`None`	`104$14.278746`

`titlecase`

Parameter Name	Required	Description	Default	Example
`titlecase`	No	All text in API responses is returned 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.

Parameter Name

Required

Description

Default

Example

api_key

Your API key.

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