> ## 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 Deals

> Upsert deals from your system into Recotap

`POST /deals`

Upserts deals from your system into Recotap. Creates the deal if `externalDealId` is new; updates it if it already exists. Max 100 deals per request. Returns HTTP `200` regardless of per-item outcome.

```bash theme={null}
curl -X POST "https://eapi.recotap.com/api/v1/deals" \
  -H "X-Api-Key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "deals": [
      {
        "externalDealId": "deal-001",
        "name": "Acme Corp - Enterprise Plan",
        "amount": 75000,
        "stageId": "stage-3",
        "stageLabel": "Proposal Sent",
        "pipelineId": "smb-pipeline",
        "pipelineLabel": "SMB Sales",
        "startDate": "2026-01-15T00:00:00Z",
        "closedDate": "2026-06-30T00:00:00Z",
        "ownerName": "Jane Smith",
        "ownerEmail": "jane@yourcompany.com",
        "ownerId": "rep-123",
        "dealCurrencyCode": "USD",
        "associatedAccounts": [
          {
            "externalId": "crm-001",
            "domain": "acme.com",
            "name": "Acme Corp"
          }
        ]
      }
    ]
  }'
```

**Request body**

| Field   | Type  | Required | Description                 |
| ------- | ----- | -------- | --------------------------- |
| `deals` | array | Yes      | Min 1, max 100 deal objects |

**Deal object**

| Field                | Type   | Required | Description                                                                                                                       |
| -------------------- | ------ | -------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `externalDealId`     | string | Yes      | Your system's unique deal ID, used for deduplication e.g. `"deal-001"`                                                            |
| `name`               | string | Yes      | Deal title e.g. `"Acme Corp - Enterprise Plan"`                                                                                   |
| `amount`             | number | No       | Deal value e.g. `75000`                                                                                                           |
| `stageId`            | string | No       | Stage ID in your system e.g. `"stage-3"`                                                                                          |
| `stageLabel`         | string | No       | Stage display name e.g. `"Proposal Sent"`                                                                                         |
| `pipelineId`         | string | No       | Pipeline ID in your system e.g. `"smb-pipeline"`                                                                                  |
| `pipelineLabel`      | string | No       | Pipeline display name e.g. `"SMB Sales"`                                                                                          |
| `startDate`          | string | No       | ISO 8601 deal start date e.g. `"2026-01-15T00:00:00Z"`                                                                            |
| `closedDate`         | string | No       | ISO 8601 expected or actual close date e.g. `"2026-06-30T00:00:00Z"`                                                              |
| `ownerName`          | string | No       | Name of the sales rep who owns this deal in your system e.g. `"Jane Smith"`                                                       |
| `ownerEmail`         | string | No       | Email of the sales rep who owns this deal in your system e.g. `"jane@yourcompany.com"`. Must be a valid email format if provided. |
| `ownerId`            | string | No       | Rep's owner ID in your system e.g. `"rep-123"`                                                                                    |
| `dealCurrencyCode`   | string | No       | e.g. `"USD"`, `"EUR"`, `"GBP"`                                                                                                    |
| `associatedAccounts` | array  | No       | Accounts linked to this deal, used for revenue attribution                                                                        |

**`associatedAccounts` object**

| Field        | Type   | Required | Description                                                                                                                               |
| ------------ | ------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `externalId` | string | No       | Your system account ID e.g. `"crm-001"`                                                                                                   |
| `domain`     | string | No       | Account domain used for matching in Recotap e.g. `"acme.com"`. If no match is found, the deal is still created with the account unlinked. |
| `name`       | string | No       | Company display name e.g. `"Acme Corp"`                                                                                                   |

**Response `data`**

```json theme={null}
{
  "results": [
    { "externalDealId": "deal-001", "status": "upserted" },
    { "externalDealId": "deal-002", "status": "failed", "error": "..." }
  ],
  "summary": { "total": 2, "upserted": 1, "failed": 1 }
}
```