Run a Fin procedure

Request

Deterministically run a specific procedure on a new conversation. Calling this endpoint guarantees that the named procedure runs — there is no non-deterministic routing.

Fin's progress is delivered asynchronously via events. If the procedure pauses for user input, the conversation status becomes awaiting_user_reply — send the user's response with /fin/reply.

To request access to the Fin Agent API, go to Settings > Integrations > Fin Agent API in your workspace and tell us about your use case. Once access is granted, Fin Agent API appears under Fin AI Agent > Deploy.

Security

bearerAuth

Path

procedure_idstringrequired

The ID of the procedure to run.

Example:12345

Intercom-Versionstring(intercom_version)

Intercom API version.
If you omit the header, the API uses the version set in your app package, and 1.0 if none is set.

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

conversation_idstringrequired

Your external conversation ID. Fin creates a conversation for this ID. If a conversation already exists for it, use /fin/reply instead.

Example:"ext-123"

userobject(Fin Agent User)required

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

messageobject

Optional message posted to the conversation before the procedure runs. Only body is required.

conversation_metadataobject

Metadata about the conversation. Only attributes are accepted (no history).

environmentstring

The identifier of the environment to start the conversation in. Only Fin for Platforms workspaces use it; other workspaces ignore it. Use the same value as messenger_environment in your Messenger installation. Defaults to the workspace's default environment. On a Fin for Platforms workspace, an identifier that matches no environment returns a 422 error.

Example:"a1b2c3d4e5"

curl -i -X POST \
  https://api.intercom.io/fin/procedures/12345/run \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'Intercom-Version: Preview' \
  -d '{
    "conversation_id": "ext-123",
    "user": {
      "id": "123456",
      "name": "John Doe",
      "email": "john.doe@example.com"
    }
  }'

Responses

Procedure run started successfully

Bodyapplication/json

conversation_idstring

The ID of the conversation.

Example:"ext-123"

intercom_conversation_idstring

The internal Intercom conversation ID, useful for matching this Agent API session to the conversation in Intercom.

Example:"192837465"

user_idstring

The ID of the user.

Example:"user-456"

procedure_idstring

The ID of the procedure that was run.

Example:"12345"

statusstring

Fin's status when the request was accepted. Always thinking; later statuses arrive as events.

Enum:"thinking""replying""awaiting_user_reply""escalated""resolved""complete"

Example:"thinking"

created_at_msstring, (date-time)

The timestamp the response was created at, with millisecond precision.

Example:"2025-01-24T10:00:00.123Z"

errorsobject(Fin Agent Attribute Errors)

Contains error details if any user or conversation attribute updates failed.

Response

{
  "conversation_id": "ext-123",
  "intercom_conversation_id": "192837465",
  "user_id": "user-456",
  "procedure_id": "12345",
  "status": "thinking",
  "created_at_ms": "2025-01-24T10:00:00.123Z"
}