Use Case: Enriching a CRM Export in Bulk – SURFE

You have a list of contacts in your CRM — names, companies, and job titles — but the data is incomplete. Emails are missing, phone numbers are outdated, and your team is wasting time chasing down information manually. Here's how to use the Surfe API to enrich your entire contact list in bulk.

What You'll Use

Enrich People — to enrich your list of contacts with verified emails and mobile numbers
Webhooks — to receive enrichment results automatically as they complete
Get Credits — to check you have enough credits before starting

Step 1: Check Your Credit Balance

Before running a large enrichment job, check you have enough credits available.

Endpoint: GET /v1/credits

Headers:

{
  "Authorization": "Bearer YOUR_API_KEY"
}

Example Response:

{
  "totalEmail": 5000,
  "totalMobile": 3000,
  "totalSearch": 500
}

If you don't have enough credits, purchase more at surfe.com/buy-credits before proceeding.

→ See: API - Get Credits

Step 2: Prepare Your Contact List

Export your contacts from your CRM and prepare them for the API. For each person you want to enrich, gather as much of the following as possible:

First name and last name
Company domain
Company name
LinkedIn URL

The more information you provide, the higher your find rate will be. Always include your own internal CRM ID as the externalID so you can match results back to your records.

Step 3: Start the Enrichment

Send your contacts to the Enrich People endpoint. You can include up to 10,000 people per request — if your list is larger, split it into batches.

Endpoint: POST /v2/people/enrich

Headers:

{
  "Authorization": "Bearer YOUR_API_KEY",
  "Content-Type": "application/json"
}

The more information you provide, the higher your find rate will be. If you have a LinkedIn URL for a contact, always include it — it significantly improves results.

Request Body:

{
  "enrichmentOptions": {
    "acceptedEmailType": "professional",
    "skipMobileEnrichmentIfNoEmailFound": false
  },
  "include": {
    "email": true,
    "jobHistory": false,
    "linkedInUrl": false,
    "mobile": true
  },
  "notificationOptions": {
    "webhookUrl": "https://your-server.com/webhook"
  },
  "people": [
    {
      "firstName": "David",
      "lastName": "Chevalier",
      "companyDomain": "surfe.com",
      "companyName": "Surfe",
      "linkedinUrl": "https://www.linkedin.com/in/david-maurice-chevalier",
      "externalID": "crm-contact-id-001"
    },
    {
      "firstName": "Jane",
      "lastName": "Smith",
      "companyDomain": "example.com",
      "companyName": "Example Co",
      "externalID": "crm-contact-id-002"
    }
  ]
}

You'll receive an enrichmentID in the response confirming the enrichment has started.

→ See: API - Enrich People - Understanding Surfe's Asynchronous Split Request

Step 4: Receive Results via Webhook

As each person's enrichment completes, Surfe sends a person.enrichment.completed event to your webhook URL with the full enriched profile.

Example webhook payload:

{
  "eventType": "person.enrichment.completed",
  "data": {
    "enrichmentID": "01973f39-f391-7b75-8812-7aad73f798f6",
    "person": {
      "externalID": "crm-contact-id-001",
      "firstName": "David",
      "lastName": "Chevalier",
      "companyName": "Surfe",
      "companyDomain": "surfe.com",
      "jobTitle": "Co-Founder & CEO",
      "emails": [
        {
          "email": "david.chevalier@surfe.com",
          "emailType": "professional",
          "validationStatus": "VALID"
        }
      ],
      "mobilePhones": [
        {
          "mobilePhone": "+33 6 12 34 56 78",
          "confidenceScore": 0.8
        }
      ],
      "status": "COMPLETED"
    }
  }
}

Use the externalID in the payload to match the enriched data back to the correct contact in your CRM.

→ See: API - Webhooks

Step 5: Update Your CRM

Once your development team receives the enriched data via webhook, they can use it to:

Update existing contact records in your CRM via their API
Flag contacts where data was not found for manual review
Trigger automated follow-up sequences using the verified contact details
Build custom logic to handle NOT_FOUND results separately from COMPLETED results

Things to Keep in Mind

People enrichment counts towards your 2,000 profiles per day quota — plan large batches across multiple days if needed
Credits are only consumed when data is successfully found
Always use externalID to match results back to your CRM records

→ See: API - Credits & Quotas

Need Help?

If you have any questions or need further assistance, feel free to reach out to our support team or email api.support@surfe.com.

Additional Resources