Intercom integration

Intercom is a customer messaging platform combining live chat, help desk tickets and a customer data platform. This integration lets your WeWeb backend manage companies, leads and users, send messages, run conversations and tickets, track events and react to workspace webhooks.

Use cases

• Sync your app's users and companies into Intercom (create, update, tag, merge)
• Create and manage support conversations and tickets from backend workflows
• Send admin-initiated in-app or email messages to contacts
• Track behavioral events for segmentation and campaigns
• React to workspace events (new conversations, replies, ticket changes) with webhook triggers

Setup

1. Open the Intercom Developer Hub and create (or open) an internal app for your workspace.
2. In the app's Authentication section, copy the Access Token.
3. In WeWeb, open the Data & API tab, then the Integrations subtab. Select Intercom, then click Add Connection.
4. Paste the Access Token and pick the Region — the data-hosting region of your Intercom workspace (US, EU, or Australia). The connection applies to all environments (Editor, Staging, Production); to use different values per environment, override the generated environment variables.
5. Test with a simple action such as List Users to verify authentication.

Enabling triggers (webhook)

The triggers (see below) require a webhook that you register manually — Intercom cannot register webhooks via API:

1. On the connection, set Enable Webhook Triggers to on and keep (or adjust) the Webhook Path (default /intercom/webhook).
2. Set the Client Secret — found in your app's Basic information in the Developer Hub. It verifies the signature of incoming webhooks.
3. Copy the generated webhook URL, then in the Developer Hub open Webhooks, paste the URL, and tick the topics you need.

Using Intercom as a data source for tables

You can create WeWeb tables backed by three Intercom resources:

• Companies — page-numbered, sorted by last_request_at (ascending or descending).
• Leads and Users — contacts filtered by role, searchable with the same filters as the list actions (see below).

Lead and user views use cursor pagination (up to 150 results per page, default 50).

Searching with filters

The List Leads, List Users, Search Conversations and Search Tickets actions share the same search interface built on Intercom's search DSL:

• Search Mode Filters — add structured rows of field + operator + value, combined with AND.
• Search Mode Advanced — provide a raw Intercom search query object for nested AND/OR groups (max 2 nesting levels, 15 filters per group).

Available operators: =, !=, IN, NIN, >, <, ~ (contains), !~ (does not contain), ^ (starts with), $ (ends with).

Searchable fields per resource:

Resource	Fields
Leads	id, name, email, phone, external_id, created_at, signed_up_at, updated_at, owner_id, unsubscribed_from_emails
Users	Same as leads, plus last_seen_at, email_domain
Conversations	state, open, read, created_at, updated_at, source.author.id, admin_assignee_id, team_assignee_id, tag_ids
Tickets	open, state, ticket_type_id, admin_assignee_id, created_at, updated_at

SEARCH INDEXING DELAY

Intercom timestamps are indexed at day precision, and newly created records can take 10–12 minutes to appear in search results. Never create a record and search for it in the same workflow — retrieve it by ID instead.

Common pitfalls (setup & usage)

Wrong region

The connection's Region must match your workspace's data-hosting region (US, EU, or Australia). A mismatch causes authentication failures even with a valid token.

Creating a user that already exists

Create User is not an upsert: creating a contact whose email already exists returns a 409 error. (Create or Update Company, by contrast, is an upsert keyed on your Company ID.)

New contacts take a few minutes to be usable

Brand-new contacts can briefly return 404 when messaged and take ~10–12 minutes to appear in search results. Use the contact ID returned at creation instead of searching for it.

Two kinds of company IDs

Create or Update Company uses your own Company ID (immutable after creation). Every other company action uses the Intercom-provisioned id returned by the API. Also note a company only becomes visible in Intercom once at least one user is attached to it.

Message vs conversation direction

Send Message is admin-initiated outreach; Create Conversation starts a conversation as the contact. After Send Message, no conversation object exists until the contact replies — unless you enable Create Conversation Immediately (in-app messages), which returns a conversation_id right away.

Triggers

With the webhook enabled and registered in the Developer Hub, nine backend triggers become available. Each fires when Intercom sends the corresponding topic:

Trigger	Topic	Fires when
On user created	contact.user.created	A user contact is created
On lead created	contact.lead.created	A lead contact is created
On conversation started by contact	conversation.user.created	A contact starts a new conversation
On contact reply	conversation.user.replied	A contact replies to a conversation
On admin reply	conversation.admin.replied	An admin replies to a conversation
On conversation closed	conversation.admin.closed	An admin closes a conversation
On conversation rated	conversation.rating.added	A contact rates a conversation
On ticket created	ticket.created	A ticket is created
On ticket state changed	ticket.state.updated	A ticket moves to another state

The event payload contains the topic plus the affected object — for example, On conversation rated receives { topic, type: "conversation", id, conversation_rating: { rating, remark } }. Incoming webhooks are signature-verified with the connection's Client Secret before any workflow runs.

Remember to tick each topic you want in the Developer Hub's Webhooks section — WeWeb only receives the topics you subscribed to there.

All Actions

This integration provides actions across companies, contacts (leads and users), messaging, conversations, tickets, tags and events. Leads and users are both Intercom contacts, distinguished by their role — the matching actions take the same inputs.

Action	Description
List Companies	List companies, page-numbered and sorted by last_request_at
Retrieve Company	Fetch a company by its Intercom-provisioned ID
Create or Update Company	Create a company, or update it if your Company ID already exists (upsert)
Update Company	Update an existing company
Delete Company	Delete a company
List Leads / List Users	Search contacts by role with filters, cursor-paginated
Retrieve Lead / Retrieve User	Fetch a contact by ID (or external ID, users only)
Create Lead / Create User	Create a contact with role lead or user
Update Lead / Update User	Update an existing contact
Delete Lead / Delete User	Permanently delete a contact
Send Message	Send an admin-initiated in-app or email message to a contact
Create Conversation	Start a contact-initiated conversation
Search Conversations	Search conversations with filters, cursor-paginated
Retrieve Conversation	Fetch a conversation by ID
Reply to Conversation	Reply as an admin (comment or note) or as the contact
Manage Conversation	Close, snooze, open or assign a conversation
Create Ticket	Create a ticket of a given type for one contact
Update Ticket	Update a ticket's attributes, state, assignment or snooze
Search Tickets	Search tickets with filters, cursor-paginated
Reply to Ticket	Reply to a ticket as an admin or as the contact
Track Event	Record an event a user performed
Create Tag	Create a tag in the workspace
Tag Contact / Untag Contact	Add or remove a tag on a contact
Attach / Detach Company	Associate or dissociate a company with a contact
Add Note to Contact	Add an internal note to a contact
Merge Lead into User	Merge a lead contact into a user contact
Archive / Unarchive Contact	Soft-delete or restore a contact

Action details

List Companies

List the workspace companies, page-numbered and sorted by last_request_at. Only companies with at least one associated user are returned.

Inputs

Display Key	Example Input	Description	Restrictions
Page Optional	1	Page number (1-based).	Default 1
Results Per Page Optional	20	Number of results per page.	Default 15
Sort Order Optional	"desc"	Sort order by last_request_at.	Valid: desc, asc

Example output

{ "type": "list", "data": [ { "id": "63a07ddf05a32042dffac965", "name": "Acme" } ], "pages": { "page": 1, "per_page": 15, "total_pages": 1 }, "total_count": 1 }

Documentation of API endpoint that powers action: Intercom API – List all companies (POST /companies/list)

Retrieve Company

Fetch a company by its Intercom-provisioned ID (not your own Company ID).

Inputs

Display Key	Example Input	Description	Restrictions
Company ID	"63a07ddf05a32042dffac965"	The Intercom-provisioned company ID.	Required

Example output

{ "id": "63a07ddf05a32042dffac965", "company_id": "company_123", "name": "Acme Corporation", "plan": {}, "custom_attributes": {} }

Documentation of API endpoint that powers action: Intercom API – Retrieve a company (GET /companies/{id})

Create or Update Company

Create a company, or update it if a company with the given Company ID already exists (upsert). Companies only become visible in Intercom once at least one user is attached.

Inputs

Display Key	Example Input	Description	Restrictions
Company ID (yours)	"company_123"	Your unique identifier for the company. Cannot be changed after creation; reusing it updates the existing company.	Required
Company Name Optional	"Acme Corporation"	Name of the company.	String
Plan Optional	"Enterprise"	The plan or tier the company is on.	String
Company Size Optional	50	Number of employees.	Number
Website Optional	"https://acme.com"	Company website URL.	String
Industry Optional	"Technology"	Industry the company operates in.	String
Monthly Spend Optional	1000	Monthly spend amount.	Number
Created At (remote) Optional	1577836800	When the company was created in your system.	UNIX timestamp (seconds)
Custom Attributes Optional	{"tier":"gold"}	Custom data attributes defined on your workspace companies.	Object

Example output

{ "id": "63a07ddf05a32042dffac965", "company_id": "company_123", "name": "Acme Corporation" }

Documentation of API endpoint that powers action: Intercom API – Create or update a company (POST /companies)

Update Company

Update an existing company. Only provided fields change; Custom Attributes keys are merged.

Inputs: same as Create or Update Company minus the create-only Company ID (yours) (the upsert key — it cannot be changed) and Created At (remote), plus:

Display Key	Example Input	Description	Restrictions
Company ID	"63a07ddf05a32042dffac965"	The Intercom-provisioned ID of the company to update (not your own Company ID (yours)).	Required

Documentation of API endpoint that powers action: Intercom API – Update a company (PUT /companies/{id})

Delete Company

Delete a company by its Intercom-provisioned ID.

Inputs

Display Key	Example Input	Description	Restrictions
Company ID	"63a07ddf05a32042dffac965"	The Intercom-provisioned company ID.	Required

Example output

{ "id": "63a07ddf05a32042dffac965", "object": "company", "deleted": true }

Documentation of API endpoint that powers action: Intercom API – Delete a company (DELETE /companies/{id})

List Leads / List Users

Search leads or users with filters, cursor-paginated. The role filter (lead or user) is applied automatically and combined with your query. See Searching with filters.

Inputs

Display Key	Example Input	Description	Restrictions
Search Mode Optional	"Filters"	Structured filter rows or a raw query object.	Valid: Filters, Advanced
Filters Optional	[{"field":"email","operator":"~","value":"@acme.com"}]	Field + operator + value rows, combined with AND. Only shown in Filters mode.	See searchable fields above
Raw Query Optional	{"operator":"OR","value":[…]}	Full Intercom search query object for nested AND/OR groups. Only shown in Advanced mode.	Max 2 nesting levels, 15 filters per group
Results Per Page Optional	50	Number of results per page.	Max 150, default 50
Starting After Optional	"WzE2…"	Pagination cursor from the previous response (pages.next.starting_after). Leave empty for the first page.	String

Example output

{ "type": "list", "data": [ { "id": "63a07ddf05a32042dffac965", "role": "user", "email": "jane@example.com" } ], "pages": { "next": { "starting_after": "WzE2…" }, "per_page": 50 }, "total_count": 120 }

Documentation of API endpoint that powers action: Intercom API – Search contacts (POST /contacts/search)

Retrieve Lead / Retrieve User

Fetch a lead or user by Intercom contact ID. Retrieve User additionally offers an ID / External ID lookup toggle to fetch by your own external ID; Retrieve Lead looks up by contact ID only. A GET on a merged contact returns 404.

Inputs

Display Key	Example Input	Description	Restrictions
Contact ID	"63a07ddf05a32042dffac965"	Intercom contact ID. Required in ID lookup mode.	Required (ID mode)
External ID	"user_ext_456"	Your own identifier. Required in External ID lookup mode.	Users only

Example output

{ "id": "63a07ddf05a32042dffac965", "role": "user", "email": "jane@example.com", "name": "Jane Smith", "external_id": "user_ext_456", "custom_attributes": {} }

Documentation of API endpoint that powers action: Intercom API – Get a contact (GET /contacts/{id})

Create Lead / Create User

Create an Intercom contact with role lead or user. Not an upsert: creating a contact whose email already exists returns a 409 error. New contacts can take a few minutes to appear in search results.

Inputs

Display Key	Example Input	Description	Restrictions
Email Optional	"jane@example.com"	Email address of the contact.	Valid email
Phone Optional	"+1234567890"	Phone number.	E.164 format recommended
Name Optional	"Jane Smith"	Full name of the contact.	String
External ID Optional	"user_ext_456"	Unique identifier from your own system.	String
Avatar URL Optional	"https://example.com/avatar.jpg"	URL to an avatar image.	Valid URL
Signed Up At Optional	1577836800	When the contact signed up.	UNIX timestamp (seconds)
Last Seen At Optional	1609459200	When the contact was last active.	UNIX timestamp (seconds)
Owner ID Optional	123456	Admin ID who owns this contact.	Number
Unsubscribed From Emails Optional	false	Email subscription status.	Boolean
Custom Attributes Optional	{"plan":"premium"}	Custom data attributes defined on your workspace contacts.	Object

Example output

{ "id": "63a07ddf05a32042dffac965", "role": "user", "email": "jane@example.com", "name": "Jane Smith" }

Documentation of API endpoint that powers action: Intercom API – Create a contact (POST /contacts)

Update Lead / Update User

Update an existing lead or user. Only provided fields change; Custom Attributes keys are merged.

Inputs: same as Create Lead / Create User, plus:

Display Key	Example Input	Description	Restrictions
Contact ID	"63a07ddf05a32042dffac965"	Intercom contact ID of the contact to update.	Required

Documentation of API endpoint that powers action: Intercom API – Update a contact (PUT /contacts/{id})

Delete Lead / Delete User

Permanently delete a contact — irreversible; consider Archive Contact instead.

Inputs

Display Key	Example Input	Description	Restrictions
Contact ID	"63a07ddf05a32042dffac965"	Intercom contact ID.	Required

Example output

{ "id": "63a07ddf05a32042dffac965", "external_id": "user_ext_456", "type": "contact", "deleted": true }

Documentation of API endpoint that powers action: Intercom API – Delete a contact (DELETE /contacts/{id})

Send Message

Send an admin-initiated message to a contact — in-app chat or email. No conversation object exists until the contact replies, unless Create Conversation Immediately is enabled.

Inputs

Display Key	Example Input	Description	Restrictions
Channel	"inapp"	How to deliver the message.	Valid: inapp, email
Subject	"Welcome aboard!"	Email subject. Only shown (and required) when Channel is email.	Required for email
Message	"Thanks for signing up — need any help?"	The message content (HTML allowed for email).	Required
From (admin)	"Support Team"	Admin sending the message, picked from your workspace admins.	Required
Recipient Type	"user"	Whether the recipient contact is a user or a lead.	Valid: user, lead
To (contact)	"63a07ddf05a32042dffac965"	Intercom contact ID of the recipient.	Required
Email Template Optional	"plain"	Email template style. Only shown when Channel is email.	Valid: plain, personal
Create Conversation Immediately Optional	false	For in-app messages, create a conversation object right away — the response then includes conversation_id.	Boolean

Example output

{ "type": "admin_message", "id": "934", "message_type": "inapp", "body": "<p>Thanks for signing up</p>" }

Documentation of API endpoint that powers action: Intercom API – Create a message (POST /messages)

Create Conversation

Start a contact-initiated conversation — the message appears as sent by the contact. For admin-initiated outreach, use Send Message.

Inputs

Display Key	Example Input	Description	Restrictions
From Type	"user"	Whether the initiating contact is a user or a lead.	Valid: user, lead
From (contact)	"63a07ddf05a32042dffac965"	Intercom contact ID initiating the conversation.	Required
Message	"Hi, I need help with my order"	The opening message (from the contact).	Required

Example output

{ "type": "user_message", "id": "403918227", "conversation_id": "147", "body": "Hi, I need help with my order" }

Documentation of API endpoint that powers action: Intercom API – Create a conversation (POST /conversations)

Search Conversations

Search conversations with filters, cursor-paginated. At least one filter row (or a raw query) is required — Intercom rejects an empty search.

Inputs: same search fields as List Leads / List Users (Search Mode, Filters, Raw Query, Results Per Page, Starting After), using the conversation searchable fields listed in Searching with filters.

Example output

{ "type": "conversation.list", "conversations": [ { "id": "147", "state": "open" } ], "pages": { "next": { "starting_after": "WzE2…" } }, "total_count": 8 }

Documentation of API endpoint that powers action: Intercom API – Search conversations (POST /conversations/search)

Retrieve Conversation

Fetch a conversation by ID.

Inputs

Display Key	Example Input	Description	Restrictions
Conversation ID	"147"	Intercom conversation ID.	Required
Display As Optional	"plaintext"	How to format the conversation parts in the response.	String

Example output

{ "type": "conversation", "id": "147", "state": "open", "source": { "body": "<p>Hi</p>" }, "conversation_parts": { "conversation_parts": [] } }

Documentation of API endpoint that powers action: Intercom API – Retrieve a conversation (GET /conversations/{id})

Reply to Conversation

Reply to a conversation as an admin (visible comment or internal note, up to 10 attachment URLs) or on behalf of the contact. Replying as an admin silently auto-assigns the conversation to that admin. Replying to inbound email conversations requires an Intercom workspace feature flag.

Inputs

Display Key	Example Input	Description	Restrictions
Conversation ID	"147"	Intercom conversation ID.	Required
Message	"Thanks — looking into it now!"	The reply content (HTML allowed).	Required
Admin	"Support Team"	Admin author of the reply. Required when replying as admin.	Required (admin replies)
Contact ID	"63a07ddf05a32042dffac965"	Contact on whose behalf to reply. Required when replying as contact.	Required (contact replies)
Reply Type Optional	"comment"	Visible comment or internal note. Admin replies only.	Valid: comment, note
Attachment URLs Optional	["https://example.com/file.pdf"]	Public URLs of files to attach.	Max 10

Example output

{ "type": "conversation", "id": "147", "state": "open" }

Documentation of API endpoint that powers action: Intercom API – Reply to a conversation (POST /conversations/{id}/reply)

Manage Conversation

Close, snooze, open or assign a conversation.

Inputs

Display Key	Example Input	Description	Restrictions
Conversation ID	"147"	Intercom conversation ID.	Required
Action	"close"	What to do with the conversation.	Valid: close, snooze, open, assign
Acting Admin	"Support Team"	Admin performing the action.	Required
Closing Message Optional	"Resolved — closing this out."	Message posted when closing. Only shown when Action is close.	String
Snoozed Until	1704067200	When the conversation reopens. Only shown (and required) when Action is snooze.	UNIX timestamp (seconds)
Assign To Optional	"admin"	Assign to an admin or a team. Only shown when Action is assign.	Valid: admin, team
Assignee ID	"814860"	Admin or team ID to assign to. Required when Action is assign. There is no API to list team IDs — take them from the Intercom UI.	Required (assign)

Example output

{ "type": "conversation", "id": "147", "state": "closed" }

Documentation of API endpoint that powers action: Intercom API – Manage a conversation (POST /conversations/{id}/parts)

Create Ticket

Create a ticket of a given type for one contact. The valid Ticket Attributes keys depend on the ticket type.

Inputs

Display Key	Example Input	Description	Restrictions
Ticket Type	"Customer issue"	The ticket type, picked from your workspace. Defines which attributes the ticket accepts.	Required
Contact	"63a07ddf05a32042dffac965"	Intercom contact ID the ticket is for (exactly one). Internal (back-office) ticket types silently drop the contact.	Required
Company ID Optional	"63a07ddf05a32042dffac965"	Intercom-provisioned company ID to associate.	String
Ticket Attributes Optional	{"_default_title_":"Order not delivered","_default_description_":"Order #42 is 5 days late"}	Attribute values, keyed by attribute name (not label). For a list attribute, the value is the option ID, not its label.	Keys depend on ticket type

Example output

{ "type": "ticket", "id": "42", "ticket_state": { "category": "submitted" }, "ticket_attributes": { "_default_title_": "Order not delivered" }, "open": true }

Documentation of API endpoint that powers action: Intercom API – Create a ticket (POST /tickets)

Update Ticket

Update a ticket: attributes, state, assignment, open/closed, snooze.

Inputs

Display Key	Example Input	Description	Restrictions
Ticket ID	"42"	Intercom ticket ID (the id field, not ticket_id).	Required
Ticket Attributes Optional	{"_default_title_":"Updated title"}	Attribute values, keyed by attribute name.	Keys depend on ticket type
State Optional	"In progress"	Move the ticket to this state, picked from your workspace ticket states.	—
Acting Admin Optional	"Support Team"	Admin performing the assignment.	—
Assignee ID Optional	"814860"	Admin or team ID to assign the ticket to; 0 unassigns.	String
Open Optional	true	Whether the ticket is open (false = closed).	Boolean
Visible to Contact Optional	true	Whether the ticket is visible to the contact.	Boolean
Snoozed Until Optional	1704067200	Snooze the ticket until this time.	UNIX timestamp (seconds)

Example output

{ "type": "ticket", "id": "42", "ticket_state": { "category": "in_progress" }, "open": true }

Documentation of API endpoint that powers action: Intercom API – Update a ticket (PUT /tickets/{id})

Search Tickets

Search tickets with filters, cursor-paginated. At least one filter row (or a raw query) is required — Intercom rejects an empty search.

Inputs: same search fields as List Leads / List Users, using the ticket searchable fields listed in Searching with filters.

Example output

{ "type": "ticket.list", "tickets": [ { "id": "42", "ticket_state": { "category": "submitted" } } ], "pages": { "next": null }, "total_count": 1 }

Documentation of API endpoint that powers action: Intercom API – Search tickets (POST /tickets/search)

Reply to Ticket

Reply to a ticket as an admin (visible comment or internal note) or on behalf of the contact. Unlike conversation replies, ticket replies do not support attachments.

Inputs

Display Key	Example Input	Description	Restrictions
Ticket ID	"42"	Intercom ticket ID.	Required
Message	"We've shipped a replacement."	The reply content (HTML allowed).	Required
Admin	"Support Team"	Admin author of the reply. Required when replying as admin.	Required (admin replies)
Contact ID	"63a07ddf05a32042dffac965"	Contact replying. Required when replying as contact.	Required (contact replies)
Reply Type Optional	"comment"	Visible comment or internal note. Admin replies only.	Valid: comment, note

Example output

{ "type": "ticket", "id": "42", "open": true }

Documentation of API endpoint that powers action: Intercom API – Reply to a ticket (POST /tickets/{id}/reply)

Track Event

Record an event a user performed. Identify the user by contact ID, external user ID, or email — at least one is required. Fire-and-forget: Intercom processes the event asynchronously.

Inputs

Display Key	Example Input	Description	Restrictions
Event Name	"ordered-item"	Name of the event (lowercase, hyphenated recommended).	Required
Contact ID Optional	"63a07ddf05a32042dffac965"	Intercom contact ID (provide this, User ID, or Email).	One identifier required
User ID (external) Optional	"user_ext_456"	Your external user identifier.	One identifier required
Email Optional	"jane@example.com"	User email.	One identifier required
Occurred At Optional	1704067200	When the event happened. Defaults to now.	UNIX timestamp (seconds)
Metadata Optional	{"order_id":"order-42","price":29.99}	Flat key-value pairs about the event. Values can be strings, numbers, booleans, a rich link {"url":…,"value":…}, or a monetary amount {"amount":…,"currency":…}. Intercom silently drops invalid metadata, so WeWeb validates it up front.	Flat object, max 10 keys

Example output

{ "accepted": true }

Verify the event in the contact's event feed — Intercom returns no body for event submissions.

Documentation of API endpoint that powers action: Intercom API – Submit a data event (POST /events)

Create Tag

Create a new tag in the workspace.

Inputs

Display Key	Example Input	Description	Restrictions
Name	"VIP"	Name of the tag.	Required

Example output

{ "type": "tag", "id": "123", "name": "VIP" }

Documentation of API endpoint that powers action: Intercom API – Create or update a tag (POST /tags)

Tag Contact / Untag Contact

Add or remove a tag on a contact. The untag response is identical to the tag response — verify removal by re-reading the contact.

Inputs

Display Key	Example Input	Description	Restrictions
Contact ID	"63a07ddf05a32042dffac965"	Intercom contact ID.	Required
Tag	"VIP"	Tag to add or remove, picked from your workspace tags.	Required

Example output

{ "type": "tag", "id": "123", "name": "VIP" }

Documentation of API endpoint that powers action: Intercom API – Attach a tag to a contact (POST /contacts/{id}/tags)

Attach / Detach Company

Associate or dissociate a company with a contact. Even after a confirmed attach, companies can be slow to surface in company lists — confirm the association from the contact side.

Inputs

Display Key	Example Input	Description	Restrictions
Contact ID	"63a07ddf05a32042dffac965"	Intercom contact ID.	Required
Company ID	"63a07ddf05a32042dffac965"	Intercom-provisioned company ID.	Required

Example output

{ "id": "63a07ddf05a32042dffac965", "name": "Acme Corporation" }

Documentation of API endpoint that powers action: Intercom API – Attach a contact to a company (POST /contacts/{id}/companies)

Add Note to Contact

Add an internal note to a contact — visible to admins only, not the contact.

Inputs

Display Key	Example Input	Description	Restrictions
Contact ID	"63a07ddf05a32042dffac965"	Intercom contact ID to add the note to.	Required
Note	"Called about the enterprise plan"	The note text (HTML allowed).	Required
Author (admin) Optional	"Support Team"	Admin to attribute the note to.	—

Example output

{ "type": "note", "id": "17495962", "body": "<p>Called about the enterprise plan</p>" }

Documentation of API endpoint that powers action: Intercom API – Create a note (POST /contacts/{id}/notes)

Merge Lead into User

Merge a lead contact into a user contact. The merged lead returns 404 on subsequent GETs.

Inputs

Display Key	Example Input	Description	Restrictions
Lead ID	"63a07ddf05a32042dffac111"	Intercom contact ID of the lead to merge.	Required
User ID	"63a07ddf05a32042dffac965"	Intercom contact ID of the user to merge into.	Required

Example output

{ "id": "63a07ddf05a32042dffac965", "role": "user", "email": "jane@example.com" }

Documentation of API endpoint that powers action: Intercom API – Merge a lead and a user (POST /contacts/merge)

Archive / Unarchive Contact

Archive (soft-delete) or restore a contact — a reversible alternative to permanent deletion. Archived contacts return 404 on GET.

Inputs

Display Key	Example Input	Description	Restrictions
Contact ID	"63a07ddf05a32042dffac965"	Intercom contact ID.	Required

Example output

{ "id": "63a07ddf05a32042dffac965", "type": "contact", "archived": true }

Documentation of API endpoint that powers action: Intercom API – Archive a contact (POST /contacts/{id}/archive)

Error handling

Error code and type	Reason
400 Bad Request	Invalid parameters — e.g. empty search query, invalid event metadata shape, or missing access token on the connection.
401 Unauthorized	Invalid access token, or region mismatch with your workspace.
403 Forbidden	The app lacks the required permission for this endpoint.
404 Not Found	Resource not found — also returned for merged or archived contacts, and briefly for just-created contacts.
409 Conflict	Creating a contact whose email already exists (contact creation is not an upsert).
429 Too Many Requests	Rate limited — about 10,000 requests/min per app, enforced in 10-second windows; check the X-RateLimit-* headers.

FAQs

Why can't I find a contact I just created?

Newly created records take ~10–12 minutes to appear in search results, and search indexes timestamps at day precision. Use the contact ID returned at creation instead of searching, and never create-then-search in the same workflow.

What's the difference between Send Message and Create Conversation?

Send Message is admin-initiated outreach (in-app or email) — no conversation exists until the contact replies (unless you enable Create Conversation Immediately). Create Conversation starts a conversation as the contact, as if they wrote in themselves.

Which company ID do I use where?

Create or Update Company uses your own Company ID (immutable, acts as the upsert key). Every other company action — retrieve, update, delete, attach/detach — uses the Intercom-provisioned id returned by the API.

Why was my ticket created without a contact?

Internal (back-office / issue-type) ticket types silently drop the Contact field — the ticket is created with no contacts and no error. Only customer-facing ticket types associate a contact.

How do I know which Ticket Attributes keys to use?

Attributes are keyed by attribute name (not label), and list attributes take the option ID rather than its label. The default type uses _default_title_ and _default_description_. Pick the ticket type in the editor to see its accepted attributes.

Why don't my webhook triggers fire?

Intercom webhooks cannot be registered via API. Check that the webhook is enabled on the connection, the generated URL is pasted in the Developer Hub's Webhooks section, the topics you need are ticked there, and the connection's Client Secret matches the app's Basic information — signature verification rejects mismatches.

Why did replying to an email conversation fail?

Replying to inbound email conversations via API requires an Intercom workspace feature flag. Contact Intercom support to enable it, or handle those conversations in the Intercom inbox.