Upsert by external_id - Instant Compliance API

The externalId field is the link between your record identifier and our customer record. Use it deliberately and create-or-update from your CRM becomes a single API call.

The rule

When a CRM event fires (created or updated), call POST /v1/customers with the same externalId every time.
We will create on first call, update on every subsequent call.
No bookkeeping needed on your side.

Why not just call PATCH?

PATCH requires our customer id (UUID) or your externalId in the path. If your CRM event fires before we know we have a record (race), or if you’re rebuilding state, you’d have to handle “not found → create”. POST with externalId handles both cases in one call.

Picking a good `externalId`

Stable. Use the immutable id from your CRM, not the email (emails change).
Scoped to your organisation. Two of your records cannot share an externalId. Reusing an id is the upsert signal — make sure you mean it.
Reasonable length. Up to 255 characters; usual CRM ids fit comfortably.

Good examples:

hubspot:123456789
salesforce:0035g000001a2BcQAA
internal:customer/7741

Bad examples:

jane@example.com    # changes when she changes email
1                   # collides easily across data sources

Worked example

CRM webhook fires with the contact:

{
  "contactId": "hubspot:123456789",
  "name": "Jane Doe",
  "email": "jane@example.com",
  "phone": "+61400000000"
}

Send it to Instant Compliance:

curl -X POST https://app.instantcompliance.ai/api/v1/customers \
  -H "Authorization: Bearer ic_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: hubspot-contact-123456789-2026-06-23T01:00:00Z" \
  -d '{
    "externalId": "hubspot:123456789",
    "fullName": "Jane Doe",
    "email": "jane@example.com",
    "phone": "+61400000000"
  }'

First call: returns 201 Created with our UUID.
Jane updates her phone in HubSpot → webhook re-fires → same call → returns 200 OK with the same UUID.

Email conflicts

Email alone is not treated as unique — family members often share one address. A record only matches an existing customer when both email and fullName (case-insensitive) match. If that matched customer has a different externalId, we reject with 409 conflict:

{
  "error": {
    "code": "conflict",
    "message": "A different customer record already uses this name and email address.",
    "details": {
      "conflicting_external_id": "salesforce:0035g000001a2BcQAA",
      "conflicting_id": "550e8400-e29b-41d4-a716-446655440000"
    }
  }
}

This usually means two of your data sources have separate ids for the same person. Resolve in your CRM (merge the contacts), then retry.

​The rule

​Why not just call PATCH?

​Picking a good externalId

​Worked example

​Email conflicts

The rule

Why not just call PATCH?

Picking a good `externalId`

Worked example

Email conflicts