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

# Push Deal Stages

> Push your system's pipeline and stage catalog into Recotap

`POST /deal-stages`

Pushes your system's pipeline and stage definitions into Recotap. Max 20 pipelines per request. Create-only — if any `pipelineId` in the request already exists, the **entire request is rejected** with `409 Conflict`. No partial creates.

```bash theme={null}
curl -X POST "https://eapi.recotap.com/api/v1/deal-stages" \
  -H "X-Api-Key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "pipelines": [
      {
        "pipelineId": "smb-pipeline",
        "pipelineLabel": "SMB Sales",
        "stages": [
          { "stageId": "s1", "stageLabel": "Prospecting"   },
          { "stageId": "s2", "stageLabel": "Proposal Sent" },
          { "stageId": "s3", "stageLabel": "Closed Won"    },
          { "stageId": "s4", "stageLabel": "Closed Lost"   }
        ]
      }
    ]
  }'
```

**Request body**

| Field       | Type  | Required | Description                    |
| ----------- | ----- | -------- | ------------------------------ |
| `pipelines` | array | Yes      | Min 1, max 20 pipeline objects |

**Pipeline object**

| Field           | Type   | Required | Description                                            |
| --------------- | ------ | -------- | ------------------------------------------------------ |
| `pipelineId`    | string | Yes      | Your system's unique pipeline ID e.g. `"smb-pipeline"` |
| `pipelineLabel` | string | Yes      | Display name for the pipeline e.g. `"SMB Sales"`       |
| `stages`        | array  | Yes      | Min 1 stage object                                     |

**Stage object**

| Field        | Type   | Required | Description                                                    |
| ------------ | ------ | -------- | -------------------------------------------------------------- |
| `stageId`    | string | Yes      | Your system's unique stage ID within this pipeline e.g. `"s1"` |
| `stageLabel` | string | Yes      | Display name for the stage e.g. `"Closed Won"`                 |

**Response `data`**

```json theme={null}
{
  "results": [
    { "pipelineId": "smb-pipeline",        "status": "created" },
    { "pipelineId": "enterprise-pipeline", "status": "created" }
  ],
  "summary": { "total": 2, "created": 2 }
}
```

## 409 Conflict

Returned when any `pipelineId` in the request already exists. The entire request is rejected — no pipelines are created.

| Condition                       | `customMessage`                           |
| ------------------------------- | ----------------------------------------- |
| Any `pipelineId` already exists | `Pipeline(s) already exist: smb-pipeline` |

The error names the conflicting pipeline IDs so you know exactly which ones to remove from the request.