API - Search People

Use Search People when you know who you're looking for but don't have their details yet. For example: "heads of marketing at software companies in France". You describe the people and companies you want, and Surfe returns a list of matches with their name, job title, company and LinkedIn URL.

To get emails and phone numbers for the people you find, use the Enrichment API guide afterwards. The full technical reference is in the API documentation.

Before you start

You'll need:

• Your API key. This is your personal password for the Surfe API. Find your API key.
• A way to send a request, such as Postman or a script your developer set up. A request is a message you send to Surfe describing what you want.

Your first search

Send your request to this address (the endpoint): POST https://api.surfe.com/v2/people/search

Add two headers (extra details sent with every request):

{
  "Authorization": "Bearer YOUR_API_KEY",
  "Content-Type": "application/json"
}

Keep the word Bearer and a space before your key.

The body of your request lists your filters. This one looks for C-level CEOs at surfe.com:

{
  "companies": {
    "domains": [
      "surfe.com"
    ]
  },
  "limit": 10,
  "pageToken": "",
  "people": {
    "jobTitles": [
      "CEO"
    ],
    "seniorities": [
      "C-Level"
    ]
  }
}

What to change:

• domains: the company websites you want to search, e.g. "surfe.com".
• jobTitles: the roles you're looking for. Similar titles are included automatically, so "CTO" also finds "Chief Technology Officer". Exact matches appear first. To match only the exact title you type, use exactJobTitles instead.
• seniorities: the level of seniority, e.g. "C-Level" or "Founder / Owner".
• limit: how many results you want back (1 to 200).
• Leave pageToken empty for your first request.

Narrow your search

Add more filters to get more relevant results. Filters about the person go under people. Filters about their company go under companies.

About the person

About their company

Many filters have an "excluded" version to leave things out, for example industriesExcluded or domainsExcluded.

A few more filters exist (such as keywords and NAICS codes). See the API reference for the full list, including which filters have an excluded version.

Some filters only accept set values. Look them up first:

• industries and seniorities: use the Get Filters endpoint.
• departmentClassifications: use the department and sub-department codes list. Use the code (e.g. information_technology_it), not the display name. Leave the sub-departments empty to match the whole department.
• technologies: use the technologies list. These are case-sensitive.
• departmentSizes: this filter uses the older department names (e.g. "Engineering"), not the department codes above.

Tip: combine departmentClassifications with seniorities to reach a specific level within a team. For example, directors in Revenue Operations.

Good to know

• Limiting people per company. peoplePerCompany (1 to 40) limits how many people you get per company, but only when you search by company domain or name alone. If your search includes any other criteria, it's ignored. For more in-depth results, search a single domain and leave this setting out.
• Ranges. For employeeCount and revenue, to must be greater than from, and a to of 0 or less is ignored. For yearFounded, to must be greater than from (maximum 9999).

Understand your results

Here's the response to the first search above:

{
  "people": [
    {
      "companyDomain": "surfe.com",
      "companyName": "Surfe Inc",
      "country": "us",
      "departmentClassifications": [
        {
          "department": "executive_c_suite",
          "subdepartments": [
            "chief_executive_officer_ceo"
          ]
        }
      ],
      "departments": [
        "Founder/Owner"
      ],
      "firstName": "David",
      "jobTitle": "Co-Founder & CEO",
      "lastName": "Chevalier",
      "linkedInUrl": "https://www.linkedin.com/in/david-maurice-chevalier",
      "seniorities": [
        "C-Level"
      ]
    }
  ],
  "total": 1
}

Each person in the results includes their firstName, lastName, jobTitle, companyName, companyDomain, country (a short code like us), linkedInUrl, seniorities and departmentClassifications.

The response also includes total (the number of results returned). If there are more results than your limit, it also includes a nextPageToken (see "Get more results").

If you sent organizationIDMappings (for example { "surfe.com": "your-id-123" }), people at those companies also include your ID in externalID.

No results?

Each filter you add narrows your results. If a search returns nothing:

• Start with just the company domain, then add one filter at a time to see which one removes your results.
• Check your industry values. An industry that isn't on the Get Filters list returns no results instead of an error.
• Check that your ranges are valid (to greater than from).
• Check that you haven't reached your daily quota. If you have, further searches are blocked until it resets. See "Credits and quota" below.

Get more results

If your search matches more people than your limit, the response includes a nextPageToken. Think of it as a bookmark for the next page of results.

1. Run your first search with an empty pageToken.
2. Copy the nextPageToken from the response.
3. Send a new request with just these two fields. Your original filters carry over automatically:

{
  "limit": 10,
  "pageToken": "PAGE_TOKEN_FROM_PREVIOUS_RESPONSE"
}

Repeat to get more results.

Credits and quota

Results count towards your people search quota. The standard quota is 200 people search results per day, and it resets at midnight in your local time. If you reach it, further searches are blocked until the reset. Contact our support team if you need a higher limit.

When search credits are enabled on your account, each call deducts ⌈results returned / 10⌉ search credits. For example, 1 to 10 results cost 1 credit, 11 to 20 results cost 2 credits and 21 to 30 results cost 3 credits. You're charged for the results actually returned, not for your limit. Only the last page may return fewer results than requested. For the best credit usage, request results in multiples of 10 (e.g. limit: 10, 20 or 100).

→ See: API - Credits & Quotas

Need help?

• Seeing an error? See the error codes article.
• Want emails and phone numbers for your results? See the Enrichment API guide.
• Still stuck? Contact our support team via Zendesk.