Enrich People (start)

Starts an asynchronous bulk enrichment job for the provided list of people.

Include the fields you want to enrich in include and provide at least one valid identifier for each person:

• linkedinUrl; or
• firstName, lastName, and either companyName or companyDomain.

Set include.linkedInUrl to return additional profile data from Surfe’s internal database and external pre-enrichment providers.

Credit usage depends on the cascades you request and the valid results found:

• The regular email cascade costs 1 email credit per email found. Enable it with include.email.
• The personal email cascade costs 2 email credits per personal email found. It is optimized for better find rate and speed when searching for personal emails. Enable include.email and set enrichmentOptions.acceptedEmailType to personal. Contact Surfe API Support to enable this cascade.
• The mobile cascade costs 1 mobile credit per valid mobile phone found. Enable it with include.mobile.

When the personal email cascade is enabled, include.mobile is ignored.

The response returns an enrichmentID and an enrichmentCallbackURL. Use these values to track the job and retrieve the results after processing completes.

We recommend setting notificationOptions.webhookUrl when creating the job. When the enrichment completes, Surfe sends the results to your webhook using the person.enrichment.completed event. See the webhook documentation for details.

If you do not use webhooks, you can check progress and retrieve completed results with GET /v2/people/enrich/:id. Polling is supported, but webhooks are more efficient and avoid unnecessary delay or load.

curl -X POST "https://api.surfe.com/v2/people/enrich" \
  -H "X-Request-Origin: <string>" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "enrichmentOptions": {
      "acceptedEmailType": "professional",
      "skipMobileEnrichmentIfNoEmailFound": false
    },
    "include": {
      "email": true,
      "jobHistory": false,
      "linkedInUrl": false,
      "mobile": true
    },
    "notificationOptions": {
      "webhookUrl": ""
    },
    "people": [
      {
        "companyDomain": "surfe.com",
        "companyName": "Surfe",
        "externalID": "external-id",
        "firstName": "David",
        "lastName": "Chevalier",
        "linkedinUrl": "https://www.linkedin.com/in/david-maurice-chevalier"
      }
    ]
  }'

{
  "enrichmentCallbackURL": "https://api.surfe.com/v2/people/enrich/0195be44-1a0d-718a-967b-042c9d17ffd7",
  "enrichmentID": "0195be44-1a0d-718a-967b-042c9d17ffd7",
  "message": "Your enrichment has started ✨, estimated time: 2 seconds."
}