Skip to content
Home/
/Fin Agent

Fin Agent

Access Fin programmatically via the Fin Agent API endpoints.

 

To request access to the Fin Agent API, please fill out this form.

 

Use the Fin Agent API as a tool: your agent stays in control and calls Fin capabilities as needed — discover what Fin can do with /fin/capabilities, ask a one-shot question with /fin/ask, run a specific procedure with /fin/procedures/{procedure_id}/run, continue a conversation with /fin/reply, escalate to a human with /fin/escalate, and record a satisfaction rating with /fin/csat. Fin notifies your application of its status and responses through a set of events, delivered via webhooks or Server-Sent Events (SSE).

 

You can also start a standalone conversation with /fin/start, where Fin owns the conversation and passes control back when it's done.

 

Pricing

Fin Agent API conversations are billed on outcomes: you're charged at most once per conversation, and only when Fin reaches a billable outcome such as a resolution. Pricing for the orchestration endpoints is being finalised while they're in Preview. See Understanding Fin outcomes.

 

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 user
  • fin_reply_chunk - SSE-only streaming event fired during reply generation (requires streaming enabled)
  • csat_requested - Fired when Fin asks the user to rate the conversation (submit the choice with POST /fin/csat)

All webhook requests include an X-Fin-Agent-API-Webhook-Signature header for request validation.

Schemas

Discover Fin's capabilities

Request

Return a machine-readable, per-user list of what Fin can do for a given end user, so an orchestrating agent can decide which endpoint to call.

The response is audience-matched to the supplied user: each live, API-triggerable procedure is checked against that user before being included, alongside the static reply and ask actions.

Security
bearerAuth
Headers
Intercom-Versionstring(intercom_version)

Intercom API version.
By default, it's equal to the version set in the app package.

Default:"Preview"
Enum:"1.0""1.1""1.2""1.3""1.4""2.0""2.1""2.2""2.3""2.4"
Example:Preview
Bodyapplication/jsonrequired
userobject(Fin Agent User)required

A user object representing the user in a Fin Agent conversation.

curl -i -X POST \
  https://api.intercom.io/fin/capabilities \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'Intercom-Version: Preview' \
  -d '{
    "user": {
      "id": "123456"
    }
  }'

Responses

Capabilities returned successfully

Bodyapplication/json
versionstring

The API version the capabilities document was generated for.

Example:"Preview"
capabilitiesArray of objects

The list of capabilities available to this user.

Response
{
  "version": "Preview",
  "capabilities": [
    { … },
    { … },
    { … }
  ]
}