---
title: "Attach a lead to a conversation"
method: POST
path: "/attach-lead"
tags: ["Conversation Operations"]
---

# Attach a lead to a conversation

`POST /attach-lead`

## Request

- Base URL: `https://api.chat-data.com/api/v2`
- URL: `https://api.chat-data.com/api/v2/attach-lead`
- Auth: HTTP bearer

Attach or update a lead for a specific conversation. This endpoint allows you to associate customer information with a conversation.

**UUID immutability:** Once a lead exists, its uuid can never be changed. Attempting to change an existing lead's uuid returns a 400 error.

**Behavior:**
- If the conversation already has a lead attached, that lead is updated with the provided fields (its uuid cannot be changed).
- If no lead is attached, the system searches for an existing lead using ALL provided identifiers together in a single query (best-effort matching).
- If an existing lead is found, it is updated and attached to the conversation (its uuid cannot be changed).
- If no lead is found, a new lead is created with the provided information and attached to the conversation.

**Search strategy:** Best-effort matching using all provided fields in a single query. For example, if you provide both email and phone, the system will search for a lead that matches BOTH values, not just email OR phone.

**Name matching:** Names are compared with an exact, case-sensitive string match. If several leads match the provided fields (for example, two leads share the same name), one of them is used, and which one is not guaranteed. For deterministic matching, use unique identifiers (email, phone, `leadId`, etc.).

**Creating new leads:** To create a new lead, provide at least one field besides `leadId` (name, email, phone, psid, ig_username, username, or info); `info` must come with another lead field. UUID alone is not sufficient for creation.

**UUID handling:** Pass a lead's uuid as `leadId`. When creating a new lead, the provided `leadId` becomes its uuid; otherwise a new UUID is generated. A uuid must be unique within the chatbot; creating a lead with a uuid that is already in use returns a 400 error.

Example body, updating an existing lead found by email:
```json
{
  "chatbotId": "6650f1c2a9e4b83d2c7a1f05",
  "conversationId": "3f2b8c1e-9a4d-4e7b-8c2a-5d1e6f7a8b9c",
  "email": "jane@chat-data.com",
  "phone": "+14155550123"
}
```

Example body, creating a lead with a specific `leadId`:
```json
{
  "chatbotId": "6650f1c2a9e4b83d2c7a1f05",
  "conversationId": "3f2b8c1e-9a4d-4e7b-8c2a-5d1e6f7a8b9c",
  "leadId": "8d0c2b6e-4f1a-4b7c-9e3d-2a5f6b7c8d9e",
  "name": "Jane Doe",
  "email": "jane@chat-data.com"
}
```

## Request body

- object
  - `chatbotId` string, required: The unique identifier of the chatbot.
  - `conversationId` string, required: The unique identifier of the conversation.
  - `leadId` string: Lead UUID. Can be used alone to find an existing lead, but is not sufficient for creating a new lead. **Important:** Once a lead exists, its uuid can never be changed. Attempting to change it returns a 400 error. When creating a new lead, this value becomes its uuid; otherwise a new UUID is generated.
  - `name` string: Lead name. Can be used to find an existing lead with an exact, case-sensitive string match. If several leads share the same name, one of them is used, and which one is not guaranteed. Use unique identifiers for deterministic matching.
  - `email` string, email: Lead email address. Must be a valid, deliverable email address of at most 254 characters (RFC 5321).
  - `phone` string: Lead phone number. It must be a valid phone number in international format, starting with `+`.
  - `psid` string: Page-scoped ID (typically for Facebook Messenger).
  - `ig_username` string: Instagram username.
  - `username` string: Slack or Telegram username. A platform-specific identifier, distinct from `ig_username` (Instagram) and `psid` (Messenger).
  - `info` string: Additional information about the lead, up to 1,000,000 characters. It may be truncated to 1,000 tokens if "User Info Truncation" is turned on in Settings > Limits Control.

## Response `200`

Successful response.

- object
  - `status` 'success', required
  - `lead` object, required: The lead attached to the conversation.
    - `leadId` string: The unique identifier of the lead (UUID).
    - `name` string: The name of the lead.
    - `email` string: The email address of the lead.
    - `phone` string: The phone number of the lead.
    - `psid` string: The page-scoped ID (PSID) of the lead.
    - `ig_username` string: The Instagram username of the lead.
    - `username` string: The Slack or Telegram username of the lead.
    - `info` string: Additional information about the lead.
    - `source` string: The source of the lead information (always `api` for this endpoint).

## Other responses

- `400`: Bad request (validation errors).
- `401`: Authentication failed: the `Authorization` header is missing or not in the `Bearer <key>` format, the API key does not exist, its workspace is unavailable or has no owner, or the workspace's plan does not include API access. `message` says which.
- `403`: The API key cannot access the requested chatbot. A chatbot-scoped key used with another chatbot's ID gets `Access denied to this chatbot`. A workspace key gets `Chatbot <id> was not found in this API key's workspace. It may have been deleted or moved to another workspace.` when the chatbot does not exist or belongs to another workspace.
- `404`: The chatbot has no conversation with this ID.
- `429`: The workspace sent more than 600 API requests in the last minute. Wait the number of seconds given in the `Retry-After` header (and in `message`) before retrying.

---

[API](https://skmtc.dev/chat-data/apis/chat-data-api-schema-guide.md) · [All operations](https://skmtc.dev/chat-data/apis/chat-data-api-schema-guide/llms.txt) · [OpenAPI document](https://skmtc.dev/chat-data/apis/chat-data-api-schema-guide/revisions/72871007f7f0?raw)