Enrich a CRM List

The standard pipeline for enriching thousands of CRM contacts without wasting credits or losing track of which result belongs to which row.

The pipeline#

Step paths below are relative — every request also needs the version and environment prefix, https://api.aggknowledgeai.com/v2/{environment}. So POST /person/enrich is called at https://api.aggknowledgeai.com/v2/test/person/enrich. See Environments.
1
Normalize inputsPOST /normalization/linkedin-url
Run LinkedIn URLs through the normalization utility first. Garbage in = paid-for garbage out.
2
Bulk validatePOST /person/validate/bulk
Tier 4, up to 250 per request. Drops rows that can never enrich — missing identifiers, malformed URLs — before they cost anything.
3
Submit the batchPOST /person/enrich/bulk
Asynchronous. Include your CRM row ID in metadata on every item — it’s echoed back verbatim, giving you a join key that survives the async round-trip.
4
Poll batch statusGET /person/enrich/bulk/{batchId}
Until the batch completes. Poll on an interval and back off if you hit a 429; batches are processed in the background.
5
Fetch & reconcileGET /person/enrich/bulk/{batchId}/items
Pull the enriched persons, then join back to your CRM on metadata.crmId.

Submitting the batch#

cURL — Bulk enrich
curl --request POST \
  --url https://api.aggknowledgeai.com/v2/live/person/enrich/bulk \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: YOUR_API_KEY' \
  --data '{
    "items": [
      { "professionalSocialMediaUrl": "linkedin.com/in/danielentrup", "metadata": { "crmId": "0031N00001xyz" } },
      { "professionalSocialMediaUrl": "linkedin.com/in/janedoe",      "metadata": { "crmId": "0031N00001abc" } }
    ]
  }'
cURL — Poll batch status
curl --request GET \
  --url https://api.aggknowledgeai.com/v2/live/person/enrich/bulk/BATCH_ID \
  --header 'x-api-key: YOUR_API_KEY'
Tip: Persist the returned personId on your CRM record. Future refreshes by personId are faster, cheaper to reconcile, and immune to professional social media URL changes.

Expect partial success#

Some items in every real-world batch will fail to enrich — that’s normal. A batch completing does not mean every item succeeded; check each item’s isSuccess. Triage rules live in Handle Failed Enrichments.