Conversation

Conversations contain messages between multiple participants on a claim.

Conversations in Claimable are message threads between two or more participants, relating to a claim. Each claim can have multiple Conversation records each of which contains at least one Message, which is delivered via email to the recipients involved.

Conversations are the primary way to communicate with parties involved in a claim, such as to collaborate between colleagues, manage external suppliers, liaise with insurers and keep claimants informed.

Conversations must belong to a Claim and can't exist outside of a claim.

The `Conversation` Object

This is a read-only object, returned in GET requests. For POST requests see the ConversationCreate object below.

Attribute	Data Type	Description
id	Integer	Read Only. The unique ID for the conversation given by Claimable.
status	String	Indicates whether the conversation is open or closed. Can only be either `open` or `closed`.
created_by	Integer	Read Only. The ID of the user who created the conversation.
created_at	Timestamp	Read Only. The date/time the conversation was created.
updated_by	Integer	Read Only. The ID of the user who last updated the conversation.
updated_at	Timestamp	Read Only. The date/time the conversation was last updated.
label	Array	Read Only. An array of strings representing labels applied to the conversation.
subject	String	Read Only. The subject of the most recent message in the conversation.
latest_message_preview	String	Read Only. A plain text preview of the body of the most recent message in the conversation.
latest_message_at	Timestamp	Read Only. When the most recent message in the conversation was sent/received.
pinned	Boolean	Indicates if the conversation is pinned (`true`) or not (`false`).
pinned_at	Timestamp	Read Only. The date/time the conversation was pinned, if `pinned: true`.
pinned_by	Integer	Read Only. The ID of the user who pinned the conversation, if `pinned: true`.
messages_count	Integer	Read Only. The total number of messages in the conversation.
received_messages_count	Integer	Read Only. The number of received (inbound) messages in the conversation.
sent_messages_count	Integer	Read Only. The number of sent (outbound) messages in the conversation.
attachments_count	Integer	Read Only. The total number of attachments across all messages in the conversation.
claim	Integer	Read Only. The ID of the claim to which the conversation belongs.
participants	Array	Read Only. An array of `ConversationParticipant`objects representing parties participating in the conversation, each of whom will be sent new messages except the message `sender` who is considered one of the participants. See the ConversationParticipant object definition for more.

Example `Conversation` Object

{
    "id": 12345,
    "created_at": "2026-02-16T20:55:01.477Z",
    "updated_at": "2026-02-16T20:55:01.805Z",
    "created_by": 123,
    "updated_by": 123,
    "status": "closed",
    "labels": ["urgent"],
    "subject": "Your Claim #1234",
    "latest_message_preview": "Dear Mr. Smith, We confirm receipt of your claim...",
    "latest_message_at": "2026-02-16T20:55:01.563Z",
    "pinned": false,
    "pinned_at": null,
    "pinned_by": null,
    "messages_count": 1,
    "received_messages_count": 0,
    "sent_messages_count": 1,
    "attachments_count": 2,
    "claim": 1234,
    "participants": [
        {
            "contact": null,
            "company": null,
            "user": 1234, // <- This participant has an associated user record.
            "name": "James Bond",
            "email": "[email protected]"
        },
				{
            "contact": 1234, // <- This participant has an associated contact record.
            "company": null,
            "user": null,
            "name": "John Smith",
            "email": "[email protected]"
        },
        {
            "contact": null,
            "company": null,
            "user": null,
            "name": "[email protected]",
            "email": "[email protected]" // <- This particpant is just vanilla email address and doesn't have a corresponding contact, company or user record in Claimable. 
        }
    ]
}

The `ConversationCreate` Object

The payload used to create/send conversations is different to the Conversation object above and offers some special features to simplify conversation creation and sending. When sending POST requests use the following schema as the payload to instruct Claimable how to build the conversation and message.

Attribute	Data Type	Description
to	Array	Required. An array of strings representing recipients to whom the message will be sent. Each string must represent a valid recipient and fall into one of the following categories: (1) an email address (e.g. `[email protected]`) - Claimable will attempt to identify a corresponding contact/company record in the account, prioritising parties linked to the claim, otherwise we fall back on just a vanilla email address. (2) a claim party keyword (e.g. `claimant` , `assigned_to`) - Claimable will use the relevant party associated with the claim, assuming they have an email address. Available options are: `created_by`, `assigned_to`, `client`, `broker`, `insurer`, `claimant`, `insured`. (3) a claim party selector (e.g. `contacts:third_party`) - Claimable will select either contacts or appointed suppliers connected to the claim, filtered by either role (for contacts) or type (for suppliers). Available options are: `contacts:{ROLE_KEY}` and `suppliers:{TYPE_KEY}`. `ROLE_KEY` and `TYPE_KEY` are slugs referring to the contact roles and supplier types configured on your account. Ask Claimable support for a full list.
subject	String	Required. The subject of the message.
body	String	Required. The body of the message. Supports basic Markdown for formatting: only bold, italics, underline, lists and links.
from	Integer	An integer referencing the user from whom the message should be sent. Must be a user who has sufficient privileges for sending messages in Claimable. The sender will be added as a `ConversationParticipant` in `participants`. If left blank, Claimable will automatically select the sender based on the following in priority order: (1) the claim handler, if available; (2) the primary account user/admin (account owner); (3) failing that, the most recently active admin user on the account.
pinned	Boolean	Indicates if the conversation is pinned (`true`) or not (`false`). Default is `false`. Pinned conversations are highlighted in Claimable (where they can be unpinned by users) and show under a separate tab to give them prominence.
status	String	Indicates if the conversation is open or closed. Can only be either `open` or `closed`. Default is `closed`. Any new replies/messages on the thread, regardless of provenance, automatically reopen conversations.

Example `ConversationCreate` Object

{
	"subject": "Your Claim #1234",
  "body": "Dear Mr. Smith,\n\nWe confirm receipt of your claim with reference #1234...",
  "to": [
    "claimant", // <- The contact who is set as the claimant on the claim.
		"assigned_to", // <- The user who is assigned to the claim (claim handler).
		"[email protected]" // <- A specific email address which may or may not match an existing contact/company.
  ]
}