---
title: "Submit a conversation"
method: POST
path: "/conversations"
---

# Submit a conversation

`POST /conversations`

## Request

- Base URL: `https://insights.reforge.com/api/v1`
- URL: `https://insights.reforge.com/api/v1/conversations`
- Auth: HTTP bearer

Submits conversation data to the system for processing. This can be content like a call transcript, email thread, or chat conversation.

## Request body

- object
  - `id` string: The unique identifier for the conversation.
  - `title` string, nullable: The title of the conversation.
  - `source` string: The source of the conversation.
  - `createdAt` string, date-time: The date and time the conversation was created.
  - `updatedAt` string, date-time, nullable: The date and time the conversation was last updated.
  - `contacts` Contact[]
    - `id` string, required: External contact ID
    - `shouldUnflattenProperties` boolean, nullable: Whether to unflatten properties that are meant to be nested objects for example `{ "plan.type": "Pro" }` will be unflattened to `{ "plan": { "type": "Pro" } }`
    - `properties` object, nullable: Properties prefixed with `$` are handled specially. Otherwise, additional key-value pairs will be metadata once ingested into the system
      - `$email` string, nullable
      - `$name` string, nullable
      - `$createdAt` string, date-time, nullable
      - `$updatedAt` string, date-time, nullable
      - `$contractValue` number, nullable: The contract value of the contact.
    - `account` Account
      - `id` string, required: The unique identifier for the account.
      - `shouldUnflattenProperties` boolean, nullable: Whether to unflatten properties that are meant to be nested objects for example `{ "plan.type": "Pro" }` will be unflattened to `{ "plan": { "type": "Pro" } }`
      - `properties` object
        - `$name` string, required: The name of the account.
        - `$domain` string, required: The domain of the account.
        - `$createdAt` string, date-time, nullable
        - `$updatedAt` string, date-time, nullable
        - `$contractValue` number, nullable: The contract value of the account.
    - `source` string, nullable: Source system to limit search to
  - `messages` object[]
    - `id` string: The unique identifier for the message.
    - `incoming` boolean: Indicates if the message is incoming (from an external user or customer) or outgoing (e.g. from a support agent or sales person on your team).
    - `contactId` string: The unique identifier for the contact that sent this message.
    - `content` string: The content of the message.
    - `createdAt` string, date-time: The date and time the message was created.
    - `shouldUnflattenProperties` boolean, nullable: Whether to unflatten properties that are meant to be nested objects for example `{ "plan.type": "Pro" }` will be unflattened to `{ "plan": { "type": "Pro" } }`
    - `properties` object: Additional metadata properties (key-value pairs)
    - `sourceUrl` string, nullable: URL linking to the source of this message
  - `rating` number, nullable: The numeric rating (integer)
  - `shouldUnflattenProperties` boolean, nullable: Whether to unflatten properties that are meant to be nested objects for example `{ "plan.type": "Pro" }` will be unflattened to `{ "plan": { "type": "Pro" } }`
  - `propagatePropertiesToMessages` boolean, nullable: When true, conversation-level properties are merged into each message's rawData. Message properties take precedence over conversation properties when there are key conflicts.
  - `properties` object: Additional metadata properties (key-value pairs)

## Response `200`

Conversation submitted successfully.

- object
  - `success` boolean

## Other responses

- `400`: Bad request.
- `429`: Rate limit exceeded.

## Changes

- **2026-07-13** `fd623cac2355`: 1 info
  - added the new optional request property `messages/items/sourceUrl`
- **2026-01-21** `110ba574ffeb`: 1 info
  - added the new optional request property `propagatePropertiesToMessages`
- **2025-10-20** `2047ff338631`: 2 info
  - added the new optional request property `contacts/items/properties/$contractValue`
  - added the new optional request property `contacts/items/source`
- **2025-07-10** `50ed1ddfb0f0`: 3 info
  - added the new optional request property `rating`
  - added the new optional request property `title`
  - added the new optional request property `updatedAt`
- **2025-02-26** `f8820abd2c00`: 1 breaking, 4 info
  - the request property `contacts/items/id` became required
  - added the new optional request property `contacts/items/account`
  - the request property `contacts/items/properties` became nullable
  - the request property `contacts/items/properties/$email` became nullable
  - …1 more

[Operation history](https://skmtc.dev/monterey-ai/apis/reforge-insights-formerly-monterey-ai-api/changes/conversations/post.md)

---

[API](https://skmtc.dev/monterey-ai/apis/reforge-insights-formerly-monterey-ai-api.md) - [All operations](https://skmtc.dev/monterey-ai/apis/reforge-insights-formerly-monterey-ai-api/llms.txt) - [OpenAPI document](https://skmtc.dev/monterey-ai/apis/reforge-insights-formerly-monterey-ai-api/revisions/fd623cac2355?raw)
