Use Case: Using externalID to Track Enrichments in Your System – SURFE

When you're enriching large batches of people or companies, keeping track of which results belong to which records in your system can get complicated fast. The externalID field solves this problem elegantly. Here's how to use it effectively.

What is externalID?

externalID is a field you include in every enrichment request that contains your own internal identifier for a person or company — for example, your CRM contact ID, database record ID, or any unique reference you use in your system.

Surfe stores this value and returns it alongside the enrichment results, so you can always match enriched data back to the correct record in your system without any complex lookup logic.

Why Use It?

Without externalID, matching enrichment results back to your records requires you to match on name, email or company — which can be unreliable, especially with common names or when enriching large batches.

With externalID, the match is always exact and instant — Surfe hands you back your own ID alongside the enriched data.

How It Works

Step 1: Include externalID in Your Enrichment Request

When starting an enrichment, include your internal identifier as the externalID for each person or company:

People enrichment example:

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

Company enrichment example:

{
  "companies": [
    {
      "domain": "surfe.com",
      "externalID": "crm-account-id-001"
    },
    {
      "domain": "example.com",
      "externalID": "crm-account-id-002"
    }
  ],
  "notificationOptions": {
    "webhookUrl": "https://your-server.com/webhook"
  }
}

Step 2: Receive Results with externalID Included

When the enrichment completes, Surfe returns the externalID alongside the enriched data in the webhook payload:

People enrichment result:

{
  "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",
      "emails": [
        {
          "email": "david.chevalier@surfe.com",
          "emailType": "professional",
          "validationStatus": "VALID"
        }
      ],
      "status": "COMPLETED"
    }
  }
}

Company enrichment result:

{
  "eventType": "company.enrichment.completed",
  "data": {
    "enrichmentID": "01973b15-68d2-7937-b87c-78dd0069b2db",
    "company": {
      "externalID": "crm-account-id-001",
      "name": "Surfe",
      "industry": "IT Services",
      "employeeCount": 65,
      "revenue": "10-50M",
      "status": "COMPLETED"
    }
  }
}

Step 3: Use externalID to Update Your Records

Your development team can use the externalID in the webhook payload to immediately identify which record to update in your system — no searching, no matching on name or email, just a direct lookup using your own ID.

Things to Keep in Mind

externalID accepts a string value — use your own internal identifier such as a CRM contact ID or database record ID to uniquely identify each record
It is not required but strongly recommended for any integration handling more than a handful of records
It is returned exactly as you sent it — make sure it's unique per record to avoid confusion
It works the same way for both people and company enrichments

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