Intercom API (unofficial showcase)
POST/fin/csat

Submit a Fin conversation CSAT rating

Submits a customer's satisfaction rating for a conversation, with an optional free-text remark. Use the rating option provided in Fin's csat_requested event; submitting a remark locks the rating against further changes.

  • IdempotentThe SDK sends Idempotency-Key, so a retried request is only applied once.

1 parameter · 3 body fields
Intercom-Versionstringoptional
The Intercom API version to use. Defaults to 2.17 when omitted; use a supported version.
Allowed:1.01.11.21.31.42.02.12.22.32.42.52.6Default:2.17

CSAT submission details. conversation_id and rating are required.

conversation_idstringrequired
Your external conversation ID — the same ID you started the conversation with, and the one echoed on the `csat_requested` event.
ratingstringrequired
The rating the user selected — one of the `key` values from the `csat_requested` event's options.
Allowed:terriblebadokgoodamazing
remarkstringoptional
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.

3 status codes
200Returns the conversation ID, the rating recorded for it, and a `rated` status.
conversation_idstringoptional
The external ID of the rated conversation.
ratingstringoptional
The rating now recorded on the conversation.
Allowed:terriblebadokgoodamazing
statusstringoptional
The result of the submission.
Allowed:rated
401Returned when the request is unauthorized.

One documented failure

  • unauthorized

    Access Token Invalid

typestringrequired
The type is error.list
request_idstringoptional
errorsarray<object>required
An array of one or more error objects
422Returned when the rating cannot be recorded, including when the conversation does not exist, Fin did not request a rating, the rating window has closed, a remark has locked the rating, or the rating value is unsupported.
errorsobjectoptional
Validation messages keyed by the field they apply to, or `base` for conversation-level failures.

Error handling

A 401 is returned when the request is unauthorized. A 422 is returned when the conversation has no requested rating, the rating window has closed, the rating is locked by an existing remark, the conversation cannot be found, or rating is not supported; provide the conversation_id and a rating of terrible, bad, ok, good, or amazing. Once remark has been recorded, the rating cannot be changed.