Surfe API
Get API KeySupportGive feedback

(Deprecated) Search People

Closed to new integrations

This endpoint is deprecated and closed to new integrations by default. New integrations must use Search People v2. Existing integrations that still rely on v1 can contact api.support@surfe.com for legacy enablement; all other calls will return 403 Feature Not Available.

Quota limitation

Results received from this endpoint count towards the people search quota

No pagination

This endpoint does not support pagination. Results are capped at the value you specify in requested. To page through results, use Search People v2.

Search for contacts based on the provided filters. Additionally, this endpoint will automatically start the bulk enrichment of the search results. The enrichment will run asynchronously; to check the enrichment's progress and results, send a request to GET /v1/people/enrichments/bulk/{id}. Note that some filters only accept pre-defined values, as provided by the filters endpoint.

Example request

curl -X POST https://api.surfe.com/v1/people/search \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "searchName": "Enterprise CTOs",
    "enrichmentType": "emailAndMobile",
    "requested": 50,
    "peopleFilters": {
      "jobTitles": ["Chief Technology Officer", "VP of Engineering"],
      "seniorities": ["C-Level", "Director"]
    },
    "organizationFilters": {
      "industries": ["Software"],
      "employeeCounts": ["201-500", "501-1000"]
    }
  }'
POST
/v1/people/search

Authorization

AuthorizationRequiredBearer <token>

In: header

Request Body

application/jsonRequired

List of filters to use as search criteria

enrichmentOptionsobject

Options to apply to the enrichment. If not provided, default options will be used.

enrichmentTypeRequiredstring
Value in: "email" | "mobile" | "emailAndMobile" | "noOp"
organizationFiltersobject

Filters that describe the organization where the person to look for works

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

peopleFiltersobject

Filters that describe the person to look for

peoplePerOrganizationinteger

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.

requestedRequiredinteger

The maximum amount of results

Minimum: 1Maximum: 10000
searchNameRequiredstring

Name for the new list that will created to store the results

curl -X POST "https://api.surfe.com/v1/people/search" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "enrichmentOptions": {
      "shouldEnrichJobHistory": true,
      "shouldPreEnrichLinkedInProfile": true,
      "skipMobileEnrichmentIfNoEmailFound": false
    },
    "enrichmentType": "email",
    "organizationFilters": {
      "departmentSizes": [
        {
          "department": "Engineering",
          "from": 10,
          "to": 100
        }
      ],
      "employeeCounts": [
        "51-200",
        "201-500"
      ],
      "excludeDomains": [
        "surfe.com",
        "apple.com",
        "microsoft.com"
      ],
      "excludeNaicsCodes": [
        0
      ],
      "includeDomains": [
        "surfe.com",
        "apple.com",
        "microsoft.com"
      ],
      "includeNames": [
        "Surfe",
        "Apple",
        "Microsoft"
      ],
      "industries": [
        "Aerospace",
        "Software"
      ],
      "keywords": [
        "Recruitment",
        "Education"
      ],
      "locations": [
        "fr",
        "es"
      ],
      "naicsCodes": [
        0
      ],
      "primaryLocations": [
        "fr",
        "es"
      ],
      "revenues": [
        "0-1M",
        "1-10M"
      ],
      "states": [
        {
          "abbreviation": "IDF",
          "countryAlpha2": "fr"
        }
      ],
      "technologies": [
        "Mixpanel",
        "Salesforce"
      ]
    },
    "organizationIDMappings": {
      "apple.com": "external-id-2",
      "surfe.com": "external-id-1"
    },
    "peopleFilters": {
      "countries": [
        "fr",
        "es"
      ],
      "departments": [
        "Engineering",
        "R&D"
      ],
      "exactJobTitles": [
        "CEO",
        "CTO"
      ],
      "jobChangePeriodInDays": 90,
      "jobTitles": [
        "Software engineer",
        "Programmer"
      ],
      "keywords": [
        "Recruitment",
        "Education"
      ],
      "previousCompanyDomains": [
        "surfe.com"
      ],
      "seniorities": [
        "Manager",
        "Head"
      ],
      "states": [
        {
          "abbreviation": "IDF",
          "countryAlpha2": "fr"
        }
      ]
    },
    "peoplePerOrganization": 0,
    "requested": 10,
    "searchName": "My list name"
  }'

List of people found, along with an enrichment ID

{
  "id": "enrichment-id",
  "people": [
    {
      "clientID": "DEPRECATED",
      "companyID": "DEPRECATED",
      "companyName": "ACME corp",
      "companyWebsite": "www.acme.org",
      "country": "United States",
      "departments": [
        "Engineering",
        "R&D"
      ],
      "externalID": "external-id",
      "facebookUrl": "https://www.facebook.com/janedoe",
      "firstName": "Jane",
      "id": "unique-id",
      "jobTitle": "Software engineer",
      "lastName": "Doe",
      "linkedinUrl": "https://www.linkedin.com/in/janedoe/",
      "location": "Arizona",
      "name": "Jane Doe",
      "seniorities": [
        "Manager",
        "Head"
      ],
      "subdepartments": [
        "Software Development",
        "Product Management"
      ],
      "twitterUrl": "https://www.twitter.com/janedoe"
    }
  ]
}