Contacts vs Leads

Understand the difference between the usage of contact vs lead APIs and the issues that you might encounter when using the both APIs together.

If you use the Lead APIs only

• CRM IDs are unique at creation, so a CRM ID lookup normally returns exactly one record. The recency rule only becomes visible if a duplicate exists.

• Most Lead API endpoints accept either a record ID or a CRM ID in the same path position, so you rarely have to translate first.

• Every lead you create also gets a contact for the same record, visible in your contact list and exports.

If you are already using the Contact APIs or planning to use both the APIs together, read the section below first — that's where the behavioral issues might start showing up.

If you use both Contact and Lead APIs together

Running both side by side is supported indefinitely, whether as a gradual migration or because different teams adopted at different times.

• A lead created in your org will appear in your contact list, exports and everywhere else a contact does.

• If you use the Contact API to update the information of the lead, the operation will be successful.

Problems you may encounter

1. A CRM ID you created can be shadowed silently

Creating a lead through the Lead APIs is rejected with 409 if that CRM ID is already held by any lead or any contact, on any phone number. But that check runs only at that moment. If one of your systems later creates or edits a contact with the same CRM ID, it succeeds — nothing blocks it. From then on, a CRM ID lookup returns whichever record was created most recently. The record you created earlier becomes unreachable by CRM ID. It is not deleted, and its own record ID still reaches it, but no CRM-ID-based lookup, automation, or campaign will ever select it again.

You can solve this issue by not using the same CRM ID for different phone numbers

2. "Most recent" means created, not active

When using CRM ID based identifiers with Lead APIs, the system resolves it by picking up the most recently created lead or contact. A record created last week and never touched since beats one that has been in active conversation for a year.

3. Two records on one phone number means only one can converse

The Contact APIs allow two records with different CRM IDs to share a phone number. Only one of them may hold a live conversation. If another record on that number already holds one, assigning, messaging, or opening a conversation for your target fails with 409 — naming a CRM ID that isn't the one you targeted.

To solve this enable, "On lead creation, activate the latest lead" for your organization — creating a record on a taken number will then deactivate the older conversation so the newest record is the live one. Without it, a newly created record on a taken number can never send.

4. Writes to an unreachable record still succeed

Expiry blocks conversations, not bookkeeping. Attribute writes and event recording return success on an expired record; only the send, assignment, or conversation-opening fails — and when an automation is what fails, its execution is marked failed and not retried.

The two habits that avoid most of this

• One CRM ID namespace. Never let a legacy sync and a newer integration assign the same CRM ID to different real people. We enforce uniqueness only at lead creation and cannot catch a collision introduced afterwards.

• Store the record ID. A CRM ID is a best current match; a record ID is a permanent handle. Anywhere reliably addressing the same record matters more than convenience, use the record ID.

If you use the Contact APIs only

Contact API is deprecated and if you are starting a new integration, you should use the Lead APIs

Nothing in your integration changes. Same request, responses and same rules.

• The same CRM ID on two different phone numbers is still two separate records.

• The same CRM ID on the same phone number twice is still rejected.

• You can still edit a CRM ID on an existing record at any time, with no uniqueness check.

If you later start using the Lead APIs, read the section above first — that's where the behavioral issues might start showing up.