Enrich People by Email

This endpoint allows you to look up a person using their email address and retrieve their professional profile data. Including their name, job title, company, location, and LinkedIn URL.

What this endpoint does:

This endpoint lets you submit one or more email addresses to Surfe and receive back enriched professional profile information for each person.

When available, returned data can include:

firstName and lastName
company and companyDomain
jobTitle
country
linkedInUrl
jobHistory

Common use cases include:

Inbound lead enrichment: Turn a raw email address into a fully qualified contact.
CRM and database cleaning: Fill in missing attributes across large contact databases and reduce duplicates.
Personalised outbound: Reverse-lookup email lists to find LinkedIn profiles and seniority data for more targeted outreach.
Customer identification: Surface a contact's role and company instantly when an inbound email arrives.
Product-led growth tracking: Enrich sign-up emails to identify high-value accounts early and trigger a sales handoff.

Endpoint overview

HTTP Method

POST

Endpoint URL

https://api.surfe.com/v2/people/find-by-email

Authentication

Authorization: Bearer YOUR_API_KEY

All Surfe API requests must include your API key in the request header. To generate your API key please find the article here.

Before you start

Before using this endpoint, make sure you have the following in place.

1. A Surfe account

You must have an active Surfe account to use the API.

2. API access

Generate your API key from Settings → API Settings inside your Surfe account.

3. Sufficient credits

Finding a LinkedIn URL costs 15 Search credits per result. Make sure your account has enough credits before running enrichments. See Credits & Quotas for full details.

4. A tool to send requests

Here are a few options as examples you can use to send API requests:

Postman
Zapier
Make
n8n
A custom backend integration

How this endpoint works

This enrichment runs asynchronously, meaning you submit your request and receive an ID immediately, rather than waiting for results in the same response.

There are two steps:

Start the enrichment — send your POST request and receive an enrichmentID
Retrieve the results — either use a webhook (recommended) to receive results automatically when completed, or poll a second GET endpoint using the enrichmentID

Recommended: Use a webhookUrl in your initial request. This avoids the need to poll and is more efficient.

Step 1: Start the enrichment

Request structure

Send a POST request with a JSON body containing the email address(es) you want to enrich.

Required headers

Authorization: Bearer YOUR_API_KEY 
Content-Type: application/json

Header	Description
Authorization	Your Surfe API key
Content-Type	Must be set to `application/json`

Request body example:

{
  "notificationOptions": {
    "webhookUrl": "https://your-webhook-url.com/endpoint"
  },
  "people": [
    {
      "email": "david.chevalier@surfe.com",
      "externalID": "external-id"
    }
  ]
}

Request field definitions

Field	Required	Type	Description
`people`	Yes	Array	List of people to enrich. Each entry requires an email address.
`people[].email`	Yes	String	The email address to search for
`people[].externalID`	No	String	Your own internal ID for this person — useful for matching results back to your system
`notificationOptions.webhookUrl`	No	String	A URL where Surfe will send the enrichment result once it completes. Strongly recommended.

cURL example

curl -X POST "https://api.surfe.com/v2/people/find-by-email" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "notificationOptions": {
      "webhookUrl": ""
    },
    "people": [
      {
        "email": "david.chevalier@surfe.com",
        "externalID": "external-id"
      }
    ]
  }'

Example response

{
"enrichmentID": "ed851fb5-20e4-4483-b794-c63931056787",
"enrichmentCallbackURL": "https://api.surfe.com/v2/people/enrich/ed851fb5-20e4-4483-b794-c63931056787"
}

This response confirms your enrichment has been queued. Save the `enrichmentID` — you'll need it to retrieve results if you're not using webhooks.

Step 2: Retrieve the results

Option A: Webhooks (recommended)
If you included a `webhookUrl` in your request, Surfe will automatically send the enrichment results to that URL once processing is complete. No further action is needed on your end. See the webhooks documentation here.

Option B: Poll for results
If you're not using webhooks, you can retrieve results manually using the Enrich People (get) endpoint.

HTTP Method

GET

Endpoint URL

https://api.surfe.com/v2/people/enrich/<your-enrichment-id>

Authentication

Authorization: Bearer YOUR_API_KEY

Replace <your-enrichment-id> with the enrichmentID from Step 1.

cURL Example:

curl -X GET "https://api.surfe.com/v2/people/enrich/ed851fb5-20e4-4483-b794-c63931056787" \
  -H "Authorization: Bearer YOUR_API_KEY"

Note: Polling is less efficient than webhooks and may introduce delays. If polling, check approximately once per second until the status changes from IN_PROGRESS to COMPLETED.

Example response

{
    "enrichmentID": "ed851fb5-20e4-4483-b794-c63931056787",
    "percentCompleted": 100,
    "people": [
        {
            "companyDomain": "surfe.com",
            "companyName": "Surfe",
            "country": "DE",
            "firstName": "David",
            "jobHistory": [
                {
                    "companyName": "Surfe",
                    "jobTitle": "Co-Founder & CEO",
                    "linkedInURL": "https://linkedin.com/company/surfe",
                    "startDate": "2020-03-01T00:00:00Z"
                },
            ],
            "jobTitle": "Co-Founder & CEO",
            "lastName": "Chevalier",
            "linkedInUrl": "https://linkedin.com/in/david-maurice-chevalier-84607875",
            "status": "COMPLETED"
        }
    ],
    "status": "COMPLETED"
}

Response fields explained

Field	Description
`enrichmentID`	The ID for this enrichment job
`status`	Overall enrichment status (`IN_PROGRESS`, `COMPLETED`)
`percentCompleted`	How much of the enrichment has been processed (0–100)
`people[].firstName`	First name of the person
`people[].lastName`	Last name of the person
`people[].companyName`	Current company name
`people[].companyDomain`	Company website domain
`people[].jobTitle`	Current job title
`people[].country`	Country code (e.g. `FR`, `DE`, `US`)
`people[].linkedInUrl`	LinkedIn profile URL
`people[].jobHistory`	Array of previous and current roles
`people[].status`	Per-person enrichment status

Best practices

Use webhooks instead of polling wherever possible. It's faster and reduces unnecessary load.
Include an externalID with each person so you can easily match results back to your own records.
Validate email formats before submitting to avoid wasted requests.
Handle errors gracefully, build logic in your integration to deal with errors.
Log API responses for debugging and auditing purposes.
Respect rate limits, add delays or queuing if you're sending large volumes.

Additional Resources