Search people

Quota limitation

Results received from this endpoint count towards the people search quota

Search for people based on the provided filters. Note that some filters only accept pre-defined values, as provided by the filters endpoint.

Job title matching

Job titles provided in peopleFilters.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"; "CTO" may also match "VP of Technology".
Exact matches appear first in results; semantic matches appear lower.

If you need stricter matching (exact titles only, no semantic expansion), contact api.support@surfe.com — this can be enabled per integration.

Example request

curl -X POST https://api.surfe.com/v2/people/search \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "limit": 10,
    "people": {
      "jobTitles": ["Chief Technology Officer", "VP of Engineering"],
      "seniorities": ["C-Level", "Director"],
      "countries": ["us", "gb"]
    },
    "companies": {
      "industries": ["Software"],
      "employeeCount": { "from": 201, "to": 1000 }
    }
  }'

Pagination

Use the nextPageToken field from the response to fetch the next page. Pass it as pageToken in your next request — the original filters are reused automatically.

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

Authorization

AuthorizationRequiredBearer <token>

In: header

Request Body

application/jsonRequired

List of filters to use as search criteria

companiesobject

limitinteger

Limit - Is the maximum amount of results per page, must be between 1 and 200

Default: 10Minimum: 1Maximum: 200

pageTokenstring

PageToken - token to retrieve the next page of results. When provided, the filters originally used for the first page are reused and any changes to filters are ignored.

peopleobject

peoplePerCompanyinteger

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.

curl -X POST "https://api.surfe.com/v2/people/search" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "companies": {
      "countries": [
        "fr",
        "W-EMEA"
      ],
      "departmentSizes": [
        {
          "department": "Engineering",
          "from": 10,
          "to": 100
        }
      ],
      "domains": [
        "surfe.com"
      ],
      "domainsExcluded": [
        "surfshop.fr"
      ],
      "employeeCount": {
        "from": 1,
        "to": 999999999999999
      },
      "industries": [
        "CRM",
        "Software",
        "SaaS",
        "Internet"
      ],
      "industriesExcluded": [
        "Retail",
        "E-commerce"
      ],
      "keywords": [
        "AI",
        "Machine Learning",
        "Blockchain"
      ],
      "keywordsExcluded": [
        "Google"
      ],
      "localities": [
        {
          "countries": [
            "string"
          ],
          "freeTexts": [
            "string"
          ],
          "isPrimary": true,
          "states": [
            {
              "code": "string",
              "country": "string"
            }
          ],
          "zipCodes": [
            {
              "countryCode": "string",
              "zipCode": "string"
            }
          ]
        }
      ],
      "naicsCodes": [
        561312
      ],
      "naicsCodesExcluded": [
        111
      ],
      "names": [
        "Surfe",
        "Leadjet"
      ],
      "revenue": {
        "from": 1,
        "to": 999999999999999
      },
      "technologies": [
        "MySQL",
        "RSS"
      ],
      "technologiesExcluded": [
        "Marketo",
        "Pardot"
      ],
      "technologyCategories": [
        "Font scripts"
      ],
      "technologyCategoriesExcluded": [
        "Referral marketing"
      ],
      "yearFounded": {
        "from": 1,
        "to": 999999999999999
      }
    },
    "limit": 10,
    "pageToken": "",
    "people": {
      "countries": [
        "fr",
        "W-EMEA"
      ],
      "departments": [
        "Management"
      ],
      "exactJobTitles": [
        "Co-Founder & CEO"
      ],
      "jobChangePeriodInDays": 1,
      "jobTitles": [
        "CEO",
        "CTO"
      ],
      "previousCompanyDomains": [
        "oddo-bhf.com"
      ],
      "seniorities": [
        "Founder",
        "C-Level"
      ],
      "states": [
        {
          "code": "string",
          "country": "string"
        }
      ]
    },
    "peoplePerCompany": 5
  }'

List of people found

{
  "nextPageToken": "string",
  "people": [
    {
      "companyDomain": "surfe.com",
      "companyName": "Surfe",
      "country": "France",
      "departments": [
        "Management",
        "Founder/Owner"
      ],
      "firstName": "David",
      "jobTitle": "Co-Founder & CEO",
      "lastName": "Chevalier",
      "linkedInUrl": "https://www.linkedin.com/in/david-maurice-chevalier/",
      "seniorities": [
        "Founder",
        "C-Level"
      ]
    }
  ],
  "total": 0
}