---
title: "Run a Fin procedure"
method: POST
path: "/fin/procedures/{procedure_id}/run"
tags: ["Fin Agent"]
---

# Run a Fin procedure

`POST /fin/procedures/{procedure_id}/run`

## Request

- Base URL: `https://api.intercom.io`
- URL: `https://api.intercom.io/fin/procedures/{procedure_id}/run`
- Auth: HTTP bearer

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`](/docs/references/2.14/rest-api/api.intercom.io/fin-agent/replytofin).

{% admonition type="warning" %}
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**.
{% /admonition %}

## Path parameters

- `procedure_id` string, required

## Headers

- `Intercom-Version` '1.0' | '1.1' | '1.2' | '1.3' | '1.4' | '2.0' | '2.1' | '2.2' | '2.3' | '2.4' | '2.5' | '2.6' | '2.7' | '2.8' | '2.9' | '2.10' | '2.11' | '2.12' | '2.13' | '2.14': Intercom API version.</br>By default, it's equal to the version set in the app package.

## Request body

- object
  - `conversation_id` string, required: Your external conversation ID. Fin creates a conversation for this ID. If a conversation already exists for it, use `/fin/reply` instead.
  - `user` FinAgentUser, required: A user object representing the user in a Fin Agent conversation.
    - `id` string, required: The ID of the user. This value will be used to uniquely identify the user during a conversation with Fin. Maps to the user_id field on the Intercom User object.
    - `name` string: The name of the user.
    - `email` string, email: The email of the user.
    - `attributes` object: A hash of attributes associated with the user. Attributes can be used by Fin to target content and responses. Limit to 10 attributes.
  - `message` FinAgentMessage: A message exchanged within a Fin Agent conversation.
    - `author` 'user' | 'agent' | 'fin', required: The author that created the message.
    - `body` string, required: The body of the message. Accepts both plain text and HTML format. When sending a message to Fin, this should contain the user's message. Fin's response will be returned as HTML.
    - `timestamp` string, date-time, required: The timestamp when the message was created. Used to deduplicate messages sent within a 5 minute window. Ideally should include milliseconds for higher precision.
    - `timestamp_ms` string, date-time: The timestamp when the message was created, with millisecond precision. Only present in webhook event responses (fin_replied).
  - `conversation_metadata` object: Metadata about the conversation. Only attributes are accepted (no history).
    - `attributes` object: A hash of conversation attributes. Limit to 20 attributes.
  - `environment` string: The identifier of the environment to start the conversation in, if your Fin for Platforms workspace has environments. Use the same value as `messenger_environment` in your Messenger installation. Defaults to the workspace's default environment; an identifier that matches no environment is rejected.

## Response `200`

Procedure run started successfully

- object
  - `conversation_id` string: The ID of the conversation.
  - `intercom_conversation_id` string: The internal Intercom conversation ID, useful for matching this Agent API session to the conversation in Intercom.
  - `user_id` string: The ID of the user.
  - `procedure_id` string: The ID of the procedure that was run.
  - `status` 'thinking' | 'replying' | 'awaiting_user_reply' | 'escalated' | 'resolved' | 'complete': Fin's current status in the conversation workflow.
  - `created_at_ms` string, date-time: The timestamp the response was created at, with millisecond precision.
  - `errors` FinAgentAttributeErrors: Contains error details if any user or conversation attribute updates failed.
    - `user` object: User-related attribute errors.
      - `attributes` object: Map of user attribute names to error messages.
    - `conversation` object: Conversation-related attribute errors.
      - `attributes` object: Map of conversation attribute names to error messages.

## Other responses

- `400`: Bad Request
- `401`: Unauthorized

## Changes

- **2026-10-22** (2.14) `617975a11355`: 1 warning
  - removed the optional property `sse_subscription_url` from the response with the `200` status
- **2026-10-09** (2.14) `f0c534587bb7`: 1 info
  - added the new optional request property `environment`
- **2026-09-28** (2.14) `0a3fd70024a8`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/intercom/apis/intercom-api/changes/fin/procedures/:procedure_id/run/post.md)

---

[API](https://skmtc.dev/intercom/apis/intercom-api.md) - [All operations](https://skmtc.dev/intercom/apis/intercom-api/llms.txt) - [OpenAPI document](https://skmtc.dev/intercom/apis/intercom-api/revisions/15220f68d145?raw)