Understanding and managing user IDs

To manage your customers effectively, Intercom uses two types of IDs: the Intercom ID and the user_id. Understanding how they work together is essential for maintaining data integrity and ensuring accurate customer identification.

The Intercom ID

The Intercom ID is an identifier that's automatically generated by our system for every customer record. This ID is constant and cannot be changed. In our API, this is often referred to as the contact_id.

The custom user_id (external ID)

The user_id is a customizable identifier that you can set to match the primary key or unique ID from your own database. It offers a flexible way to integrate Intercom with your external systems and can be updated via the API.

Best practices for managing user IDs

Following these best practices will help you avoid common data issues like duplicate records or merged conversations.

Assign a unique and consistent identifier

You should always assign a unique user_id for each customer, typically the primary key from your own database records. It's crucial to use this same user_id for all future interactions and profile updates for that specific customer.

Avoid passing different user_ids for the same email address, as this will create duplicate customer records.

Important:

Using inconsistent or overlapping user_ids can cause serious data integrity issues, such as cross-account logins and merged conversations between different customers.
The value -1 is reserved by Intercom's system for internal purposes and should not be used as a user_id. Using this value can cause unexpected behavior, such as conversations being incorrectly associated with the wrong user profile. If you use -1 as a user_id, it is often used as a default or placeholder value. This means if a user has it, it is no longer unique and can causes issues.

Use globally unique user IDs in multi-tenant setups

User_id values sent to Intercom must be globally unique across your entire workspace. In multi-tenant setups — where multiple tenants or organizations share the same Intercom workspace — user IDs that are only unique within a single tenant can collide across tenants, causing separate customers to be merged into the same Intercom contact record.

To prevent this, prefix user_id values with a tenant identifier before sending them to Intercom. For example, instead of sending "user_123", send "tenant_abc:user_123".

Note: Enabling JWT authentication is also required to prevent user record collisions and ensure secure identification. Without it, a bad actor can impersonate another user by supplying their user_id, which can result in unauthorized access to conversation history and workspace data. Globally unique user_id values prevent accidental record merges, while JWT authentication prevents deliberate impersonation.

Avoid using default or placeholder values

Never assign default values like "undefined" or use the same user_id across multiple customers. This will lead to data errors and prevent you from correctly identifying individual customers.

Backfilling or updating user IDs

If you need to update a customer record that previously had an unknown user_id, you can add the correct identifier later.

Pro tip: You can consult your own database to find the correct user_id and then update the customer record in Intercom using a CSV import or our API.

Step-by-step: updating a user_id via the Intercom ID

Use the Search for a Contact endpoint to find the contact by email or another known attribute.
Note the id field in the response — this is the contact's permanent Intercom ID.
Look up the correct user_id from your own database.
Call the Update a Contact endpoint, passing the Intercom ID (id) and the correct user_id.

{
  "id": "contact_intercom_id",
  "user_id": "your_stable_database_id"
}

Important: Always use the Intercom ID (id) — not email or an existing user_id — when targeting a contact for an update. This ensures you update the correct record, even when the contact has no user_id set or has an incorrect one.

Preventing integrations from setting incorrect user IDs

Integrations like CRM syncs, analytics tools, and data pipelines can inadvertently set incorrect user_ids. Common causes include:

Mapping a session ID, cookie, or temporary token instead of a stable database primary key
Sending null, undefined, 0, or -1 as placeholder values when a customer isn't authenticated
Using an email address in the user_id field (emails can change, breaking contact continuity)
Different integrations sending different user_ids for the same customer

To prevent this:

Audit your integration mappings — confirm which field in your system maps to user_id in Intercom. It should be your database's primary key for each customer.
Validate before sending — ensure user_id is non-null, non-empty, and not a reserved value (such as -1 or undefined) before it's passed to Intercom.
Use a single source of truth — if multiple integrations send data to Intercom, ensure they all use the same stable customer identifier.
Test with known records — after configuring an integration, use the Search for a Contact endpoint to verify a few customers' user_ids match your database.

Managing user IDs with the API

You can use Intercom’s API to perform several key actions for managing your customer IDs. For complete details, see our Developer Hub.

Retrieving, updating, or searching for a contact

Retrieve a contact: Look up a customer’s details using their Intercom ID (id) or your custom user_id with the Retrieve a Contact endpoint.
Update a contact: Set or correct a user_id using the Update a Contact endpoint.
Search for a contact: Validate identifiers like user_id or email using the Search for a Contact endpoint.

Auditing your integrations

Regular audits help you catch incorrect user_ids before they cause data integrity issues. Follow these steps to audit your integrations and ensure all contacts have the correct, stable user_id.

Identify contacts with missing or suspicious user_ids — use the Search for a Contact endpoint to query contacts where user_id is blank or contains a known placeholder value (such as -1 or undefined). You can also export your contacts list from Intercom and filter for anomalies.
Trace the source of each user_id — for each flagged contact, identify which integration last set the user_id. Check your integration logs or event history to confirm where the value originated.
Correct the user_id using the Intercom ID — look up the correct user_id from your own database, then use the Update a Contact endpoint with the contact's Intercom ID to set the right value. See Backfilling or updating user IDs for the step-by-step process.
Fix the integration configuration — update the integration to map to the correct, stable identifier going forward. For third-party tools, check the field mapping settings and update them to point to your database's primary key.
Validate after correction — re-search for updated contacts to confirm user_id now reflects the correct value, and monitor for new occurrences over the following days.

Ensuring correct identification with JWT authentication

To ensure robust authentication for logged-in customers, it's best practice to use your database’s primary key as the user_id in the JSON Web Token (JWT) payload.

If you only have an email address to identify a customer, you should populate both the user_id and email attributes in the JWT payload with the customer's email address.

Troubleshooting common user ID errors

Archiving a custom user_id

If you archive a custom user_id attribute, the default Intercom user_id field will not be automatically updated with that data. A manual backfill will be required to update the records.

Handling duplicate records

If you find duplicate records caused by mismatched user_id and email associations, you’ll need to clean up the records manually or by using the API to merge or delete them.

Switching from a custom to the default ID

If you need to update your user database field, consult with your developer on how to use the Intercom API or use the CSV import workflow.

💡Tip

Need more help? Get support from our Community Forum
Find answers and get help from Intercom Support and Community Experts