Find people

Search the Icypeas lead database for people matching your criteria: job title, company, location, skills, experience… Counting is free, each result fetched costs 0.02 credit.

How to use it:

Build a query with the filters below.
Call /find-people/count to see how many people match. It's free, so tweak your filters until the number looks right.
Call /find-people to get the results, 100 per page by default (up to 200). Use the pagination token to get the next pages.

info

Unlike email searches, these endpoints answer immediately: no waiting, no second call. See the rate limits.

Available filters

Below is the list of available filters that can be used to search the people dataset. They come in two families: the filters matching the person, and the filters matching the company the person works, or used to work, for.

Filters on the person

Filter name	Description	Type	Examples	Constraints
firstname	The first name of a person	Include/Exclude	`"firstname": { "include": ["John", "Jane"], "exclude": ["Alice"] }`	This is a open text field. You can put whatever you want.
lastname	The last name of a person	Include/Exclude	`"lastname": { "include": ["Doe", "Smith"], "exclude": ["Brown"] }`	This is a open text field. You can put whatever you want.
currentJobTitle	The current job title of a person	Include/Exclude	`"currentJobTitle": { "include": ["Software Engineer", "Manager"], "exclude": ["Intern"] }`	This is a open text field. You can put whatever you want.
pastJobTitle	The past job title of a person	Include/Exclude	`"pastJobTitle": { "include": ["Developer", "Analyst"], "exclude": ["Consultant"] }`	This is a open text field. You can put whatever you want.
school	The name of the school attended by the person	Include/Exclude	`"school": { "include": ["Stanford", "Harvard"], "exclude": ["MIT"] }`	This is an open text field. You can put whatever you want.
languages	The languages spoken by the person	Include/Exclude	`"languages": { "include": ["English", "Spanish"], "exclude": ["French"] }`	This is a text field. It should contain valid language names or alpha-2 language codes.
skills	The skills possessed by the person	Include/Exclude	`"skills": { "include": ["JavaScript", "Python"], "exclude": ["Java"] }`	This is a text field. It should contain valid skill names.
location	The location of the person, or the location of their current job	Include/Exclude	`"location": { "include": ["New York", "Paris, France"], "exclude": ["Los Angeles"] }`	You can put the name of a city, a country, a state, but for best results we strongly advised to use alpha-2 country code (IN, FR, US, ...). Use `profileLocation` or `workLocation` to match only one of the two. Use a comma to narrow a location down, see below
profileLocation	The location of the person only, whatever the location of their job	Include/Exclude	`"profileLocation": { "include": ["Paris, France"] }`	Same values as `location`.
workLocation	The location of the person's current job only, whatever the location of the person	Include/Exclude	`"workLocation": { "include": ["FR"] }`	Same values as `location`, except that a comma separated location is not narrowed down, see below
totalYearsOfExperience	The total number of years of experience of the person	Range	`"totalYearsOfExperience": { ">=": 5, "<=": 10 }`	This is a range of integers, expressed in years. Please see how to define a range here
timeInCurrentCompany	The number of years the person has been working in their current company	Range	`"timeInCurrentCompany": { "<=": 1 }`	This is a range of integers, expressed in years. Please see how to define a range here
keyword	A special filter that search across the entire profile (past & current job titles, job descriptions, skills, profile headline & descriptions, educations, ...)	Include/Exclude	`"keyword": { "include": ["CEO", "Co-Founder"] }`	This is an open text field, you can put whatever you want.

Filters on the company

Every filter below comes in two flavours: currentCompany* matches the company the person currently works for, pastCompany* matches a company the person used to work for.

Filter name	Description	Type	Examples	Constraints
currentCompanyName	The name of the company where the person currently works	Include/Exclude	`"currentCompanyName": { "include": ["Google", "Microsoft"], "exclude": ["Facebook"] }`	This is a open text field. You can put whatever you want.
pastCompanyName	The name of a company the person worked for before	Include/Exclude	`"pastCompanyName": { "include": ["Amazon", "IBM"], "exclude": ["Oracle"] }`	This is a open text field. You can put whatever you want.
currentCompanyId	An id representing the company where the person currently works	Include/Exclude	`"currentCompanyId": { "include": ["https://www.icypeas.com", "5678", "icypeas", "https://linkedin.com/company/icypeas"] }`	This is a textual field. It should contain valid ids. We support: company domain or website / URN numeric id / LinkedIn URL of the company / Directly the company vanity name: https://linkedin.com/company/icypeas -> icypeas.
pastCompanyId	An id representing a company the person worked for before	Include/Exclude	`"pastCompanyId": { "include": ["https://www.icypeas.com", "5678", "icypeas", "https://linkedin.com/company/icypeas"] }`	This is a textual field. It should contain valid ids. We support: company domain or website / URN numeric id / LinkedIn URL of the company / Directly the company vanity name: https://linkedin.com/company/icypeas -> icypeas.
currentCompanyWebsite	The website or domain of the company where the person currently works	Include/Exclude	`"currentCompanyWebsite": { "include": ["https://www.icypeas.com", "microsoft.com"] }`	This is a textual field. It should contain valid websites or domains only. We strongly advise to use the web domain and not a formatted URL (i.e. use `icypeas.com` instead of `https://www.icypeas.com`).
pastCompanyWebsite	The website or domain of a company the person worked for before	Include/Exclude	`"pastCompanyWebsite": { "include": ["https://www.microsoft.com", "google.com"] }`	This is a textual field. It should contain valid websites or domains only.
currentCompanyUrn	The URN of the company where the person currently works	Include/Exclude	`"currentCompanyUrn": { "include": ["1234", "5678"] }`	This is a numeric field. It should contain valid company URNs.
pastCompanyUrn	The URN of a company the person worked for before	Include/Exclude	`"pastCompanyUrn": { "include": ["3456", "7890"] }`	This is a numeric field. It should contain valid company URNs.
currentCompany.type	The type of the company where the person currently works (Privately Held, Public Company, ...)	Include/Exclude	`"currentCompany.type": { "include": ["Privately Held"], "exclude": ["Public Company"] }`	Available types are: `Privately Held`, `Sole Proprietorship`, `Self-Employed`, `Partnership`, `Public Company`, `Nonprofit`, `Educational Institution`, `Government Agency`
pastCompany.type	The type of a company the person worked for before	Include/Exclude	`"pastCompany.type": { "include": ["Nonprofit"] }`	Same values as `currentCompany.type`.
currentCompany.industry	The industry of the company where the person currently works (Software development, ...)	Include/Exclude	`"currentCompany.industry": { "include": ["Real Estate"] }`	The list of available industries can be downloaded here
pastCompany.industry	The industry of a company the person worked for before	Include/Exclude	`"pastCompany.industry": { "include": ["Real Estate"] }`	Same values as `currentCompany.industry`.
currentCompany.location	The headquarters' location of the company where the person currently works	Include/Exclude	`"currentCompany.location": { "include": ["US", "Paris, France"] }`	You can put the name of a city, a country, a state, but for best results we strongly advised to use alpha-2 country code (IN, FR, US, ...). This is the location of the company, not the one of the person: see `location`. Use a comma to narrow a location down, see below
pastCompany.location	The headquarters' location of a company the person worked for before	Include/Exclude	`"pastCompany.location": { "include": ["US", "Paris, France"] }`	Same values as `currentCompany.location`.
currentCompany.headcount	The headcount of the company where the person currently works	Range	`"currentCompany.headcount": { ">": 10 }`	This is a range of integers. Please see how to define a range here
pastCompany.headcount	The headcount of a company the person worked for before	Range	`"pastCompany.headcount": { ">": 10 }`	This is a range of integers. Please see how to define a range here
currentCompany.headcountGrowth	The headcount growth (in percentage) of the company where the person currently works, in a given timespan (6 months, 12 months, 24 months)	HeadCountGrowth	`"currentCompany.headcountGrowth": { "min": -10, "max": 50, "timespan": "6months" }`	This is a HeadCountGrowth kind of type. Please see how to define it here
pastCompany.headcountGrowth	The headcount growth (in percentage) of a company the person worked for before, in a given timespan (6 months, 12 months, 24 months)	HeadCountGrowth	`"pastCompany.headcountGrowth": { "min": 0, "max": 100, "timespan": "24months" }`	This is a HeadCountGrowth kind of type. Please see how to define it here
currentCompany.revenue	The revenue of the company where the person currently works	Range	`"currentCompany.revenue": { ">": 1000000 }`	This is a range of integers. Please see how to define a range here
pastCompany.revenue	The revenue of a company the person worked for before	Range	`"pastCompany.revenue": { ">": 1000000 }`	This is a range of integers. Please see how to define a range here
currentCompany.keyword	A special filter that search across the profile of the company where the person currently works (name, specialties, ...)	Include/Exclude	`"currentCompany.keyword": { "include": ["Higher education"] }`	This is an open text field, you can put whatever you want.
pastCompany.keyword	A special filter that search across the profile of a company the person worked for before (name, specialties, ...)	Include/Exclude	`"pastCompany.keyword": { "include": ["Higher education"] }`	This is an open text field, you can put whatever you want.

info

The filters matching the current experience — currentJobTitle, workLocation, timeInCurrentCompany and every currentCompany* filter — all apply to the same job. Combining them returns the people whose current job matches all of them at once, and not the people who match each of them on a different job. The same goes for pastJobTitle and the pastCompany* filters on past experiences.

Narrowing a location down

A location made of comma separated parts only matches when every one of its parts does. "Paris, France" matches the people in Paris and in France, which is how you tell the French Paris from Paris, Texas.

Each part is matched against the country, the state and the city, so the order of the parts does not matter: "Paris, France" and "France, Paris" are the same filter.

Several locations remain alternatives to each other, whether they hold a comma or not. "location": { "include": ["Paris, France", "US"] } matches the people in Paris (France) or anywhere in the United States.

This applies to location, profileLocation, currentCompany.location and pastCompany.location.

caution

workLocation is the exception: it is matched against the location of the job as it is written on the profile, which already is a comma separated string. "workLocation": { "include": ["Paris, France"] } therefore looks for that exact wording, and is not narrowed down to Paris and France. Prefer location or currentCompany.location when you need a location narrowed down.

Query examples

Search for all people living in Paris, France
{
    "query": {
        "profileLocation": { "include": ["Paris, France"] }
    }
}

Search for all people currently employed as CTO in the US
{
    "query": {
        "currentJobTitle": { "include": ["CTO", "Chief Technical Officer"] },
        "location": { "include": ["US"] }
    }
}

Search for all people speaking English in France
{
    "query": {
        "languages": { "include": ["EN"] },
        "location": { "include": ["FR"] }
    }
}

Search for all engineers working at Apple
{
    "query": {
        "currentJobTitle": { "include": ["engineer"] },
        "currentCompanyName": { "include": ["apple"] }
    }
}

Search for seasoned people that recently joined a fast growing company
{
    "query": {
        "totalYearsOfExperience": { ">=": 10 },
        "timeInCurrentCompany": { "<=": 1 },
        "currentCompany.headcountGrowth": { "min": 20, "max": 100, "timespan": "12months" }
    }
}

Search for all people working in a small privately held software company in France
{
    "query": {
        "currentCompany.type": { "include": ["Privately Held"] },
        "currentCompany.industry": { "include": ["Software Development"] },
        "currentCompany.headcount": { "<=": 50 },
        "currentCompany.location": { "include": ["FR"] }
    }
}

Count matching people (free)

When you need to assess the number of people returned by a specific query, you should use this route. We do not charge anything when using this route.

POSThttps://app.icypeas.com/api/find-people/count

Headers

Authorizationstringrequired
Your API key, as is (no Bearer prefix).
Content-Typestringrequired
Always application/json.

Body parameters

queryobjectrequired
The query
Rule: should be a valid query (see available fields above)

Request example

cURL
JavaScript
Python
PHP
PowerShell

curl -X POST "https://app.icypeas.com/api/find-people/count" \
  -H "Content-Type: application/json" \
  -H "Authorization: YOUR_API_KEY"

const response = await fetch("https://app.icypeas.com/api/find-people/count", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: "YOUR_API_KEY",
  },
});

const data = await response.json();
console.log(data);

import requests

response = requests.post(
    "https://app.icypeas.com/api/find-people/count",
    headers={"Authorization": "YOUR_API_KEY"},
)
print(response.json())

<?php
$ch = curl_init("https://app.icypeas.com/api/find-people/count");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_HTTPHEADER => [
        "Content-Type: application/json",
        "Authorization: YOUR_API_KEY",
    ],
]);

$response = json_decode(curl_exec($ch), true);
curl_close($ch);
print_r($response);

$headers = @{
  "Authorization" = "YOUR_API_KEY"
  "Content-Type"  = "application/json"
}

$response = Invoke-RestMethod -Method POST -Uri "https://app.icypeas.com/api/find-people/count" -Headers $headers
$response | ConvertTo-Json -Depth 10

Responses

200SuccessResponse when they are no errors

Example response · 200
{
  "success": true,
  "total": 10
}

Response fields

successboolean
true means that your search succeeded (no error was raised on our side)
totalnumber
The number of people

200Validation errorResponse when there are validation errors.

The request reached Icypeas but some fields are wrong. The response lists every problem in validationErrors. See how to read and fix errors.

Example response · 200
{
  "validationErrors": [
    {
      "expected": "object with props defined in the schema",
      "type": "objectStrict",
      "actual": {
        "x": 10
      },
      "field": "query.headcount",
      "message": "The object 'query.headcount' contains forbidden keys."
    }
  ],
  "success": false
}

Type	Fields	When it happens
`required`	`query`	Error sent when the query field is not passed inside the request body
`EmptyQueryError`	`query`	Error sent when the query is empty
`objectStrict`	`query.[field]`	Error sent when a field contains forbidden keys (for instance { urn: { x: ["test"] } } instead of { urn: { exclude: ["test"] } })
`arrayEmpty`	`query.[field].includequery.[field].exclude`	Error sent when a Include/Exclude field contains an empty include or exclude array
`objectLength`	`query.[field]`	Error sent when a field is empty (for instance { urn: {} } instead of { urn: { include: ["1527"] } })
`InsufficientCredits`		You need more credits than the ones you have to run this search.
`UnpaidSubscriptionError`		Error sent when you have a pending payment and your subscription is therefore not paid

401UnauthorizedResponse when we could not authenticate you.

Example response · 401
{
  "message": "Unauthorized access.",
  "error": "UnauthorizedAccessError",
  "status": 401,
  "code": "unauthorized_access_error"
}

Response fields

messagestring
Human-readable message.
errorstring
Error name
statusnumber
HTTP error code
codestring
Error code

429Too many requestsError received when rate limit is exceeded

Example response · 429
{
  "message": "You have exceeded the max number of requests per minute.",
  "error": "RateLimitExceededError",
  "status": 429,
  "code": "rate_limit_exceeded_error"
}

Response fields

messagestring
Human-readable message.
errorstring
Error name
statusnumber
HTTP error code
codestring
Error code

Fetch matching people

When you want to retrieve the results for your query, you should use this route. The route is paginated, please see below on how to handle pagination.

POSThttps://app.icypeas.com/api/find-people

Headers

Authorizationstringrequired
Your API key, as is (no Bearer prefix).
Content-Typestringrequired
Always application/json.

Body parameters

queryobjectrequired
The query
Rule: should be a valid query (see available fields above)
paginationobjectoptional
This is optional and used only if you want to retrieve more people than the first page.
Rule: should be a valid pagination object
Show properties (2)
- tokenstringrequired
  The token returned with the previous page. Valid 15 minutes; each response returns a new token with a new 15-minute validity.
  Rule: should be a valid pagination token
- sizenumberoptional
  The number of people returned per page
  Rule: should be a valid integer between 1 and 200
  Default: 100

Request example

cURL
JavaScript
Python
PHP
PowerShell

curl -X POST "https://app.icypeas.com/api/find-people" \
  -H "Content-Type: application/json" \
  -H "Authorization: YOUR_API_KEY"

const response = await fetch("https://app.icypeas.com/api/find-people", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: "YOUR_API_KEY",
  },
});

const data = await response.json();
console.log(data);

import requests

response = requests.post(
    "https://app.icypeas.com/api/find-people",
    headers={"Authorization": "YOUR_API_KEY"},
)
print(response.json())

<?php
$ch = curl_init("https://app.icypeas.com/api/find-people");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_HTTPHEADER => [
        "Content-Type: application/json",
        "Authorization: YOUR_API_KEY",
    ],
]);

$response = json_decode(curl_exec($ch), true);
curl_close($ch);
print_r($response);

$headers = @{
  "Authorization" = "YOUR_API_KEY"
  "Content-Type"  = "application/json"
}

$response = Invoke-RestMethod -Method POST -Uri "https://app.icypeas.com/api/find-people" -Headers $headers
$response | ConvertTo-Json -Depth 10

Responses

200SuccessResponse when no errors are sent

Example response · 200
{
  "success": true,
  "total": 4,
  "leads": [
    {
      "firstname": "Pierre-Baptiste",
      "lastname": "Landoin",
      "headline": "CEO @Icypeas | Love discussing lead generation, sales automation, marketing hacks and entrepreneurship",
      "description": "I have co-founded:\n- Icypeas (Email Finder & Verifier, www.icypeas.com)\n- NSW PRIM (Model mapping, www.nswprim.com)\n- Superpitch (Animated Videos, www.superpitch.fr)\n- FileVirtuelle (Welcome Kiosks, www.filevirtuelle.com)\n- Cerbair (Drone Detection, www.cerbair.com)\n- MySeat (Connected Objects, www.myseat.fr)\n\nIn total, over 50 jobs created and €6M in revenue in 2021.",
      "profileUrl": "https://www.linkedin.com/in/pierre-baptiste-landoin-icypeas",
      "lastJobTitle": "Chief Executive Officer",
      "lastJobDescription": "Icypeas is a SaaS to find and verify email addresses. \n\n- unparalleled email discovery rate\n- lowest bounce rate \n\nDiscover more on https://www.icypeas.com.",
      "lastJobStartDate": "10-2022",
      "address": "Paris, Ile-de-France, France",
      "lastCompanyName": "Icypeas",
      "lastCompanyUrn": "urn:li:fs_salesCompany:89667826",
      "lastCompanyUrl": "https://www.linkedin.com/company/icypeas/",
      "lastCompanyWebsite": "https://www.icypeas.com",
      "lastCompanyDescription": "",
      "lastCompanySize": 4,
      "lastCompanyIndustry": "Software Development",
      "lastCompanyAddress": "Paris, Île-de-France, France"
    },
    {
      "firstname": "Corentin",
      "lastname": "Ribeyre",
      "headline": "CTO at Icypeas",
      "description": "",
      "profileUrl": "https://www.linkedin.com/in/corentin-ribeyre-30085a3b",
      "lastJobTitle": "Chief Technology Officer / Founder",
      "lastJobDescription": "",
      "lastJobStartDate": "10-2022",
      "address": "Paris, Ile-de-France, France",
      "lastCompanyName": "Icypeas",
      "lastCompanyUrn": "urn:li:fs_salesCompany:89667826",
      "lastCompanyUrl": "https://www.linkedin.com/company/icypeas/",
      "lastCompanyWebsite": "https://www.icypeas.com",
      "lastCompanyDescription": "",
      "lastCompanySize": 4,
      "lastCompanyIndustry": "Software Development",
      "lastCompanyAddress": "Paris, Île-de-France, France"
    }
  ],
  "pagination": {
    "size": 2,
    "token": "xxxxxx"
  }
}

Response fields

successboolean
true means that your search succeeded (no error was raised on our side)
totalnumber
The number of people
paginationobject
This is used if you want to retrieve more people than the first page.
Show properties (2)
- tokenstring
  Token to request the next page. Valid 15 minutes from this response: request the next page before it expires.
- sizenumber
  The number of people returned per page
  Default: 100
leadsarray of objects
An array containing the people information
Show item properties (17)
- firstnamestring
  The firstname of the lead
- lastnamestring
  The lastname of the lead
- headlinestring
  A brief summary or description of the lead's professional identity or role
- descriptionstring
  Detailed information about the lead's background, experience, and accomplishments
- profileUrlstring
  The URL to the lead's LinkedIn profile
- lastJobTitlestring
  The title of the lead's most recent job position
- lastJobDescriptionstring
  A more detailed description about his/her most recent position
- lastJobStartDatestring
  The start date of the lead's most recent job position
- addressstring
  The geographical location or address associated with the lead
- lastCompanyNamestring
  The name of the company where the lead was most recently employed
- lastCompanyUrnstring
  The unique identifier (URN) of the most recent company on LinkedIn
- lastCompanyUrlstring
  The URL to the LinkedIn page of the lead's most recent company
- lastCompanyWebsitestring
  The website address of the lead's most recent company
- lastCompanyDescriptionstring
  A brief description or overview of the lead's most recent company
- lastCompanySizenumber
  The number of employees inside the lead's most recent company
- lastCompanyIndustrystring
  The industry in which the lead's most recent company operates
- lastCompanyAddressstring
  The geographical location or address of the lead's most recent company

200Validation errorResponse when there are validation errors.

The request reached Icypeas but some fields are wrong. The response lists every problem in validationErrors. See how to read and fix errors.

Example response · 200
{
  "validationErrors": [
    {
      "expected": "object with props defined in the schema",
      "type": "objectStrict",
      "actual": {
        "x": 10
      },
      "field": "query.currentJobTitle",
      "message": "The object 'query.headcount' contains forbidden keys."
    }
  ],
  "success": false
}

Type	Fields	When it happens
`required`	`query`	Error sent when the query field is not passed inside the request body
`EmptyQueryError`	`query`	Error sent when the query is empty
`objectStrict`	`query.[field]`	Error sent when a field contains forbidden keys (for instance { urn: { x: ["test"] } } instead of { urn: { exclude: ["test"] } })
`arrayEmpty`	`query.[field].includequery.[field].exclude`	Error sent when a Include/Exclude field contains an empty include or exclude array
`objectLength`	`query.[field]`	Error sent when a field is empty (for instance { urn: {} } instead of { urn: { include: ["1527"] } })
`InsufficientCredits`		You need more credits than the ones you have to run this search.
`UnpaidSubscriptionError`		Error sent when you have a pending payment and your subscription is therefore not paid
`number`	`pagination.size`	Error sent when the size in pagination is not an integer
`numberMin`	`pagination.size`	Error sent when pagination is less than the min
`numberMax`	`pagination.size`	Error sent when pagination is greater than the max
`InvalidPaginationTokenError`	`pagination.token`	Error sent when the pagination token is not in the right format

401UnauthorizedResponse when we could not authenticate you.

Example response · 401
{
  "message": "Unauthorized access.",
  "error": "UnauthorizedAccessError",
  "status": 401,
  "code": "unauthorized_access_error"
}

Response fields

messagestring
Human-readable message.
errorstring
Error name
statusnumber
HTTP error code
codestring
Error code

429Too many requestsError received when rate limit is exceeded

Example response · 429
{
  "message": "You have exceeded the max number of requests per minute.",
  "error": "RateLimitExceededError",
  "status": 429,
  "code": "rate_limit_exceeded_error"
}

Response fields

messagestring
Human-readable message.
errorstring
Error name
statusnumber
HTTP error code
codestring
Error code

Pagination

Results come in pages of pagination.size items (100 by default, from 1 to 200). With 1,000 matches and the default size, you need 10 calls to get everything.

When there are more results, the response contains a pagination object with a token. Send that object back with the same query to get the next page:

1. First request
{
  "query": { "headcount": { ">": 10 } },
  "pagination": { "size": 2 }
}

1. First response (shortened)
{
  "success": true,
  "total": 845,
  "leads": [
    { "name": "Harvard Graduate School of Education", "numberOfEmployees": 1134, "industry": "Higher Education" },
    { "name": "Trammell Crow Company", "numberOfEmployees": 989, "industry": "Real Estate" }
  ],
  "pagination": {
    "size": 2,
    "token": "eyJzYSI6W1syXSxbMTI4ODQ5MDE5MDJdXSwiaWQiOi…"
  }
}

2. Next request: same query + the pagination object you received
{
  "query": { "headcount": { ">": 10 } },
  "pagination": {
    "size": 2,
    "token": "eyJzYSI6W1syXSxbMTI4ODQ5MDE5MDJdXSwiaWQiOi…"
  }
}

Each response brings a new token: always use the latest. Stop when no pagination object comes back.

Token expiration

A token is valid for 15 minutes. Every request that uses it returns a new token, with a fresh 15-minute window.

So the 15 minutes is the maximum time between two pages, not the time you have to go through the whole search. As long as you ask for the next page within 15 minutes of the previous one, you can keep paging for as long as you need, even to retrieve hundreds of thousands or millions of results.

Request	Uses token	Returns token	Valid until
Page 1 at 10:00	none	A	10:15
Page 2 at 10:12	A	B	10:27
Page 3 at 10:20	B	C	10:35
…	…	…	…

If a token expires, start again from the first page with the same query.

warning

Always send the latest token. An older one may have expired even if you're still paging.
Don't change the query between pages: the token belongs to that exact query.
Pausing your script for more than 15 minutes between two pages (for example while processing a batch) makes the token expire.

Include/Exclude specs

The Include/Exclude field can contains two arrays:

include array which lists what needs to be included in the query.
exclude array which lists what needs to be excluded from the query.

For instance, when looking for leads, you can include some currentJobTitle and exclude some others:

{
    "currentJobTitle": {
        "include": ["CTO"],
        "exclude": ["Senior engineer"]
    }
}

caution

include and exclude arrays are limited to 200 values per array per field.

Range specs

The Range field contains comparison operators and numerical values only. Some examples are listed below:

{
    "headcount": {
        ">=": 10,
        "<": 20
    }
}

{
    "headcount": {
        ">": 10,
        "<=": 20
    }
}

{
    "headcount": {
        ">": 10,
        "<": 20
    }
}

The operators can be > (greater than), < (less than), >= (greater or equal), <= (less or equal).

You are responsible for giving a range that makes sense.

Headcount growth specs

Filter companies by their employee growth rate over a specific period. This criterion is useful for identifying scaling companies, detecting workforce reductions, or finding organizations at particular growth stages.

Headcount growth parameters

Parameter	Type	Description
`timespan`	string	The measurement period: `6months`, `12months`, or `24months`
`min`	number	Minimum growth rate (percentage). Range: -100 to 10,000
`max`	number	Maximum growth rate (percentage). Range: -100 to 10,000

Growth rate scale

0% = No change in headcount
Positive values = Headcount increase
Negative values = Headcount decrease
-100% = Company lost all employees

Headcount growth example

{
  "headcountGrowth": {
    "timespan": "6months",
    "min": -10,
    "max": 50
  }
}

Returns all companies that experienced between -10% and +50% headcount growth in the past 6 months.

Available filters​

Filters on the person​

Filters on the company​

Narrowing a location down​

Query examples​

Count matching people (free)​

Fetch matching people​

Pagination​

Token expiration​

Include/Exclude specs​

Range specs​

Headcount growth specs​

Headcount growth parameters​

Growth rate scale​

Headcount growth example​

Available filters

Filters on the person

Filters on the company

Narrowing a location down

Query examples

Count matching people (free)

Fetch matching people

Pagination

Token expiration

Include/Exclude specs

Range specs

Headcount growth specs

Headcount growth parameters

Growth rate scale

Headcount growth example