Find People

caution

Rate limits always apply on all routes. Check the dedicated page for more information.

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 the number of people matching your query

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

BODY PARAMS

query*object(should be a valid query (see available fields above))

The query

RESPONSES

Find 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

BODY PARAMS

query*object(should be a valid query (see available fields above))

The query

paginationobject(should be a valid pagination object)

This is optional and used only if you want to retrieve more people than the first page.

token*string(should be a valid pagination token)

The pagination token

sizenumber(should be a valid integer between 1 and 200)

The number of people returned per page

Default Value :100

RESPONSES

Pagination

The results of a query are paginated depending of the size parameter you have given inside the pagination object (default value is 100). If you need to fetch more than the first 100 results, you need to use the pagination mecanism.

If your query returns 1,000 results - with the default pagination size of 100 - you'll need to call the route 10 times to get all the results. Min pagination size is 1 and max is 200.

When the number of results is greater than the size, we will return a pagination object that looks like:

{
    "pagination": {
        "size": 100,
        "token": "eyJzYSI6W1syXSxbMTI4ODQ5MDE5MDJdXSwiaWQiOiIwOGZzQXc4eGFXTjVjR1ZoY3kxemJuTXRaR1YyWld4dmNHMWxiblF0YkdsdWEyVmthVzR0WTI5dGNHRnVlUzB5TURJME1URXhOUlpVUjI5MlYyNVJNMUkyTm1adlRUTnRVR0Y0TmpObkJoWmlMVGwwUm1wYVRsSjBUMU5XYlVKYWJHOUNSa1pCQUFBQUFBQUFQRFpJRmpsU2JqSlRUMEZYVWxWSE0zRk1WRTh5YTFoUGJsRUFNV2xqZVhCbFlYTXRjMjV6TFdSbGRtVnNiM0J0Wlc1MExXeHBibXRsWkdsdUxXTnZiWEJoYm5rdE1qQXlOREV4TVRVV1ZFZHZkbGR1VVROU05qWm1iMDB6YlZCaGVEWXpad1VXWWkwNWRFWnFXazVTZEU5VFZtMUNXbXh2UWtaR1FRQUFBQUFBQUR3MlJ4WTVVbTR5VTA5QlYxSlZSek54VEZSUE1tdFlUMjVSQURGcFkzbHdaV0Z6TFhOdWN5MWtaWFpsYkc5d2JXVnVkQzFzYVc1clpXUnBiaTFqYjIxd1lXNTVMVEl3TWpReE1URTFGbFJIYjNaWGJsRXpValkyWm05Tk0yMVFZWGcyTTJjSUZtSXRPWFJHYWxwT1VuUlBVMVp0UWxwc2IwSkdSa0VBQUFBQUFBQThOa29XT1ZKdU1sTlBRVmRTVlVjemNVeFVUekpyV0U5dVVRQXhhV041Y0dWaGN5MXpibk10WkdWMlpXeHZjRzFsYm5RdGJHbHVhMlZrYVc0dFkyOXRjR0Z1ZVMweU1ESTBNVEV4TlJaVVIyOTJWMjVSTTFJMk5tWnZUVE50VUdGNE5qTm5CeFppTFRsMFJtcGFUbEowVDFOV2JVSmFiRzlDUmtaQkFBQUFBQUFBUERaSkZqbFNiakpUVDBGWFVsVkhNM0ZNVkU4eWExaFBibEVBTVdsamVYQmxZWE10YzI1ekxXUmxkbVZzYjNCdFpXNTBMV3hwYm10bFpHbHVMV052YlhCaGJua3RNakF5TkRFeE1UVVdWRWR2ZGxkdVVUTlNOalptYjAwemJWQmhlRFl6WndvV1lpMDVkRVpxV2s1U2RFOVRWbTFDV214dlFrWkdRUUFBQUFBQUFEdzJUQlk1VW00eVUwOUJWMUpWUnpOeFRGUlBNbXRZVDI1UkFERnBZM2x3WldGekxYTnVjeTFrWlhabGJHOXdiV1Z1ZEMxc2FXNXJaV1JwYmkxamIyMXdZVzU1TFRJd01qUXhNVEUxRmxSSGIzWlhibEV6VWpZMlptOU5NMjFRWVhnMk0yY0pGbUl0T1hSR2FscE9VblJQVTFadFFscHNiMEpHUmtFQUFBQUFBQUE4TmtzV09WSnVNbE5QUVZkU1ZVY3pjVXhVVHpKcldFOXVVUUF4YVdONWNHVmhjeTF6Ym5NdFpHVjJaV3h2Y0cxbGJuUXRiR2x1YTJWa2FXNHRZMjl0Y0dGdWVTMHlNREkwTVRFeE5SWlVSMjkyVjI1Uk0xSTJObVp2VFROdFVHRjROak5uREJaaUxUbDBSbXBhVGxKMFQxTldiVUphYkc5Q1JrWkJBQUFBQUFBQVBEWk9GamxTYmpKVFQwRlhVbFZITTNGTVZFOHlhMWhQYmxFQU1XbGplWEJsWVhNdGMyNXpMV1JsZG1Wc2IzQnRaVzUwTFd4cGJtdGxaR2x1TFdOdmJYQmhibmt0TWpBeU5ERXhNVFVXVkVkdmRsZHVVVE5TTmpabWIwMHpiVkJoZURZelp3c1dZaTA1ZEVacVdrNVNkRTlUVm0xQ1dteHZRa1pHUVFBQUFBQUFBRHcyVFJZNVVtNHlVMDlCVjFKVlJ6TnhURlJQTW10WVQyNVJBREZwWTNsd1pXRnpMWE51Y3kxa1pYWmxiRzl3YldWdWRDMXNhVzVyWldScGJpMWpiMjF3WVc1NUxUSXdNalF4TVRFMUZsUkhiM1pYYmxFelVqWTJabTlOTTIxUVlYZzJNMmNBRm1JdE9YUkdhbHBPVW5SUFUxWnRRbHBzYjBKR1JrRUFBQUFBQUFBOE5rSVdPVkp1TWxOUFFWZFNWVWN6Y1V4VVR6SnJXRTl1VVFBeGFXTjVjR1ZoY3kxemJuTXRaR1YyWld4dmNHMWxiblF0YkdsdWEyVmthVzR0WTI5dGNHRnVlUzB5TURJME1URXhOUlpVUjI5MlYyNVJNMUkyTm1adlRUTnRVR0Y0TmpObkFoWmlMVGwwUm1wYVRsSjBUMU5XYlVKYWJHOUNSa1pCQUFBQUFBQUFQRFpFRmpsU2JqSlRUMEZYVWxWSE0zRk1WRTh5YTFoUGJsRUFNV2xqZVhCbFlYTXRjMjV6TFdSbGRtVnNiM0J0Wlc1MExXeHBibXRsWkdsdUxXTnZiWEJoYm5rdE1qQXlOREV4TVRVV1ZFZHZkbGR1VVROU05qWm1iMDB6YlZCaGVEWXpad0VXWWkwNWRFWnFXazVTZEU5VFZtMUNXbXh2UWtaR1FRQUFBQUFBQUR3MlF4WTVVbTR5VTA5QlYxSlZSek54VEZSUE1tdFlUMjVSQURGcFkzbHdaV0Z6TFhOdWN5MWtaWFpsYkc5d2JXVnVkQzFzYVc1clpXUnBiaTFqYjIxd1lXNTVMVEl3TWpReE1URTFGbFJIYjNaWGJsRXpValkyWm05Tk0yMVFZWGcyTTJjRUZtSXRPWFJHYWxwT1VuUlBVMVp0UWxwc2IwSkdSa0VBQUFBQUFBQThOa1lXT1ZKdU1sTlBRVmRTVlVjemNVeFVUekpyV0U5dVVRQXhhV041Y0dWaGN5MXpibk10WkdWMlpXeHZjRzFsYm5RdGJHbHVhMlZrYVc0dFkyOXRjR0Z1ZVMweU1ESTBNVEV4TlJaVVIyOTJWMjVSTTFJMk5tWnZUVE50VUdGNE5qTm5BeFppTFRsMFJtcGFUbEowVDFOV2JVSmFiRzlDUmtaQkFBQUFBQUFBUERaRkZqbFNiakpUVDBGWFVsVkhNM0ZNVkU4eWExaFBibEVBTVdsamVYQmxZWE10YzI1ekxXUmxkbVZzYjNCdFpXNTBMV3hwYm10bFpHbHVMV052YlhCaGJua3RNakF5TkRFeE1UVVdWRWR2ZGxkdVVUTlNOalptYjAwemJWQmhlRFl6Wnc0V1lpMDVkRVpxV2s1U2RFOVRWbTFDV214dlFrWkdRUUFBQUFBQUFEdzJVQlk1VW00eVUwOUJWMUpWUnpOeFRGUlBNbXRZVDI1UkFERnBZM2x3WldGekxYTnVjeTFrWlhabGJHOXdiV1Z1ZEMxc2FXNXJaV1JwYmkxamIyMXdZVzU1TFRJd01qUXhNVEUxRmxSSGIzWlhibEV6VWpZMlptOU5NMjFRWVhnMk0yY05GbUl0T1hSR2FscE9VblJQVTFadFFscHNiMEpHUmtFQUFBQUFBQUE4Tms4V09WSnVNbE5QUVZkU1ZVY3pjVXhVVHpKcldFOXVVUUFCRmxSSGIzWlhibEV6VWpZMlptOU5NMjFRWVhnMk0yY0FBQT09IiwiZklkIjoieFgwVzBKY0JDZGpFUUxvRlpZcjIifx=="
    }
}

You just have to pass this pagination object to your request each time you want to fetch more results.

Let's take an example here:

Imagine you want all companies with more than 10 employees and only return 2 companies per page. Your initial query will look like this:

Example of first request

{
    "query": {
        "headcount": { ">": 10 }
    },
    "pagination": { "size": 2 }
}

The system will return something like:

First response from Icypeas

    "success": true,
    "total": 845,
    "leads": [
{
    "name": "Harvard Graduate School of Education",
    "lid": "hgse",
    "urn": "urn:li:fs_salesCompany:1653",
    "url": "https://www.linkedin.com/company/hgse/",
    "description": "Education touches every aspect of human activity. At the Harvard Graduate School of Education (HGSE), we believe studying and improving the enterprise of education are central to the health and future of society.",
    "address": "Cambridge, Massachusetts, United States",
    "numberOfEmployees": 1134,
    "industry": "Higher Education",
    "website": "http://www.gse.harvard.edu",
    "specialties": [],
    "employeeGrowth": [],
    "_id": "sMMXT5MBIateb5xQKCCK"
},
{
    "name": "Trammell Crow Company",
    "lid": "trammell-crow-company",
    "urn": "urn:li:fs_salesCompany:2320",
    "url": "https://www.linkedin.com/company/trammell-crow-company/",
    "description": "Trammell Crow Company (TCC) is a global commercial real estate developer and wholly-owned subsidiary of CBRE Group, Inc. (NYSE:CBRE), a Fortune 500 and S&P 500 company headquartered in Dallas. Founded in 1948, TCC has developed or acquired nearly 2,900 buildings valued at $75 billion and over 655 million square feet. As of September 30, 2024, TCC had $19 billion of projects in process and $13.4 billion in its pipeline. With 575 employees throughout the United States and Europe in 27 offices, the company serves users of and investors in office, industrial/logistics, healthcare, life science, data center and mixed-use projects, as well as multi-family residential through its operating subsidiary High Street Residential. For more information visit www.TrammellCrow.com.",
    "address": "Dallas, Texas, United States",
    "numberOfEmployees": 989,
    "industry": "Real Estate",
    "website": "http://www.trammellcrow.com",
    "specialties": [],
    "employeeGrowth": [],
    "_id": "-sMXT5MBIateb5xQeCIO"
},
    ],
    "pagination": {
      "size": 2,
      "token": "eyJzYSI6W1syXSxbMTI4ODQ5MDE5MDJdXSwiaWQiOiIwOGZzQXc4eGFXTjVjR1ZoY3kxemJuTXRaR1YyWld4dmNHMWxiblF0YkdsdWEyVmthVzR0WTI5dGNHRnVlUzB5TURJME1URXhOUlpVUjI5MlYyNVJNMUkyTm1adlRUTnRVR0Y0TmpObkJoWmlMVGwwUm1wYVRsSjBUMU5XYlVKYWJHOUNSa1pCQUFBQUFBQUFQRFpJRmpsU2JqSlRUMEZYVWxWSE0zRk1WRTh5YTFoUGJsRUFNV2xqZVhCbFlYTXRjMjV6TFdSbGRtVnNiM0J0Wlc1MExXeHBibXRsWkdsdUxXTnZiWEJoYm5rdE1qQXlOREV4TVRVV1ZFZHZkbGR1VVROU05qWm1iMDB6YlZCaGVEWXpad1VXWWkwNWRFWnFXazVTZEU5VFZtMUNXbXh2UWtaR1FRQUFBQUFBQUR3MlJ4WTVVbTR5VTA5QlYxSlZSek54VEZSUE1tdFlUMjVSQURGcFkzbHdaV0Z6TFhOdWN5MWtaWFpsYkc5d2JXVnVkQzFzYVc1clpXUnBiaTFqYjIxd1lXNTVMVEl3TWpReE1URTFGbFJIYjNaWGJsRXpValkyWm05Tk0yMVFZWGcyTTJjSUZtSXRPWFJHYWxwT1VuUlBVMVp0UWxwc2IwSkdSa0VBQUFBQUFBQThOa29XT1ZKdU1sTlBRVmRTVlVjemNVeFVUekpyV0U5dVVRQXhhV041Y0dWaGN5MXpibk10WkdWMlpXeHZjRzFsYm5RdGJHbHVhMlZrYVc0dFkyOXRjR0Z1ZVMweU1ESTBNVEV4TlJaVVIyOTJWMjVSTTFJMk5tWnZUVE50VUdGNE5qTm5CeFppTFRsMFJtcGFUbEowVDFOV2JVSmFiRzlDUmtaQkFBQUFBQUFBUERaSkZqbFNiakpUVDBGWFVsVkhNM0ZNVkU4eWExaFBibEVBTVdsamVYQmxZWE10YzI1ekxXUmxkbVZzYjNCdFpXNTBMV3hwYm10bFpHbHVMV052YlhCaGJua3RNakF5TkRFeE1UVVdWRWR2ZGxkdVVUTlNOalptYjAwemJWQmhlRFl6WndvV1lpMDVkRVpxV2s1U2RFOVRWbTFDV214dlFrWkdRUUFBQUFBQUFEdzJUQlk1VW00eVUwOUJWMUpWUnpOeFRGUlBNbXRZVDI1UkFERnBZM2x3WldGekxYTnVjeTFrWlhabGJHOXdiV1Z1ZEMxc2FXNXJaV1JwYmkxamIyMXdZVzU1TFRJd01qUXhNVEUxRmxSSGIzWlhibEV6VWpZMlptOU5NMjFRWVhnMk0yY0pGbUl0T1hSR2FscE9VblJQVTFadFFscHNiMEpHUmtFQUFBQUFBQUE4TmtzV09WSnVNbE5QUVZkU1ZVY3pjVXhVVHpKcldFOXVVUUF4YVdONWNHVmhjeTF6Ym5NdFpHVjJaV3h2Y0cxbGJuUXRiR2x1YTJWa2FXNHRZMjl0Y0dGdWVTMHlNREkwTVRFeE5SWlVSMjkyVjI1Uk0xSTJObVp2VFROdFVHRjROak5uREJaaUxUbDBSbXBhVGxKMFQxTldiVUphYkc5Q1JrWkJBQUFBQUFBQVBEWk9GamxTYmpKVFQwRlhVbFZITTNGTVZFOHlhMWhQYmxFQU1XbGplWEJsWVhNdGMyNXpMV1JsZG1Wc2IzQnRaVzUwTFd4cGJtdGxaR2x1TFdOdmJYQmhibmt0TWpBeU5ERXhNVFVXVkVkdmRsZHVVVE5TTmpabWIwMHpiVkJoZURZelp3c1dZaTA1ZEVacVdrNVNkRTlUVm0xQ1dteHZRa1pHUVFBQUFBQUFBRHcyVFJZNVVtNHlVMDlCVjFKVlJ6TnhURlJQTW10WVQyNVJBREZwWTNsd1pXRnpMWE51Y3kxa1pYWmxiRzl3YldWdWRDMXNhVzVyWldScGJpMWpiMjF3WVc1NUxUSXdNalF4TVRFMUZsUkhiM1pYYmxFelVqWTJabTlOTTIxUVlYZzJNMmNBRm1JdE9YUkdhbHBPVW5SUFUxWnRRbHBzYjBKR1JrRUFBQUFBQUFBOE5rSVdPVkp1TWxOUFFWZFNWVWN6Y1V4VVR6SnJXRTl1VVFBeGFXTjVjR1ZoY3kxemJuTXRaR1YyWld4dmNHMWxiblF0YkdsdWEyVmthVzR0WTI5dGNHRnVlUzB5TURJME1URXhOUlpVUjI5MlYyNVJNMUkyTm1adlRUTnRVR0Y0TmpObkFoWmlMVGwwUm1wYVRsSjBUMU5XYlVKYWJHOUNSa1pCQUFBQUFBQUFQRFpFRmpsU2JqSlRUMEZYVWxWSE0zRk1WRTh5YTFoUGJsRUFNV2xqZVhCbFlYTXRjMjV6TFdSbGRtVnNiM0J0Wlc1MExXeHBibXRsWkdsdUxXTnZiWEJoYm5rdE1qQXlOREV4TVRVV1ZFZHZkbGR1VVROU05qWm1iMDB6YlZCaGVEWXpad0VXWWkwNWRFWnFXazVTZEU5VFZtMUNXbXh2UWtaR1FRQUFBQUFBQUR3MlF4WTVVbTR5VTA5QlYxSlZSek54VEZSUE1tdFlUMjVSQURGcFkzbHdaV0Z6TFhOdWN5MWtaWFpsYkc5d2JXVnVkQzFzYVc1clpXUnBiaTFqYjIxd1lXNTVMVEl3TWpReE1URTFGbFJIYjNaWGJsRXpValkyWm05Tk0yMVFZWGcyTTJjRUZtSXRPWFJHYWxwT1VuUlBVMVp0UWxwc2IwSkdSa0VBQUFBQUFBQThOa1lXT1ZKdU1sTlBRVmRTVlVjemNVeFVUekpyV0U5dVVRQXhhV041Y0dWaGN5MXpibk10WkdWMlpXeHZjRzFsYm5RdGJHbHVhMlZrYVc0dFkyOXRjR0Z1ZVMweU1ESTBNVEV4TlJaVVIyOTJWMjVSTTFJMk5tWnZUVE50VUdGNE5qTm5BeFppTFRsMFJtcGFUbEowVDFOV2JVSmFiRzlDUmtaQkFBQUFBQUFBUERaRkZqbFNiakpUVDBGWFVsVkhNM0ZNVkU4eWExaFBibEVBTVdsamVYQmxZWE10YzI1ekxXUmxkbVZzYjNCdFpXNTBMV3hwYm10bFpHbHVMV052YlhCaGJua3RNakF5TkRFeE1UVVdWRWR2ZGxkdVVUTlNOalptYjAwemJWQmhlRFl6Wnc0V1lpMDVkRVpxV2s1U2RFOVRWbTFDV214dlFrWkdRUUFBQUFBQUFEdzJVQlk1VW00eVUwOUJWMUpWUnpOeFRGUlBNbXRZVDI1UkFERnBZM2x3WldGekxYTnVjeTFrWlhabGJHOXdiV1Z1ZEMxc2FXNXJaV1JwYmkxamIyMXdZVzU1TFRJd01qUXhNVEUxRmxSSGIzWlhibEV6VWpZMlptOU5NMjFRWVhnMk0yY05GbUl0T1hSR2FscE9VblJQVTFadFFscHNiMEpHUmtFQUFBQUFBQUE4Tms4V09WSnVNbE5QUVZkU1ZVY3pjVXhVVHpKcldFOXVVUUFCRmxSSGIzWlhibEV6VWpZMlptOU5NMjFRWVhnMk0yY0FBQT09IiwiZklkIjoieFgwVzBKY0JDZGpFUUxvRlpZcjIifx=="
    }

If you want to fetch the next page, just pass the returned pagination object along your next query:

Your second request to fetch more results

{
    "query": {
        "headcount": { ">": 10 }
    },
    "pagination": { 
      "size": 2,
      "token": "eyJzYSI6W1syXSxbMTI4ODQ5MDE5MDJdXSwiaWQiOiIwOGZzQXc4eGFXTjVjR1ZoY3kxemJuTXRaR1YyWld4dmNHMWxiblF0YkdsdWEyVmthVzR0WTI5dGNHRnVlUzB5TURJME1URXhOUlpVUjI5MlYyNVJNMUkyTm1adlRUTnRVR0Y0TmpObkJoWmlMVGwwUm1wYVRsSjBUMU5XYlVKYWJHOUNSa1pCQUFBQUFBQUFQRFpJRmpsU2JqSlRUMEZYVWxWSE0zRk1WRTh5YTFoUGJsRUFNV2xqZVhCbFlYTXRjMjV6TFdSbGRtVnNiM0J0Wlc1MExXeHBibXRsWkdsdUxXTnZiWEJoYm5rdE1qQXlOREV4TVRVV1ZFZHZkbGR1VVROU05qWm1iMDB6YlZCaGVEWXpad1VXWWkwNWRFWnFXazVTZEU5VFZtMUNXbXh2UWtaR1FRQUFBQUFBQUR3MlJ4WTVVbTR5VTA5QlYxSlZSek54VEZSUE1tdFlUMjVSQURGcFkzbHdaV0Z6TFhOdWN5MWtaWFpsYkc5d2JXVnVkQzFzYVc1clpXUnBiaTFqYjIxd1lXNTVMVEl3TWpReE1URTFGbFJIYjNaWGJsRXpValkyWm05Tk0yMVFZWGcyTTJjSUZtSXRPWFJHYWxwT1VuUlBVMVp0UWxwc2IwSkdSa0VBQUFBQUFBQThOa29XT1ZKdU1sTlBRVmRTVlVjemNVeFVUekpyV0U5dVVRQXhhV041Y0dWaGN5MXpibk10WkdWMlpXeHZjRzFsYm5RdGJHbHVhMlZrYVc0dFkyOXRjR0Z1ZVMweU1ESTBNVEV4TlJaVVIyOTJWMjVSTTFJMk5tWnZUVE50VUdGNE5qTm5CeFppTFRsMFJtcGFUbEowVDFOV2JVSmFiRzlDUmtaQkFBQUFBQUFBUERaSkZqbFNiakpUVDBGWFVsVkhNM0ZNVkU4eWExaFBibEVBTVdsamVYQmxZWE10YzI1ekxXUmxkbVZzYjNCdFpXNTBMV3hwYm10bFpHbHVMV052YlhCaGJua3RNakF5TkRFeE1UVVdWRWR2ZGxkdVVUTlNOalptYjAwemJWQmhlRFl6WndvV1lpMDVkRVpxV2s1U2RFOVRWbTFDV214dlFrWkdRUUFBQUFBQUFEdzJUQlk1VW00eVUwOUJWMUpWUnpOeFRGUlBNbXRZVDI1UkFERnBZM2x3WldGekxYTnVjeTFrWlhabGJHOXdiV1Z1ZEMxc2FXNXJaV1JwYmkxamIyMXdZVzU1TFRJd01qUXhNVEUxRmxSSGIzWlhibEV6VWpZMlptOU5NMjFRWVhnMk0yY0pGbUl0T1hSR2FscE9VblJQVTFadFFscHNiMEpHUmtFQUFBQUFBQUE4TmtzV09WSnVNbE5QUVZkU1ZVY3pjVXhVVHpKcldFOXVVUUF4YVdONWNHVmhjeTF6Ym5NdFpHVjJaV3h2Y0cxbGJuUXRiR2x1YTJWa2FXNHRZMjl0Y0dGdWVTMHlNREkwTVRFeE5SWlVSMjkyVjI1Uk0xSTJObVp2VFROdFVHRjROak5uREJaaUxUbDBSbXBhVGxKMFQxTldiVUphYkc5Q1JrWkJBQUFBQUFBQVBEWk9GamxTYmpKVFQwRlhVbFZITTNGTVZFOHlhMWhQYmxFQU1XbGplWEJsWVhNdGMyNXpMV1JsZG1Wc2IzQnRaVzUwTFd4cGJtdGxaR2x1TFdOdmJYQmhibmt0TWpBeU5ERXhNVFVXVkVkdmRsZHVVVE5TTmpabWIwMHpiVkJoZURZelp3c1dZaTA1ZEVacVdrNVNkRTlUVm0xQ1dteHZRa1pHUVFBQUFBQUFBRHcyVFJZNVVtNHlVMDlCVjFKVlJ6TnhURlJQTW10WVQyNVJBREZwWTNsd1pXRnpMWE51Y3kxa1pYWmxiRzl3YldWdWRDMXNhVzVyWldScGJpMWpiMjF3WVc1NUxUSXdNalF4TVRFMUZsUkhiM1pYYmxFelVqWTJabTlOTTIxUVlYZzJNMmNBRm1JdE9YUkdhbHBPVW5SUFUxWnRRbHBzYjBKR1JrRUFBQUFBQUFBOE5rSVdPVkp1TWxOUFFWZFNWVWN6Y1V4VVR6SnJXRTl1VVFBeGFXTjVjR1ZoY3kxemJuTXRaR1YyWld4dmNHMWxiblF0YkdsdWEyVmthVzR0WTI5dGNHRnVlUzB5TURJME1URXhOUlpVUjI5MlYyNVJNMUkyTm1adlRUTnRVR0Y0TmpObkFoWmlMVGwwUm1wYVRsSjBUMU5XYlVKYWJHOUNSa1pCQUFBQUFBQUFQRFpFRmpsU2JqSlRUMEZYVWxWSE0zRk1WRTh5YTFoUGJsRUFNV2xqZVhCbFlYTXRjMjV6TFdSbGRtVnNiM0J0Wlc1MExXeHBibXRsWkdsdUxXTnZiWEJoYm5rdE1qQXlOREV4TVRVV1ZFZHZkbGR1VVROU05qWm1iMDB6YlZCaGVEWXpad0VXWWkwNWRFWnFXazVTZEU5VFZtMUNXbXh2UWtaR1FRQUFBQUFBQUR3MlF4WTVVbTR5VTA5QlYxSlZSek54VEZSUE1tdFlUMjVSQURGcFkzbHdaV0Z6TFhOdWN5MWtaWFpsYkc5d2JXVnVkQzFzYVc1clpXUnBiaTFqYjIxd1lXNTVMVEl3TWpReE1URTFGbFJIYjNaWGJsRXpValkyWm05Tk0yMVFZWGcyTTJjRUZtSXRPWFJHYWxwT1VuUlBVMVp0UWxwc2IwSkdSa0VBQUFBQUFBQThOa1lXT1ZKdU1sTlBRVmRTVlVjemNVeFVUekpyV0U5dVVRQXhhV041Y0dWaGN5MXpibk10WkdWMlpXeHZjRzFsYm5RdGJHbHVhMlZrYVc0dFkyOXRjR0Z1ZVMweU1ESTBNVEV4TlJaVVIyOTJWMjVSTTFJMk5tWnZUVE50VUdGNE5qTm5BeFppTFRsMFJtcGFUbEowVDFOV2JVSmFiRzlDUmtaQkFBQUFBQUFBUERaRkZqbFNiakpUVDBGWFVsVkhNM0ZNVkU4eWExaFBibEVBTVdsamVYQmxZWE10YzI1ekxXUmxkbVZzYjNCdFpXNTBMV3hwYm10bFpHbHVMV052YlhCaGJua3RNakF5TkRFeE1UVVdWRWR2ZGxkdVVUTlNOalptYjAwemJWQmhlRFl6Wnc0V1lpMDVkRVpxV2s1U2RFOVRWbTFDV214dlFrWkdRUUFBQUFBQUFEdzJVQlk1VW00eVUwOUJWMUpWUnpOeFRGUlBNbXRZVDI1UkFERnBZM2x3WldGekxYTnVjeTFrWlhabGJHOXdiV1Z1ZEMxc2FXNXJaV1JwYmkxamIyMXdZVzU1TFRJd01qUXhNVEUxRmxSSGIzWlhibEV6VWpZMlptOU5NMjFRWVhnMk0yY05GbUl0T1hSR2FscE9VblJQVTFadFFscHNiMEpHUmtFQUFBQUFBQUE4Tms4V09WSnVNbE5QUVZkU1ZVY3pjVXhVVHpKcldFOXVVUUFCRmxSSGIzWlhibEV6VWpZMlptOU5NMjFRWVhnMk0yY0FBQT09IiwiZklkIjoieFgwVzBKY0JDZGpFUUxvRlpZcjIifx=="
    }
}

The response will contain the next page and a new pagination token. Take the new pagination token and keep going until you run out of results.

caution

You cannot change the query between your initial request and your subsequent request using the pagination token. It will result in unwanted behavior.

Also, each token has an expiration date, so you will not be able to reuse it indefinitely.

Include/Exclude specs

The Include/Exclude field can contains two arrays:

1. include array which lists what needs to be included in the query.
2. 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.

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

Example

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

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