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.
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.
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.
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.
Need more help? Get support from our Community Forum
Find answers and get help from Intercom Support and Community Experts