external_id: the contact's external ID for integrations

Use external_id to link a contact to its record in your ERP, e-commerce or other system and avoid duplicates when syncing.

Jun 26, 2026

What external_id is

The external_id field stores the identifier a contact already has in another system of yours (your ERP, your e-commerce, a different CRM, an in-house database). It's free text up to 255 characters that travels with the contact record in Omnifox and lets you link that contact back to its original record in your platform.

Messaging and Meta don't use it; it exists purely for integrations you build with the Omnifox REST API. It's indexed, so searching or deduplicating by external_id is fast.

When to use it

  • You sync contacts between Omnifox and an external system and need to know which is which without relying on phone or email (which can change).
  • You want your integration to be idempotent: re-sending the same contact shouldn't create duplicates.

How to store it via API

external_id is accepted when creating or updating a contact, and as a key in upsert.

1. Create with external_id:

POST /api/v1/contacts
{
  "first_name": "Alex",
  "phone": "+593990000000",
  "external_id": "erp-00482"
}

2. Upsert (create or update by a unique key):

POST /api/v1/contacts/upsert
{
  "unique_by": ["external_id"],
  "external_id": "erp-00482",
  "first_name": "Alex",
  "email": "[email protected]"
}

With unique_by: ["external_id"], Omnifox looks in the current workspace for a contact with that external_id. Exactly one match: it updates it; no match: it creates it. You can combine keys (["phone","external_id"]), but if different keys point to different contacts the API returns 409 (ambiguous) so you never merge by accident.

Verify it

  • After the upsert, call it again with the same data: the response should return the same contact id and not create a new one.
  • In Contacts, open the record and confirm the data was updated rather than duplicated.

If it doesn't work

  • Duplicates are created: make sure you send unique_by and that the external_id is identical (no stray spaces or different casing). The value is compared as-is.
  • I get a 409 ambiguous: two workspace contacts already hold clashing keys (e.g. one has that phone, another has that external_id). Resolve it by merging or cleaning up before retrying.
  • external_id is null across workspaces: remember each workspace has its own database; external_id is only unique inside the workspace where you stored it.

Tips

  • Prefix the value (erp-, shop-) so you can tell at a glance which system it came from.
  • Keep the external_id stable: if it changes in your source system, you lose the link and may duplicate.

Related articles

Was this helpful?

Related articles

Message us on WhatsApp