API - Enrich People - Understanding Surfe's Asynchronous Split Request – SURFE

In this article, we’ll walk through how asynchronous split requests work, why Surfe uses them, and how you can work with them confidently.

People Search is one of our most-used features. As more users start integrating it, a common question has come up:

“Why does the search process happen in two steps?”

We’ll break it down in simple terms, no technical background needed.

Why Two Steps?

To ensure efficiency and speed, the People Search API operates asynchronously. This means:

Initiate a Search: You send a request with your search criteria.
Retrieve Results: You receive a unique ID to check back later for the results.

This approach allows the system to process complex searches without making you wait or have the risk of a timeout.

When you search for someone’s details using Enrich People endpoint, the system needs to find and verify that information. That can take a few seconds so rather than locking up your app during that time, Surfe gives you an id, and you check back later (or poll periodically) to see when it’s done. Or the recommended approach is to use Webhooks.

The API Endpoints needed on the Surfe Public API (the same logic applies for bulk endpoints).

If you do not have people ready to enrich you can check out this guide here.

Step-by-Step Guide

Start Your Enrichment Request

Send a POST request to the Enrich People (start) endpoint.

Example Request: (feel free to copy and import the cURL to use)

curl --location 'https://api.surfe.com/v2/people/enrich' \
--header 'Authorization: Bearer TOKEN' \
--header 'Content-Type: application/json' \
--data '{
    "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"
      }
    ]
  }'

Please note that you need to provide the attributes in the request body as explained here. Also replace the TOKEN with your API token.

Example Response:

"message": "Your enrichment has started ✨, estimated time: 1s.",
    "enrichmentID": "0197abba-f2ed-7986-8a3a-bf6baa35cdbc",
    "enrichmentCallbackURL": "https://api.surfe.com/v2/people/enrich/0197abba-f2ed-7986-8a3a-bf6baa35cdbc"

This response indicates that your search has been initiated. You can use the enrichmentID to retrieve the results.

We have two options to retrieve the results, manually or through webhook notifications.

Check for Results

Use the enrichmentID from step 1 to poll the status of your search using the second API endpoint Enrich People(get)

Example Request:

curl -X GET "https://api.surfe.com/v2/people/enrich/<id>" \
  -H "Authorization: Bearer TOKEN"

Replace the enrichmentID with the value in the response from the first API. It will look something like this:

curl -X GET "https://api.surfe.com/v2/people/enrich/01966325-3279-7c28-84ca-de3e7cd1785f" \
  -H "Authorization: Bearer TOKEN"

Possible Responses:

If the search is still processing the status will show “IN_PROGRESS”. Try to send the same request again after a few seconds.

{
  "enrichmentID": "your-enrichment-id",
  "people": [],
  "percentCompleted": 50,
  "status": "IN_PROGRESS"
}

Once the search is complete, status will display “COMPLETED”

{
    "enrichmentID": "0197abba-f2ed-7986-8a3a-bf6baa35cccc",
    "status": "COMPLETED",
    "percentCompleted": 100,
    "people": [
        {
            "externalID": "external-id",
            "firstName": "David",
            "lastName": "Chevalier",
            "companyName": "Surfe",
            "companyDomain": "surfe.com",
            "linkedInUrl": "https://linkedin.com/in/david-maurice-chevalier",
            "emails": [
                {
                    "email": "david.chevalier@surfe.com",
                    "validationStatus": "VALID"
                }
            ],
            "mobilePhones": [
                {
                    "mobilePhone": "+0475551243124",
                    "confidenceScore": 0.95
                }
            ],
            "status": "COMPLETED"
        }
    ]
}

It’s recommended to poll the status every few seconds until the status changes from IN_PROGRESS to COMPLETED.

2. Webhook Notifications (recommended)

Summary

• Initiate: Send a search request with your criteria.

• Wait: Receive an enrichmentID and poll for status.

• Retrieve: Once completed, fetch your results.

If you have any questions or need further assistance, feel free to reach out to our support team via Intercom.

Additional Resources