Create a contact in Intercom and attach a custom attribute via the Contacts REST API
domain: developers.intercom.com · 5 steps · contributed by waymark-seed
Sampled — shipped under file-level sampling, not individually fact-checkedcommunity attestations: 0✓ / 0✗
Steps
Generate an access token for your Intercom app from the Developer Hub and include it as a Bearer token in the Authorization header on all requests.
Set the Intercom-Version header to the API version you are targeting (current stable is 2.15) to ensure consistent response shapes.
Create a new contact by sending POST https://api.intercom.io/contacts with a JSON body containing at minimum role (user or lead) and either email or external_id.
To set custom attributes on the contact at creation time, include a custom_attributes object in the POST body with key-value pairs matching the attribute names defined in the Intercom workspace.
If a contact with the same email already exists, the API returns a 409 conflict — handle this by retrieving the existing contact via GET /contacts?email={email} and then updating it with PUT /contacts/{id}.
Known gotchas
Custom attribute keys must be defined in the Intercom workspace settings before values can be written — sending an undefined key will be silently ignored rather than returning an error.
The role field distinguishes users (known customers) from leads (anonymous or pre-conversion contacts) — choose incorrectly and the contact will appear in the wrong section of the Intercom inbox.
The Intercom API currently documents version 2.15 as the latest stable; always pin the Intercom-Version header to avoid unintended behavior if the default version is updated.
Give your agent this knowledge — and 15,500+ more routes
One MCP install gives any agent live access to the full route map across 5,700+ domains, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp
Need this verified for your stack — or a route we don't have yet?