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

# Leads API

> Read, create, update and move leads through each company's own pipeline — by ID, never by stage name.

> [!TIP]
>
> Try signed requests in your browser at the [API Sandbox](https://play2sellsa.github.io/api-sandbox/) — paste your API key and secret, and the playground signs requests automatically.

> [!NOTE]
>
> Examples show the wire-format `Authorization: P2S-SIGN-V1 API_KEY:TIMESTAMP:SIGNATURE` header. To compute the signature in your code, use the `signedRequest` helper in [Authentication](https://docs.play2sell.com/api/authentication.md).

The Leads API lets your system work with the leads of the API key's company: list and read them, create and update them, move them through the pipeline, mark them won or lost, archive them and log notes and activities. Keeping two systems in sync is covered step by step in [Two-way sync](https://docs.play2sell.com/api/integrations/leads-sync.md).

## Before you start

* **One endpoint, one action per call.** Every call is a `POST` to `https://api.play2sell.com/functions/v1/default-integration` with `"action"` in the body. Filters also go in the body, because the signature covers the body and not the query string (see [Conventions](https://docs.play2sell.com/api/conventions.md)).
* **Scopes.** Reading needs `leads:read`; writing needs `leads:write`. One does not imply the other, and neither opens `sync_collaborators` or `sync_activities`. A key without the scope gets `403` with `code: "scope_insufficient"`. Create keys in **Admin > Integrations > API Keys**.
* **Each company has its own pipeline.** Stage names and order are configured per company and can change at any time. Always use the **stage ID** from [`list_pipelines`](#action-list_pipelines), and read **won/lost from `stage.outcome`** (`open`, `won`, `lost`), never from the name.
* **Points stay with Missions.** Changes made through this API update the lead, its stage and its history, but **do not score points** in missions or campaigns. Points from integrations come only from [`sync_activities`](https://docs.play2sell.com/api/integrations/activities).

| Action | Scope | What it does |
| - | - | - |
| [`list_pipelines`](#action-list_pipelines) | `leads:read` | Pipelines and stages, with IDs, outcome and stage requirements |
| [`list_lead_fields`](#action-list_lead_fields) | `leads:read` | The company's lead fields, including custom fields, and where each value appears in the lead |
| [`get_lead`](#action-get_lead) | `leads:read` | One lead, by `lead_id` or by your `external_id` |
| [`list_leads`](#action-list_leads) | `leads:read` | Filtered, cursor-paginated list; also the change feed for sync |
| [`get_lead_history`](#action-get_lead_history) | `leads:read` | Every change to a lead, with before/after values and who made it |
| [`sync_leads`](#action-sync_leads) | `leads:write` | Create or update up to 100 leads per call (forms, landing pages, other systems) |
| [`update_lead`](#action-update_lead) | `leads:write` | Change only the fields you send |
| [`move_lead_stage`](#action-move_lead_stage) | `leads:write` | Move the lead to a stage, following the stage's rules |
| [`close_lead`](#action-close_lead) | `leads:write` | Mark as won or lost, whatever the stages are called |
| [`archive_lead`](#action-archive_lead--restore_lead) / `restore_lead` | `leads:write` | Archive and bring back |
| [`add_lead_activity`](#action-add_lead_activity) | `leads:write` | Log a note, call, WhatsApp, email, meeting or visit on the lead |
| [`list_lead_activities`](#action-list_lead_activities) | `leads:read` | A lead's timeline, or every activity of the company since a date |

## The lead object

Every action that returns a lead returns this shape.

```json theme={null}
{
  "id": "6f1c2a9e-1b7d-4c1e-9a55-3f0b8e7d2c10",
  "external_id": "crm-48213",
  "source": "my-crm",
  "name": "Ana Souza",
  "email": "ana@empresa.com.br",
  "phone": "+5511987654321",
  "document": "12345678909",
  "company_name": "Empresa Ltda",
  "product": "Annual plan",
  "status": "open",
  "pipeline": { "id": "1b0e…", "name": "Leads" },
  "stage": { "id": "c4d2…", "key": "qualified", "name": "Qualified", "order": 2, "outcome": "open" },
  "owner": { "email": "maria@yourcompany.com", "name": "Maria Santos" },
  "value": 12000,
  "expected_close_date": "2026-12-15",
  "win_probability": 40,
  "priority": "high",
  "buying_moment": "3 months",
  "is_important": false,
  "is_starred": true,
  "tags": ["site", "vip"],
  "custom_fields": { "Preferred color": "blue" },
  "notes": "Prefers WhatsApp after 6 pm",
  "lost_reason": null,
  "attribution": {
    "first_touch": { "utm_source": "linkedin", "landing_page": "https://www.example.com/" },
    "last_touch": { "utm_source": "google" }
  },
  "version": 7,
  "last_change": { "origin": "api", "api_key_id": "0d9e…" },
  "created_at": "2026-11-02T13:05:11.204Z",
  "updated_at": "2026-11-20T10:41:52.880Z",
  "stage_changed_at": "2026-11-18T09:12:00.000Z",
  "closed_at": null
}
```

| Field | Meaning |
| - | - |
| `status` | `open`, `won`, `lost` (from the stage's `outcome`) or `archived` |
| `stage.key` | A stable identifier of the stage. It does **not** change when the company renames the stage. Use `stage.id` in calls |
| `custom_fields` | The company's custom fields, label → text. See [`list_lead_fields`](#action-list_lead_fields) |
| `version` | Goes up by 1 each time a field of this contract changes. Use it for [`expected_version`](#avoiding-overwrites-expected_version) |
| `last_change` | Who made the latest change: `origin` is `api` (through this API; `api_key_id` says which key) or `app` (anything else) |
| `closed_at` | When the lead was won or lost; `null` while open |

## Identifying a lead

Write actions and `get_lead` accept **either** form:

* `lead_id`: the SalesOS ID (UUID);
* `external_id` + `source`: your ID, within the `source` you used when creating it (default `api`).

Sending both returns `400`. A lead of another company is never found: the answer is `404 LEAD_NOT_FOUND`.

***

## Reading

### Action: list\_pipelines

The company's pipelines and stages, in order. Call it once, cache it, and refresh when a stage ID you hold is rejected.

```bash theme={null}
curl -X POST https://api.play2sell.com/functions/v1/default-integration \
  -H "Authorization: P2S-SIGN-V1 API_KEY:TIMESTAMP:SIGNATURE" \
  -H "Content-Type: application/json" \
  -d '{"action":"list_pipelines"}'
```

```json theme={null}
{
  "data": {
    "pipelines": [
      {
        "id": "1b0e…", "key": "lead_pipeline", "name": "Leads", "is_default": true,
        "stages": [
          { "id": "a1…", "key": "new", "name": "New", "order": 0, "outcome": "open", "is_terminal": false,
            "requirements": { "document_required": false, "approval_required": false, "field": null } },
          { "id": "b2…", "key": "proposal", "name": "Proposal", "order": 3, "outcome": "open", "is_terminal": false,
            "requirements": { "document_required": true, "approval_required": false,
                              "field": { "label": "Proposal amount", "type": "number", "required": true } } },
          { "id": "c3…", "key": "won", "name": "Closed won", "order": 5, "outcome": "won", "is_terminal": true,
            "requirements": { "document_required": false, "approval_required": true, "field": null } }
        ]
      }
    ]
  },
  "meta": { "request_id": "…", "timestamp": "2026-11-20T10:00:00.000Z" }
}
```

`requirements` tells you what [`move_lead_stage`](#action-move_lead_stage) will ask for when a lead **advances** into that stage.

### Action: list\_lead\_fields

The company's lead fields in screen order, including custom fields. `path` says where the value appears in the lead object (`null` = not exposed by the API).

```json theme={null}
{
  "data": {
    "fields": [
      { "key": "customer_phone", "label": "Phone", "type": "phone", "is_custom": false, "required": true, "options": null, "path": "phone" },
      { "key": "cor_preferida", "label": "Preferred color", "type": "select", "is_custom": true, "required": false,
        "options": ["blue", "green"], "path": "custom_fields.cor_preferida" }
    ]
  }
}
```

### Action: get\_lead

**lead\_id** `string`

SalesOS ID (UUID). Or send `external_id`.

**external\_id** `string`

Your ID (max 255).

**source** `string`

With `external_id`. Default `api`.

```json theme={null}
{ "action": "get_lead", "external_id": "crm-48213", "source": "my-crm" }
```

The answer is always `200`: `{ "data": { "found": true, "lead": { … } } }`, or `{ "found": false, "lead": null }` when the lead does not exist in the company.

### Action: list\_leads

**filters** `object`

All optional, combined with AND. An unknown filter returns `400`, so a typo never returns everything.

| Filter | Type | |
| - | - | - |
| `pipeline_id` | UUID | |
| `stage_ids` | UUID\[] (1–50) | Any of |
| `status` | string or string\[] | `open`, `won`, `lost`, `archived` |
| `owner_email` | string | |
| `source`, `external_id` | string | |
| `tags` | string\[] (1–20) | Any of |
| `q` | string (2–100) | Text in name, email, company or phone |
| `ids` | UUID\[] (1–100) | |
| `created_since`, `created_until`, `updated_since`, `updated_until` | ISO 8601 | |
| `include_archived` | boolean | Archived leads are left out unless `true` (or `status` includes `archived`) |
| `exclude_own_changes` | boolean | Leaves out leads whose **latest** change was made by the calling key. See [Two-way sync](https://docs.play2sell.com/api/integrations/leads-sync.md) |

**sort** `object`

`{ "by": "updated_at" | "created_at", "direction": "asc" | "desc" }`. Default: `updated_at` ascending when `updated_since` is sent, otherwise newest first.

**limit** `integer`

1–500, default 100. Larger values are reduced to 500.

**cursor** `string`

`next_cursor` from the previous page.

```json theme={null}
{ "action": "list_leads", "filters": { "status": "open", "tags": ["site"] }, "limit": 50 }
```

```json theme={null}
{
  "data": {
    "items": [ { "id": "6f1c…", "name": "Ana Souza", "…": "…" } ],
    "next_cursor": "eyJ2IjoxLCJvIjoi…",
    "has_more": true,
    "server_time": "2026-11-20T10:41:57.120Z",
    "sync_watermark": null
  }
}
```

The cursor is tied to the filters and sort that produced it. Changing them in the middle of a pagination returns `400` (`cursor`): start again without a cursor.

**Change feed.** With `updated_since`, the list is ordered by `updated_at` ascending and the answer includes `sync_watermark`. When `has_more` is `false`, use `sync_watermark` as your next `updated_since`: no change made before it can still appear later. See [Two-way sync](https://docs.play2sell.com/api/integrations/leads-sync.md).

### Action: get\_lead\_history

Every change to a lead, oldest first: what changed (before/after), the kind of change and who made it.

```json theme={null}
{ "action": "get_lead_history", "lead_id": "6f1c…", "limit": 100 }
```

```json theme={null}
{
  "data": {
    "found": true,
    "items": [
      {
        "id": 98121, "version": 7, "kind": "stage_changed",
        "changes": {
          "stage_id": { "old": "a1…", "new": "c4d2…" }
        },
        "change_source": { "origin": "app", "api_key_id": null },
        "changed_at": "2026-11-18T09:12:00.000Z"
      }
    ],
    "next_cursor": null,
    "has_more": false
  }
}
```

`kind` is `created`, `updated`, `stage_changed`, `archived` or `restored`. `changes` lists only the fields that changed, each with `old` and `new`. Changes are recorded for leads of the leads pipeline.

***

## Writing

All write actions:

* answer with the lead **as it is after the change**, plus `result`;
* accept an optional [`idempotency_key`](#retrying-safely-idempotency_key) and [`expected_version`](#avoiding-overwrites-expected_version);
* run as one transaction: everything is written, or nothing is.

[`add_lead_activity`](#action-add_lead_activity) answers with the activity instead of the lead, and does not take `expected_version`.

### Action: sync\_leads

Create or update **up to 100 leads per call**: a form on your website, a landing page, another system.

A new lead enters the company's default leads pipeline at the **first stage**, or at the `stage_id` you send.

#### How a lead is recognized

For each item we look for an **active** lead of the company in this order:

1. the same `external_id` **within the same `source`** (two sources never mix);
2. the same `email` (case-insensitive);
3. the same `phone`.

Found: **update**. Not found: **create**. If the email belongs to one lead and the phone to another, the item returns `IDENTITY_CONFLICT` and **nothing is written** for it. The same person twice in a batch creates one lead and updates that same lead the second time.

#### What an update does

| Field | Behavior |
| - | - |
| Absent or empty | Nothing changes (never erases) |
| `name`, `email`, `phone`, `document`, `company_name`, `product` | Replaced |
| `tags` | **Added** to the lead's existing tags |
| `extra_fields` | Merged: a sent label replaces the same label; others stay |
| `attribution` | The **first** one is kept as the lead's origin; every call becomes the last touch and is added to the conversion history (last 20) |
| `owner_email` | Changes the owner only if it is an **active** user of the company |
| `stage_id` | Used only to **create**. On an existing lead it is ignored with the warning `stage_ignored_use_move_lead_stage` |
| `source`, notes | Never changed by this action |

#### Request

**source** `string`

Where the leads come from, lowercase: letters, digits, `_ . -` (max 60). Default `api`.

**idempotency\_key** `string`

Optional. See [Retrying safely](#retrying-safely-idempotency_key).

**leads** `array` *required*

Array of leads (max **100**).

**leads\[].external\_id** `string` *required*

Unique ID of the lead in your system (max 255).

**leads\[].name** `string`

Max 200. To **create**, send at least one of `name`, `email` and `phone`.

**leads\[].email** `string`

Customer email.

**leads\[].phone** `string`

With country code, e.g. `+5511987654321`. Without one, the company's country is assumed.

**leads\[].document** `string`

CPF (11) or CNPJ (14) digits; punctuation is ignored.

**leads\[].company\_name** `string`

Max 200.

**leads\[].product** `string`

Max 300.

**leads\[].tags** `string[]`

Up to 20 tags, 60 characters each.

**leads\[].owner\_email** `string`

Owner. Unknown or inactive: the lead goes to the default owner, with a warning.

**leads\[].stage\_id** `string`

Optional, only for new leads: an **open** stage of the leads pipeline **without requirements** (see `list_pipelines`). Otherwise the item fails with `STAGE_NOT_ALLOWED_ON_CREATE` or `STAGE_NOT_FOUND`.

**leads\[].extra\_fields** `object`

Label → text. Up to 50 fields, 1,000 characters each.

**leads\[].attribution** `object`

`utm_source`, `utm_medium`, `utm_campaign`, `utm_term`, `utm_content`, `landing_page`, `referrer`, `form_id` (500 characters each).

```bash theme={null}
curl -X POST https://api.play2sell.com/functions/v1/default-integration \
  -H "Authorization: P2S-SIGN-V1 API_KEY:TIMESTAMP:SIGNATURE" \
  -H "Content-Type: application/json" \
  -d '{"action":"sync_leads","source":"website","idempotency_key":"form-2026-11-11-0001","leads":[{"external_id":"form-2026-11-11-0001","name":"Ana Souza","email":"ana@empresa.com.br","phone":"+5511987654321","product":"Annual plan","tags":["site"],"attribution":{"utm_source":"linkedin","landing_page":"https://www.example.com/"}}]}'
```

#### Response (200)

One result **per lead, in request order**. A bad item does not fail the batch: it returns `status: "error"` and the others go through.

```json theme={null}
{
  "data": {
    "created": 1, "updated": 1, "errors": 1, "total": 3,
    "results": [
      { "index": 0, "external_id": "form-1", "status": "created", "lead_id": "6f1c…", "matched_by": null, "warnings": ["owner_fallback"] },
      { "index": 1, "external_id": "form-2", "status": "updated", "lead_id": "9a2d…", "matched_by": "email", "warnings": [] },
      { "index": 2, "external_id": "form-3", "status": "error", "lead_id": null, "matched_by": null, "warnings": [],
        "error": { "code": "INVALID_PHONE", "message": "Phone with country code (E.164), e.g. +5511987654321", "field": "phone" } }
    ]
  },
  "meta": { "request_id": "…", "timestamp": "2026-11-11T19:30:00.000Z" }
}
```

| Field | Meaning |
| - | - |
| `status` | `created`, `updated` or `error` |
| `matched_by` | How the existing lead was recognized: `external_id`, `email` or `phone` |
| `warnings` | `owner_fallback`, `owner_not_found`, `stage_ignored_use_move_lead_stage`, `event_not_emitted` |
| `error.code` | `INVALID_ITEM`, `MISSING_EXTERNAL_ID`, `MISSING_CONTACT`, `INVALID_EMAIL`, `INVALID_PHONE`, `INVALID_DOCUMENT`, `INVALID_FIELD`, `IDENTITY_CONFLICT`, `STAGE_NOT_FOUND`, `STAGE_NOT_ALLOWED_ON_CREATE`, `NO_PIPELINE`, `NO_ACTIVE_USER`, `WRITE_FAILED` |

Errors that affect the **whole batch** (`leads` empty or over 100, invalid `source` or `idempotency_key`) answer `400 VALIDATION_ERROR`.

### Action: update\_lead

Changes **only the fields you send**. `null` clears an optional field. An unknown field returns `400`.

**fields** `object` *required*

`name` (cannot be cleared), `email`, `phone`, `document`, `company_name`, `product`, `value` (≥ 0), `expected_close_date` (`YYYY-MM-DD`), `priority` (`low`, `medium`, `high`, `urgent`), `notes` (max 5,000), `buying_moment`, `is_important`, `is_starred`, `owner_email`, `custom_fields` (label → text, or `null` to remove that field; up to 50), `add_tags`, `remove_tags` (up to 20 each).

```json theme={null}
{
  "action": "update_lead",
  "external_id": "crm-48213", "source": "my-crm",
  "fields": { "value": 15000, "owner_email": "joao@yourcompany.com", "add_tags": ["vip"], "custom_fields": { "Preferred color": null } },
  "idempotency_key": "crm-48213-v8"
}
```

Answer: `200` with `{ "data": { "result": "updated", "lead": { … } } }`.

### Action: move\_lead\_stage

Moves the lead to `stage_id`, a stage of **the lead's own pipeline**. Moving **forward** follows the stage's rules exactly as in the app; moving **back** is always allowed.

**stage\_id** `string` *required*

Stage ID from `list_pipelines`.

**document\_url** `string`

When the stage requires a document: an `http(s)` link to it.

**field\_value** `string | number`

When the stage requires a field (`requirements.field`).

**lost\_reason** `string`

When the target stage has `outcome: "lost"` (1–500 characters).

**value** `number`

Updates the lead's value together with the move.

**message** `string`

Message to the leader when the stage requires approval (max 1,000).

| `result` | HTTP | Meaning |
| - | - | - |
| `moved` | 200 | The lead is in the new stage; `status` follows the stage's `outcome` |
| `unchanged` | 200 | The lead was already in that stage |
| `pending_approval` | **202** | The stage requires a leader's approval. The lead **did not move**: the leader was asked, and the answer includes `approval_id` |

A missing requirement returns `422 STAGE_REQUIREMENT_MISSING`, and `details` says what to send:

```json theme={null}
{
  "error": {
    "code": "STAGE_REQUIREMENT_MISSING",
    "message": "The stage requires input before the lead can advance",
    "details": { "requirement": "field", "field": "field_value", "label": "Proposal amount", "type": "number" }
  }
}
```

### Action: close\_lead

Marks the lead as won or lost **by outcome**, whatever the stages are called. It moves the lead to the first stage of its pipeline with that `outcome`, following the same rules as `move_lead_stage`.

**outcome** `string` *required*

`won` or `lost`.

**lost\_reason** `string`

Only with `lost`.

**value** `number`

Final value.

```json theme={null}
{ "action": "close_lead", "lead_id": "6f1c…", "outcome": "lost", "lost_reason": "Bought from a competitor" }
```

If the pipeline has no stage with that outcome: `422 NO_STAGE_FOR_OUTCOME`. To reopen, use `move_lead_stage` to an open stage.

### Action: archive\_lead / restore\_lead

`archive_lead` takes the lead out of the pipeline (`status: "archived"`) without deleting anything. `restore_lead` brings it back with the status it had. Answers `result: "archived"`, `"restored"` or `"unchanged"`. An archived lead cannot be updated or moved (`409 LEAD_ARCHIVED`) until it is restored.

***

## Notes and activities

### Action: add\_lead\_activity

Logs something that happened with the lead. It appears in the lead's timeline in the app, like activities logged there, and **does not score points** (points come from [`sync_activities`](https://docs.play2sell.com/api/integrations/activities)).

**lead\_id** `string`

The lead. Or send `lead_external_id` + `lead_source`.

**lead\_external\_id** `string`

Your ID of the lead (with `lead_source`, default `api`).

**type** `string` *required*

`note`, `call`, `whatsapp`, `email`, `meeting` or `visit`.

**description** `string`

Up to 5,000 characters. Required for `note`.

**occurred\_at** `string`

When it happened (ISO 8601). Default: now. Cannot be in the future.

**author\_email** `string`

Who did it: an active user of the company. Default: the lead's owner.

**external\_id** `string`

Your ID of **this activity** (with `source`, default `api`). Sending the same pair again returns the existing activity (`result: "existing"`, `200`) instead of creating another.

**direction** `string`

`inbound` or `outbound` (calls, messages).

**duration\_seconds** `integer`

0–86,400.

```json theme={null}
{
  "action": "add_lead_activity",
  "lead_external_id": "crm-48213", "lead_source": "my-crm",
  "type": "call", "direction": "outbound", "duration_seconds": 312,
  "description": "Talked about financing; will send documents on Monday",
  "author_email": "maria@yourcompany.com",
  "external_id": "call-99812", "source": "my-crm"
}
```

Answer `201` (created) or `200` (already existed):

```json theme={null}
{
  "data": {
    "result": "created",
    "activity": {
      "id": "5e7a…", "lead_id": "6f1c…", "type": "call",
      "description": "Talked about financing; will send documents on Monday",
      "occurred_at": "2026-11-20T14:02:00.000Z",
      "author": { "email": "maria@yourcompany.com", "name": "Maria Santos" },
      "external_id": "call-99812", "source": "my-crm",
      "direction": "outbound", "duration_seconds": 312,
      "stage_change": null,
      "change_source": { "origin": "api", "api_key_id": "0d9e…" }
    }
  }
}
```

### Action: list\_lead\_activities

One lead's timeline (`lead_id`, or `external_id` + `source`), or **every activity of the company** from `since` on. Includes what was logged in the app and by integrations, oldest first. Stage changes come as `type: "status_change"` with `stage_change.from_stage_id` / `to_stage_id`.

**since** `string`

ISO 8601. Required when no lead is given. Filters by `occurred_at`: an activity logged later with a past `occurred_at` does not show up in a feed that already passed that date.

**types** `string[]`

Only these types, e.g. `["note", "call"]`.

**limit** `integer`

1–500, default 100.

**cursor** `string`

`next_cursor` from the previous page.

Answer: `{ "data": { "found": true, "items": [ … ], "next_cursor": null, "has_more": false } }`. For a lead that does not exist, `found` is `false`.

***

## Retrying safely: idempotency\_key

Networks fail. To retry a write without doing it twice, send an `idempotency_key` (8–255 characters: letters, digits, `_ . : -`) that is unique for that operation, such as your own event ID.

| Situation | Answer |
| - | - |
| First call with the key | Runs normally and saves the answer |
| Same key, **same request**, within 24 h | The saved answer, with `"idempotent_replayed": true`. Nothing is written again |
| Same key, **different request** | `422 IDEMPOTENCY_KEY_REUSED` |
| Same key while the first call is still running | The second call waits for the first and then gets its answer |
| The call ended in an error | Nothing is saved: fix the request and retry with the same key |

The key is per API key: two keys never share it. It is in the **body**, which is signed, not in a header.

## Avoiding overwrites: expected\_version

To change a lead only if nobody changed it since you read it, send the `version` you read as `expected_version`. If the lead is no longer at that version, nothing is written and the answer is `409 VERSION_CONFLICT`, with `details.current_version`. Read the lead again, merge, and retry.

## Errors

| HTTP | `error.code` | Cause | What to do |
| - | - | - | - |
| 400 | `VALIDATION_ERROR` | A field is missing, has the wrong type or is unknown. `details` lists each one | Fix the request |
| 404 | `LEAD_NOT_FOUND` | No such lead in the key's company | Check `lead_id`, or `external_id` + `source` |
| 409 | `LEAD_ARCHIVED` | The lead is archived | `restore_lead` first |
| 409 | `VERSION_CONFLICT` | The lead changed since `expected_version` | Read again and retry |
| 409 | `APPROVAL_PENDING` | A stage change of this lead is already waiting for approval | Wait for the leader |
| 409 | `NO_APPROVER` | The stage requires approval and the owner has no leader | Ask the admin to set the team's leader |
| 422 | `STAGE_NOT_FOUND` | `stage_id` is not a stage of the lead's pipeline | Refresh `list_pipelines` |
| 422 | `STAGE_REQUIREMENT_MISSING` | The stage requires a document or a field | Send what `details` asks for |
| 422 | `NO_STAGE_FOR_OUTCOME` | The pipeline has no won/lost stage | Ask the admin to set the stage outcome |
| 422 | `OWNER_NOT_FOUND` | `owner_email` is not an active user of the company | Use an active user's email |
| 422 | `AUTHOR_NOT_FOUND` | `author_email` is not an active user of the company | Use an active user's email, or leave it out |
| 422 | `IDEMPOTENCY_KEY_REUSED` | Same `idempotency_key`, different request | Use a new key for a new operation |

Authentication errors (`401`, and `403 scope_insufficient` when the key lacks `leads:read` or `leads:write`) and rate limits (`429`) have their own format, the same for every endpoint: see [Authentication](https://docs.play2sell.com/api/authentication.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.