Search Contacts

Quota limitation

Results received from this endpoint count towards the contact search quota

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, in order 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.

Authorization

AuthorizationRequiredBearer <token>

In: header

Request Body

application/jsonRequired

List of filters to use as search criteria

enrichmentTypeRequiredstring

Type of enrichment to execute

Value in: "email" | "emailAndMobile"

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

The number of people to be found per each organization. When using this filter the organizationFilters.includeDomains field needs to be present and include at least 1 domain and all the rest of organizationFilters cannot be present in the request

Minimum: 1Maximum: 100

requestedRequiredinteger

The maximum amount of results

Minimum: 1Maximum: 5000

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 '{
    "enrichmentType": "email",
    "organizationFilters": {
      "departmentSizes": [
        {
          "department": "Engineering",
          "from": 10,
          "to": 100
        }
      ],
      "employeeCounts": [
        "51-200",
        "201-500"
      ],
      "excludeDomains": [
        "surfe.com",
        "apple.com",
        "microsoft.com"
      ],
      "includeDomains": [
        "surfe.com",
        "apple.com",
        "microsoft.com"
      ],
      "includeNames": [
        "Surfe",
        "Apple",
        "Microsoft"
      ],
      "industries": [
        "Aerospace",
        "Software"
      ],
      "keywords": [
        "Recruitment",
        "Education"
      ],
      "locations": [
        "fr",
        "es"
      ],
      "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"
      ],
      "jobTitles": [
        "Software engineer",
        "Programmer"
      ],
      "keywords": [
        "Recruitment",
        "Education"
      ],
      "seniorities": [
        "Manager",
        "Head"
      ]
    },
    "peoplePerOrganization": 10,
    "requested": 10,
    "searchName": "My list name"
  }'

List of contacts found and 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"
    }
  ]
}

Search Contacts

Authorization

Request Body

Response

TypeScript