If you're looking to find people based on their job title, company, or location using the Surfe API, the Search People endpoint is your go-to tool.
The Search People (V2) endpoint lets you:
Search for professionals by job title, seniority, company, country, and more.
Narrow your search using filters like industry, employee size, or department.
Return a list of matching people including name, title, company, and LinkedIn info.
Some filters (like job title or seniority) only accept specific values. To see what's available, check the Filters API. This ensures your search works correctly.
To use this endpoint, you'll need:
A valid Surfe API Key
Basic understanding of JSON (we’ll help with that!)
A tool to send API requests (like Postman or a developer who can help you test it)
Here is a step-by-step guide on how you can retrieve what is needed to start calling through our API.
Log in and navigate to the API Key section.
Copy your API key (you'll need it for authorization).
Don’t share your API key publicly, it gives access to your account.
Step 2: Build your request with filters
Endpoint v2/people/search
Headers (Required)
Authorization: Bearer YOUR_API_KEY (Ensure to paste the token you copied in the first step in the authorization section! You will need to include Bearer TOKEN)
Example:
Authentication: Authorization: Bearer SurfeRocks2025APIKey
Content-Type: application/json
Full list of fields:
companiescountriesdomainsdomainsExcludedemployeeCountindustriesnamesrevenue
peoplecountriesdepartmentsjobTitlesseniorities
limitpageTokenpeoplePerCompany
Example of body for the API request:
{
"companies": {
"countries": [
"fr"
],
"domains": [
"surfe.com"
]
},
"limit": 10,
"pageToken": "",
"people": {
"jobTitles": [
"CEO"
],
"seniorities": [
"Founder"
]
},
"peoplePerCompany": 5
}
What these fields mean:
countries: Use 2-letter ISO country codes (e.g. "fr" for France)domains: The company domain (e.g. surfe.com)limit: Max number of results (1–200, default is 10)jobTitles&seniorities: Helps narrow your resultspeoplePerCompany: Caps how many results per company
cURL request example (feel free to copy and import this into your programme such as Postman)
curl --location 'https://api.surfe.com/v2/people/search' \
--header 'Authorization: Bearer YOUR_API_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
"companies": {
"countries": [
"fr"
],
"domains": [
"surfe.com"
]
},
"limit": 10,
"pageToken": "",
"people": {
"jobTitles": [
"CEO"
],
"seniorities": [
"Founder"
]
},
"peoplePerCompany": 5
}'
Step 3: Send the request and receive the response:
Here is an example response based on the request built with filters. It will pull information for contacts and their information!
{
"people": [
{
"firstName": "David",
"lastName": "Chevalier",
"companyName": "Surfe",
"companyDomain": "surfe.com",
"linkedInUrl": "https://www.linkedin.com/in/david-maurice-chevalier",
"jobTitle": "Co-Founder & CEO",
"seniorities": [
"Founder",
"C-Level"
],
"departments": [
"Management",
"Founder/Owner"
],
"country": "fr"
}
],
"total": 1
}
PaginationToken:
If your search returns a lot of results, use pagination to fetch them in batches.
Send first request with blank
pageTokenGet
nextPageTokenin the responseAdd it into the next request in
pageTokenRepeat to get more results
Think of pageToken like a bookmark, each one helps you pick up where the last search left off.
Example response with nextPageToken:
],
"total": 16815495,
"nextPageToken": "eyJxdWVyeUlEIjoiZWRjNTJmZGEtYzM4MS00YTZlLWI2OWYtMTE4MjhhOGQ3OTJiIiwib2Zmc2V0IjoxMH0="
You will need to use this in the request body again to go to the next page of results. Simple copy and paste the token into the pageToken field in the same request body you just called:
"companies": {
"countries": [
"fr"
],
"domains": [
"surfe.com"
]
},
"limit": 10,
"pageToken": "eyJxdWVyeUlEIjoiZWRjNTJmZGEtYzM4MS00YTZlLWI2OWYtMTE4MjhhOGQ3OTJiIiwib2Zmc2V0IjoxMH0=",
"people": {
"jobTitles": [
"CEO"
],
"seniorities": [
"Founder"
]
},
"peoplePerCompany": 5
}'
Click send again and this will then return the next page of the results in the request.
To retrieve the next page of results you will need to copy and paste the next page token after each response has been retrieved. They look very similar, but they are different and will pull the next page of results!
Seeing error codes? Check out the article here for specific errors and how to troubleshoot.
Now that you’ve found people, you can enrich them with emails, phone numbers, job titles, and more. Head over to our Enrichment API guide to get started!
If you have any questions or need further assistance, feel free to reach out to our support team via Intercom.