---
title: "Ask Fin"
method: POST
path: "/fin/ask"
tags: ["Fin Agent"]
---

# Ask Fin

`POST /fin/ask`

## Request

- Base URL: `https://api.intercom.io`
- URL: `https://api.intercom.io/fin/ask`
- Auth: HTTP bearer

Ask Fin a single, self-contained question and receive one informational answer.

Unlike a conversation, `/fin/ask` is non-conversational: Fin will not ask follow-up
questions, will not run procedures, and will not escalate to a human on its own. You can
still escalate one yourself with `POST /fin/escalate`; the ask conversation is already
closed after its one-shot answer, and escalation leaves it closed while routing the
handoff separately.

Fin's answer is delivered asynchronously via the `fin_replied` event. The conversation
ends with a `complete` status — there is no `awaiting_user_reply` cycle.

{% 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 %}

## 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.
  - `message` FinAgentMessage, required: 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).
  - `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.
  - `conversation_metadata` FinAgentConversationMetadata: Metadata about the conversation, including history and attributes.
    - `history` FinAgentMessage[]: An array of previous messages in the conversation before Fin is initialized. This data provides context to Fin and helps generate a better answer. Limit to the last 10 messages.
      - `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).
    - `attributes` object: A hash of attributes associated with the conversation. These attributes can be used by Fin to provide more contextual responses. Limit to 20 attributes.
  - `attachments` FinAgentAttachment[]: An array of attachments to include with the message. Maximum of 10 attachments.
    - `type` 'url' | 'file', required: The type of attachment.
    - `url` string, uri: The URL of the attachment. Required when type is 'url'. Must be publicly accessible.
    - `name` string: The name of the file. Required when type is 'file'.
    - `content_type` string: The MIME type of the file. Required when type is 'file'.
    - `data` string, byte: Base64-encoded file data. Required when type is 'file'.
  - `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`

Question accepted successfully

- object
  - `conversation_id` string: The external 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.
  - `status` 'thinking' | 'replying' | '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/ask/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)