The intercom API reference.
Home//
REST API Reference
/- List all identity verification secrets
Identity Verification Secret
Identity Verification Secret (with material)
Create an identity verification secret
Delete an identity verification secret
List all identity verific...
Intercom API (Preview)
Download OpenAPI description
Overview
URL
License
Languages
Servers
The production API server
https://api.intercom.io/
The european API server
https://api.eu.intercom.io/
The australian API server
https://api.au.intercom.io/
AI Content
With the AI Content APIs, you can create and manage External Pages and Content Import Sources for your Fin Content Library.
External Pages are pages that you want Fin to be able to answer questions about. The API for External Pages is a great way to ingest into your Fin Content Library pages that are not publicly accessible and hence can't be crawled by Intercom.
Content Import Sources are the sources of those pages, and they are used to determine the default audience for the pages (configured via the UI). You should create a Content Import Source for each source of External Pages that you want to ingest into your Fin Content Library.
You can then iterate through the content from that source via its API and POST it to the External Pages endpoint. That endpoint has an external_id parameter which allows you to specify the identifier from the source. The endpoint will then either create a new External Page or update an existing one as appropriate.",
SchemasOperations
Custom Object Instances
Everything about your Custom Object instances.
Permission Requirements
From now on, to access this endpoint, you need additional permissions. Please head over to the Developer Hub app package authentication settings to configure the required permissions.
SchemasOperations
Fin Agent
Access Fin programmatically via the Fin Agent API endpoints.
Please reach out to your accounts team to discuss access and tailored, hands-on support.
Integration is centered around two endpoints (/fin/start and /fin/reply) and a set of events that notify your application of Fin's status and responses. Events can be delivered via webhooks or Server-Sent Events (SSE).
Events
Configure a webhook endpoint in the Fin Agent API settings to receive events, or use the sse_subscription_url from the API response to subscribe via SSE. See the setup guide for configuration details.
fin_status_updated- Fired when Fin's status changes (awaiting_user_reply, escalated, resolved, complete)fin_replied- Fired when Fin sends a reply to the userfin_reply_chunk- SSE-only streaming event fired during reply generation (requires streaming enabled)
All webhook requests include an X-Fin-Agent-API-Webhook-Signature header for request validation.
Schemas
Identity Verification Secret
Metadata for an HMAC secret used to sign user_hash values for Messenger identity verification. The secret field is intentionally omitted — it is only returned once, in the response to POST /secure_mode_secrets.
Human-readable name for the secret, used to identify it in rotation flows
Example: "Production Web"
{ "type": "identity_verification_secret", "id": "102", "name": "Production Web", "supports_android": false, "supports_ios": false, "supports_web": true, "created_at": 1734537243 }
Identity Verification Secret (with material)
Metadata for an HMAC secret used to sign user_hash values for Messenger identity verification. The secret field is intentionally omitted — it is only returned once, in the response to POST /secure_mode_secrets.
Human-readable name for the secret, used to identify it in rotation flows
Example: "Production Web"
{ "type": "identity_verification_secret", "id": "102", "name": "Production Web", "supports_android": false, "supports_ios": false, "supports_web": true, "created_at": 1734537243, "secret": "9Zw0xNs3vKk0fPz9rwKqNbzH3mPVQmQxL9vhSm9Tk4A" }
Request
Returns the identity verification secrets configured for your workspace.
Each entry includes metadata only — the HMAC signing material itself is never returned by this endpoint. The raw secret is only available once, in the response to POST /secure_mode_secrets. Persist it at that moment.
Security
bearerAuth
- The production API serverhttps://api.intercom.io/secure_mode_secrets
- The european API serverhttps://api.eu.intercom.io/secure_mode_secrets
- The australian API serverhttps://api.au.intercom.io/secure_mode_secrets
- curl
- Node.js
- Ruby
- PHP
- Python
- Java
- Go
- C#
- R
curl -i -X GET \
https://api.intercom.io/secure_mode_secrets \
-H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
-H 'Intercom-Version: Preview'Response
application/json
{ "type": "list", "data": [ { … } ] }
Request
Creates a new identity verification secret for your workspace. Intercom generates a 256-bit, cryptographically random value server-side and returns it once in the response.
This is the only opportunity to capture the secret. Store it in your secure configuration immediately. The secret field is omitted from all subsequent responses (including GET /secure_mode_secrets) — if you lose it, you must rotate a new secret in and delete this one.
You must enable the secret for at least one platform (supports_android, supports_ios, or supports_web). Rotation flow: create the new secret, roll it out to every client signing user_hash values, then delete the old secret with DELETE /secure_mode_secrets/{id} once traffic has cut over.
Security
bearerAuth
- The production API serverhttps://api.intercom.io/secure_mode_secrets
- The european API serverhttps://api.eu.intercom.io/secure_mode_secrets
- The australian API serverhttps://api.au.intercom.io/secure_mode_secrets
- curl
- Node.js
- Ruby
- PHP
- Python
- Java
- Go
- C#
- R
curl -i -X POST \
https://api.intercom.io/secure_mode_secrets \
-H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
-H 'Content-Type: application/json' \
-H 'Intercom-Version: Preview' \
-d '{
"name": "Production Web",
"supports_web": true
}'Response
application/json
{ "type": "identity_verification_secret", "id": "103", "name": "Production Web", "secret": "9Zw0xNs3vKk0fPz9rwKqNbzH3mPVQmQxL9vhSm9Tk4A", "supports_android": false, "supports_ios": false, "supports_web": true, "created_at": 1734537500 }
Request
Soft-deletes an identity verification secret. After deletion, any user_hash values signed with that secret will no longer verify — Messenger sessions depending on it will be rejected on their next request. Use this to complete a rotation: create a new secret, roll it out, then delete the old one.
Security
bearerAuth
- The production API serverhttps://api.intercom.io/secure_mode_secrets/{id}
- The european API serverhttps://api.eu.intercom.io/secure_mode_secrets/{id}
- The australian API serverhttps://api.au.intercom.io/secure_mode_secrets/{id}
- curl
- Node.js
- Ruby
- PHP
- Python
- Java
- Go
- C#
- R
curl -i -X DELETE \
https://api.intercom.io/secure_mode_secrets/102 \
-H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
-H 'Intercom-Version: Preview'Procedures
Submit human-collected input to Fin Procedures via the HITL (Human in the Loop) API.
When a Fin Procedure reaches a HITL step with the API channel enabled, Intercom sends a procedure.hitl_notification.created webhook to your system. Your system collects the required input and responds via the callback endpoint documented here.
This API requires the Procedures HITL API feature to be enabled for your workspace and an OAuth token with the write_conversations scope.
SchemasOperations