Submit a CSAT rating

Request

Record a customer's satisfaction rating for a conversation, with an optional free-text remark.

Fin decides when to ask for a rating — this reuses the CSAT settings on your Fin workflow, not this API. When Fin asks, it fires a csat_requested event over webhooks or SSE carrying the rating options to show the user. Present those options, then submit the user's choice here.

Submitting the same rating again, with no new remark, is a no-op and stays successful, so an at-least-once client can safely retry. Submitting a different rating updates the stored rating while the update window is still open, and a first remark can be added to an already-rated survey. Once a remark has been recorded the rating is locked and can no longer be changed.

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

Security

bearerAuth

Intercom-Versionstring(intercom_version)

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

Default:"2.14"

Enum:"1.0""1.1""1.2""1.3""1.4""2.0""2.1""2.2""2.3""2.4"

Example:2.14

Bodyapplication/jsonrequired

conversation_idstringrequired

Your external conversation ID — the same ID you started the conversation with, and the one echoed on the csat_requested event.

Example:"ext-123"

ratingstringrequired

The rating the user selected — one of the key values from the csat_requested event's options.

Enum:"terrible""bad""ok""good""amazing"

Example:"amazing"

remarkstring

Optional free-text comment the user left alongside the rating. Can be added to an already-rated survey, but only once — the rating locks after a remark is recorded.

Example:"Fin solved my problem in seconds."

curl -i -X POST \
  https://api.intercom.io/fin/csat \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'Intercom-Version: 2.14' \
  -d '{
    "conversation_id": "ext-123",
    "rating": "amazing"
  }'

Responses

Rating recorded successfully

Bodyapplication/json

conversation_idstring

The external ID of the rated conversation.

Example:"ext-123"

ratingstring

The rating now recorded on the conversation.

Enum:"terrible""bad""ok""good""amazing"

Example:"amazing"

statusstring

The result of the submission.

Value:"rated"

Example:"rated"

Response

{
  "conversation_id": "ext-123",
  "rating": "amazing",
  "status": "rated"
}