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.
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_byand 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
Related articles
-
How to import contacts from a CSV file
Upload your contact list in minutes by mapping your CSV columns to CRM fields.
-
Managing contacts and the CRM
In Omnifox every conversation creates a contact. Learn to use custom fields, tags, the deal pipeline and the contact 360 timeline.
-
CRM complete guide
The CRM in depth, in 46 chapters: pipeline, deals, the deal record, to-dos, dashboard and goal, settings, the contact record, contacts, import, lead forms, chat, AI and workflows.
-
Contact custom fields
Build fields tailored to your business to store exactly the information you need about each contact.
-
The sales pipeline and deals
Visualize and manage your sales process with a stage board and opportunity cards.