> ## Documentation Index
> Fetch the complete documentation index at: https://docs.open.cx/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a Connect thread

> Create an order-scoped thread with its initial participants. Idempotent on reference, so call it from your order pipeline without duplicate-guarding.

Create the conversation for an order. Call it when the order is confirmed — the `customer_merchant` lane opens immediately; the `customer_courier` lane waits for a courier.

## Request

<ParamField body="reference" type="string" required>
  Your order ID. Unique per organization and the idempotency key: posting an existing `reference` returns the existing thread with `200`.
</ParamField>

<ParamField body="participants" type="array" required>
  Initial participants. Usually the customer and merchant; couriers are [added later](/api-reference/connect/add-participant).

  <Expandable title="participant">
    <ParamField body="role" type="string" required>
      `customer`, `merchant`, or `courier`.
    </ParamField>

    <ParamField body="external_id" type="string" required>
      Your ID for this person or store. Also accepts an OpenCX `contact_id` for customers already known to your workspace.
    </ParamField>

    <ParamField body="display_name" type="string" required>
      Name shown to the other participants. Never expose contact details here.
    </ParamField>

    <ParamField body="language" type="string">
      BCP-47 code (`ar`, `en`, `hi`…). The Supervisor renders every message in this language for this participant. Defaults to your org's primary language.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="lanes" type="array">
  Lanes to enable. Defaults to `["customer_merchant", "customer_courier"]`; include `"merchant_courier"` to open the third lane.
</ParamField>

<ParamField body="supervisor" type="object">
  Override the org-default [Supervisor](/connect/ai-supervisor) config for this thread.

  <Expandable title="supervisor">
    <ParamField body="mode" type="string">
      `observe`, `assist`, or `resolve` (org default applies when omitted).
    </ParamField>

    <ParamField body="lanes" type="object">
      Per-lane overrides: `{ "customer_courier": { "mode": "assist", "nudge_after_seconds": 300 } }`.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="lifecycle" type="object">
  Override org defaults: `wrap_up_hours` (default `24`), `retention_days` (default `30`).
</ParamField>

<ParamField body="custom_data" type="object">
  Arbitrary JSON stored on the thread and surfaced to the Supervisor as answering context — order total, vertical, promo flags.
</ParamField>

## Response

<ResponseField name="id" type="string">
  Thread ID (`th_…`).
</ResponseField>

<ResponseField name="reference" type="string">
  Your order ID.
</ResponseField>

<ResponseField name="status" type="string">
  `open` on creation. Lifecycle: `open → wrap_up → locked → archived`.
</ResponseField>

<ResponseField name="order_status" type="string">
  Starts at `confirmed`; you drive it via [Update thread](/api-reference/connect/update-thread).
</ResponseField>

<ResponseField name="participants" type="array">
  Participants with server-assigned `id` (`prt_…`) alongside your `external_id`.
</ResponseField>

<ResponseField name="lanes" type="array">
  Lane objects: `id`, `status` (`active` | `waiting` | `closed`), `supervisor_mode`.
</ResponseField>

<RequestExample>
  ```bash cURL theme={"dark"}
  curl -X POST https://api.open.cx/connect/threads \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "reference": "order_84421",
      "participants": [
        { "role": "customer", "external_id": "cus_991",
          "display_name": "Fatima", "language": "ar" },
        { "role": "merchant", "external_id": "mrc_204",
          "display_name": "Shawarma House", "language": "en" }
      ],
      "custom_data": { "vertical": "food", "total": 86.5, "currency": "QAR" }
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json 201 theme={"dark"}
  {
    "id": "th_9f2c4e",
    "reference": "order_84421",
    "status": "open",
    "order_status": "confirmed",
    "participants": [
      { "id": "prt_c81", "role": "customer", "external_id": "cus_991",
        "display_name": "Fatima", "language": "ar" },
      { "id": "prt_m32", "role": "merchant", "external_id": "mrc_204",
        "display_name": "Shawarma House", "language": "en" }
    ],
    "lanes": [
      { "id": "customer_merchant", "status": "active", "supervisor_mode": "resolve" },
      { "id": "customer_courier", "status": "waiting", "supervisor_mode": "resolve" }
    ],
    "custom_data": { "vertical": "food", "total": 86.5, "currency": "QAR" },
    "created_at": "2026-07-30T14:03:11Z"
  }
  ```
</ResponseExample>