Skip to main content

API - Search People

David S
Updated

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.

Results received from this endpoint count towards the people search quota.

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.

 

Step 1: Get Your API Key

  1. Go to https://dashboard.surfe.com

  2. 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:

  • companies

    • countries (deprecated — use localities instead)

    • departmentSizes

    • domains

    • domainsExcluded

    • employeeCount

    • industries

    • industriesExcluded

    • keywords

    • keywordsExcluded

    • localities

    • naicsCodes

    • naicsCodesExcluded

    • names revenue

    • technologies

    • technologiesExcluded

    • technologyCategories

    • technologyCategoriesExcluded

    • yearFounded

  • people

    • countries

    • departments

    • exactJobTitles

    • jobChangePeriodInDays

    • jobTitles

    • previousCompanyDomains

    • seniorities

    • states

  • limit

  • pageToken

  • peoplePerCompany

 

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(deprecated): This filter has been deprecated. Use the localities filter instead for more in-depth location searches.

    Then add these new descriptions after it:

  • localities: Search for companies by location. Accepts countries and world regions, specific regions within a country, specific zip codes, or free text within a company's full address. Any locality filter can be set to target HQ locations only or any location.

  • naicsCodes: Search by NAICS industry codes.

  • naicsCodesExcluded: Exclude specific NAICS industry codes from results.

  • industriesExcluded: Exclude specific industries from results.

  • technologies: Search by technologies used by a company.

  • technologiesExcluded: Exclude specific technologies from results.

  • technologyCategories: Search by technology categories.

  • technologyCategoriesExcluded: Exclude specific technology categories from results.

  • departmentSizes: Search by a specific department within a specific range of employees.

  • keywords: Search by specific keywords associated with a company.

  • keywordsExcluded: Exclude specific keywords from results.

  • yearFounded: Search for companies founded within a specific time range. Set from and to values.

  • domains: The company domain (e.g. surfe.com)

  • domainsExcluded: Company domains excluded from the search.

  • limit: Max number of results (1–200, default is 10)

  • jobTitles & seniorities: Helps narrow your results.

  • exactJobTitles: Search by exact job titles without expanding to similar or related titles. Use this when you need strict matching.

  • jobChangePeriodInDays: Search for people who have recently changed jobs within the specified number of days.

  • previousCompanyDomains: Search by a person's previous companies using their domain (e.g. surfe.com).

  • states: Search for people within a specific region within a country. Each state requires a code and country value.

  • peoplePerCompany: Limits the number of people returned per company when searching by domain or name only. Valid values are between 1 and 5. For more in-depth results, search using a single domain and omit this parameter. This field is ignored if the search includes criteria beyond domain or name.

Job Title Matching

 

Job titles provided in jobTitles are expanded automatically:

  • Acronym matching is bidirectional — searching for "CTO" also matches "Chief Technology Officer" and vice versa. You do not need to submit both forms.

  • Semantic matching additionally surfaces closely related titles — for example "Director of Engineering" may also match "VP of Engineering" or "Head of Engineering"

  • Exact matches appear first in results, semantic matches appear lower

If you need stricter matching with no semantic expansion, use the exactJobTitles filter instead, or contact support via intercom to enable this per integration.

 

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": {
      "departmentSizes": [
        {
          "department": "Engineering",
          "from": 10,
          "to": 100
        }
      ],
      "domains": [
        "surfe.com"
      ],
      "employeeCount": {
        "from": 1,
        "to": 999999999999999
      },
      "industries": [
        "Software",
        "SaaS"
      ],
      "keywords": [
        "AI",
        "Machine Learning"
      ],
      "localities": [
        {
          "country": "fr"
        }
      ],
      "names": [
        "Surfe"
      ],
      "revenue": {
        "from": 1,
        "to": 999999999999999
      },
      "technologies": [
        "MySQL"
      ],
      "yearFounded": {
        "from": 2010,
        "to": 2024
      }
    },
    "limit": 10,
    "pageToken": "",
    "people": {
      "countries": [
        "fr"
      ],
      "departments": [
        "Management"
      ],
      "exactJobTitles": [
        "Co-Founder & CEO"
      ],
      "jobChangePeriodInDays": 30,
      "jobTitles": [
        "CEO"
      ],
      "previousCompanyDomains": [
        "surfe.com"
      ],
      "seniorities": [
        "Founder"
      ],
      "states": [
        {
          "code": "IDF",
          "country": "fr"
        }
      ]
    },
    "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.

  1. Send first request with blank pageToken

  2. Get nextPageToken in the response

  3. Add it into the next request in pageToken

  4. Repeat 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.

 

Additional Resources

Comments

0 comments

Please sign in to leave a comment.