Search people

Quota limitation

Results received from this endpoint count towards the people search quota

Credits

When credit charging is enabled for your account, each call deducts ⌈results returned / 10⌉ ICP search credits (e.g. 1 to 10 results = 1 credit, 11 to 20 results = 2 credits, 21 to 30 results = 3 credits). Credits are charged on results returned, not limit — only the last page may return fewer results than requested. For optimal credit usage, request results in multiples of 10 (e.g. limit: 10, 20, 100).

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

organizationIDMappingsobject

Mapping of an organization domain to its corresponding ID. Search results associated with the same organization will return this ID in the externalID field

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": 9999
      }
    },
    "limit": 10,
    "organizationIDMappings": {
      "apple.com": "external-id-2",
      "surfe.com": "external-id-1"
    },
    "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"
      ],
      "externalID": "id-company1",
      "firstName": "David",
      "jobTitle": "Co-Founder & CEO",
      "lastName": "Chevalier",
      "linkedInUrl": "https://www.linkedin.com/in/david-maurice-chevalier/",
      "seniorities": [
        "Founder",
        "C-Level"
      ]
    }
  ],
  "total": 0
}