Authenticate using a Bearer token (access token from an Intercom app); include Authorization: Bearer {token} and Intercom-Version: {latest stable version} on all requests.
To create a contact, POST to https://api.intercom.io/contacts with a JSON body containing 'role' ('user' or 'lead'), 'email', and optionally 'name', 'phone', 'external_id', and 'custom_attributes' as a key-value object.
To update an existing contact by ID, PUT to /contacts/{contact_id} with only the fields you want to change — partial updates are supported.
To upsert by external_id, search first: POST /contacts/search with a filter on 'external_id' equals your value; if found, update; if not, create.
Custom attributes must be predefined in the Intercom workspace settings before they can be set via API — passing an undefined attribute key returns a 422.
To add a tag, POST to /contacts/{contact_id}/tags with 'id' being the tag ID (not name); retrieve tag IDs via GET /tags.
Known gotchas
The Intercom API version is specified in the Intercom-Version header and determines response schema — pin to a specific version to avoid breaking changes from version drift.
Creating a duplicate contact (same email) will create a new separate contact, not merge — always search before creating if deduplication is important.
Custom attribute keys are case-sensitive and must match the exact name configured in Intercom workspace settings; a mismatch returns 422 with a message about an invalid attribute.
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp