# Create a deal

`POST https://api.versionseven.ai/v1/crm/deals`

Creates a deal. Attach an existing lead with `lead_id`, or send `lead` to create one with the deal. Send one or the other, not both. An inline `lead` is created the way [Create a lead](https://docs.versionseven.ai/api-reference/leads/create-lead) does it, and answers the same `409` codes when it can't be.

> **Note:** A `lead_id`, `stage_id` or `owner_id` that isn't in your organization answers `400`, not `404`, so the response never confirms an ID that belongs to another organization.

- Required scope: `crm:write`
- Accepts an `Idempotency-Key` header, which makes retries safe. See [Idempotency](https://docs.versionseven.ai/guides/idempotency).

## Request

**cURL**

```bash
curl -X POST "https://api.versionseven.ai/v1/crm/deals" \
  -H "Authorization: Bearer $VICTORIA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "name": "Acme Corp - Enterprise License",
  "expected_close_date": "2024-03-31T00:00:00+00:00",
  "lead_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "metadata": {
    "campaign": "Q1 outreach",
    "source": "inbound"
  },
  "notes": "Initial meeting scheduled for next week",
  "owner_id": "f4a5b6c7-d8e9-0123-f012-456789012345",
  "probability": 25,
  "stage_id": "d2e3f4a5-b6c7-8901-def0-234567890123",
  "value": 50000
}'
```

**Node.js**

```javascript
const response = await fetch("https://api.versionseven.ai/v1/crm/deals", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.VICTORIA_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": crypto.randomUUID(),
  },
  body: JSON.stringify({
    "name": "Acme Corp - Enterprise License",
    "expected_close_date": "2024-03-31T00:00:00+00:00",
    "lead_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "metadata": {
      "campaign": "Q1 outreach",
      "source": "inbound"
    },
    "notes": "Initial meeting scheduled for next week",
    "owner_id": "f4a5b6c7-d8e9-0123-f012-456789012345",
    "probability": 25,
    "stage_id": "d2e3f4a5-b6c7-8901-def0-234567890123",
    "value": 50000
  }),
});

const data = await response.json();
```

**Python**

```python
import os
import uuid

import requests

response = requests.post(
    "https://api.versionseven.ai/v1/crm/deals",
    headers={
        "Authorization": f"Bearer {os.environ['VICTORIA_API_KEY']}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "name": "Acme Corp - Enterprise License",
        "expected_close_date": "2024-03-31T00:00:00+00:00",
        "lead_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "metadata": {
            "campaign": "Q1 outreach",
            "source": "inbound",
        },
        "notes": "Initial meeting scheduled for next week",
        "owner_id": "f4a5b6c7-d8e9-0123-f012-456789012345",
        "probability": 25,
        "stage_id": "d2e3f4a5-b6c7-8901-def0-234567890123",
        "value": 50000,
    },
)
data = response.json()
```

## Headers

- `Authorization` (string, required): `Bearer` followed by a space and your API key, for example `Bearer vk_…`.
- `Idempotency-Key` (string, optional, at most 255 characters): Any unique string, such as a UUID, that makes retrying this request safe. A repeat with the same key for at least 24 hours returns the original response instead of doing the work again. Use a new key for each distinct request.

## Request body

- `name` (string, required, at most 2,000 characters, example `"Acme Corp - Enterprise License"`): Deal name/title
- `expected_close_date` (string · date-time or null, optional, at most 2,000 characters, example `"2024-03-31T00:00:00+00:00"`): Expected close date
- `lead` (object or null, optional): Inline lead data — a new lead will be created and linked to this deal. Cannot be used together with lead\_id.
  - `first_name` (string, required, at most 2,000 characters, example `"Sarah"`): Lead's first name
  - `last_name` (string, required, at most 2,000 characters, example `"Johnson"`): Lead's last name
  - `annual_revenue` (integer or null, optional, ≥ 0, example `5000000`): Company annual revenue in dollars
  - `company` (string or null, optional, at most 2,000 characters, example `"Acme Corp"`): Company name
  - `company_website` (string or null, optional, at most 2,000 characters, example `"https://acmecorp.com"`): Company website URL
  - `email` (string or null, optional, at most 2,000 characters, example `"sarah.johnson@acmecorp.com"`): Lead's email address (required if linkedin\_url not provided)
  - `employees` (integer or null, optional, ≥ 0, example `150`): Number of employees
  - `industry` (string or null, optional, at most 2,000 characters, example `"Technology"`): Industry sector
  - `linkedin_url` (string or null, optional, at most 2,000 characters, example `"https://linkedin.com/in/sarahjohnson"`): Lead's LinkedIn profile URL (required if email not provided)
  - `title` (string or null, optional, at most 2,000 characters, example `"VP of Sales"`): Job title
- `lead_id` (string · uuid or null, optional, at most 2,000 characters, example `"a1b2c3d4-e5f6-7890-abcd-ef1234567890"`): ID of an existing lead to associate with this deal
- `metadata` (object or null, optional): Additional metadata
- `notes` (string or null, optional, at most 2,000 characters, example `"Initial meeting scheduled for next week"`): Deal notes
- `owner_id` (string · uuid or null, optional, at most 2,000 characters, example `"f4a5b6c7-d8e9-0123-f012-456789012345"`): ID of the deal owner (user)
- `probability` (integer or null, optional, ≥ 0, ≤ 100, example `25`): Win probability percentage (0-100)
- `stage_id` (string · uuid or null, optional, at most 2,000 characters, example `"d2e3f4a5-b6c7-8901-def0-234567890123"`): Initial stage ID (defaults to first stage in pipeline)
- `value` (number or null, optional, ≥ 0, example `50000`): Deal value in dollars

## Response

### `201`

```json
{
  "message": "string",
  "deal": {
    "name": "Acme Corp - Enterprise License",
    "actual_close_date": "2026-01-14T19:30:00+00:00",
    "created_at": "2024-01-15T10:30:00+00:00",
    "custom_fields": {},
    "expected_close_date": "2024-03-31T00:00:00+00:00",
    "id": "e3f4a5b6-c7d8-9012-ef01-345678901234",
    "lead_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "metadata": {},
    "notes": "Initial meeting scheduled for next week",
    "owner_id": "f4a5b6c7-d8e9-0123-f012-456789012345",
    "probability": 75,
    "stage_id": "d2e3f4a5-b6c7-8901-def0-234567890123",
    "updated_at": "2024-01-20T14:45:00+00:00",
    "value": 50000
  },
  "success": true
}
```

- `message` (string, required)
- `deal` (object, required): The created deal
  - `name` (string, required, example `"Acme Corp - Enterprise License"`): Deal name/title
  - `actual_close_date` (string · date-time or null, optional): Actual close date (set when deal is won/lost)
  - `created_at` (string · date-time or null, optional, example `"2024-01-15T10:30:00+00:00"`): When the deal was created
  - `custom_fields` (object or null, optional): Custom fields as key-value pairs
  - `expected_close_date` (string · date-time or null, optional, example `"2024-03-31T00:00:00+00:00"`): Expected close date
  - `id` (string or null, optional, example `"e3f4a5b6-c7d8-9012-ef01-345678901234"`): Deal ID
  - `lead_id` (string or null, optional, example `"a1b2c3d4-e5f6-7890-abcd-ef1234567890"`): Associated lead ID
  - `metadata` (object or null, optional): Additional metadata
  - `notes` (string or null, optional, example `"Initial meeting scheduled for next week"`): Deal notes
  - `owner_id` (string or null, optional, example `"f4a5b6c7-d8e9-0123-f012-456789012345"`): ID of the deal owner (user)
  - `probability` (integer or null, optional, example `75`): Win probability percentage (0-100)
  - `stage_id` (string or null, optional, example `"d2e3f4a5-b6c7-8901-def0-234567890123"`): Current stage ID
  - `updated_at` (string · date-time or null, optional, example `"2024-01-20T14:45:00+00:00"`): When the deal was last updated
  - `value` (number or null, optional, example `50000`): Deal value in dollars
- `success` (boolean, optional, default `true`)

## Errors

Errors share one JSON body: `success`, `error`, `message`, optional `details`, and `request_id`. For example:

```json
{
  "success": false,
  "error": "UNAUTHORIZED",
  "message": "Invalid or inactive API key",
  "request_id": "734d11a1-54d4-414c-9e8d-4e1ada977db4"
}
```

| Status | Code | Meaning |
| --- | --- | --- |
| 400 | `VALIDATION_ERROR` | The request didn't match the endpoint's schema: a missing or malformed field, a bad query parameter, or a value out of range. `details.errors` lists each failing field with its `field`, `message` and `type`. |
| 400 | `INVALID_LEAD` | The `lead_id` in the request body isn't a lead in your organization. This is a `400` rather than a `404` so the response never confirms an ID that belongs to another organization. |
| 400 | `INVALID_STAGE` | The `stage_id` in the request body isn't a stage in your organization. This is a `400` rather than a `404` for the same reason as `INVALID_LEAD`. |
| 400 | `INVALID_OWNER` | The `owner_id` in the request body isn't a member of your organization. This is a `400` rather than a `404` for the same reason as `INVALID_LEAD`. |
| 401 | `UNAUTHORIZED` | The `Authorization` header is missing or malformed, or the API key is unknown or has been deactivated. |
| 401 | `API_KEY_EXPIRED` | The API key is past its expiry date. Create a new key in the Victoria AI app. |
| 403 | `TRIAL_LEAD_CAP_REACHED` | The organization is on a free trial and has used up its lead quota, so the lead wasn't created. `details` carries the `cap`, the number `used` and the `remaining` count. Subscribe in the Victoria AI app to add more. |
| 403 | `INSUFFICIENT_SCOPE` | The API key doesn't have the scope this endpoint requires, such as `leads:write`. |
| 403 | `ORGANIZATION_DEACTIVATED` | The organization that owns this API key has been deactivated. |
| 409 | `LEAD_ALREADY_EXISTS` | A lead with the same email or LinkedIn URL already exists in your organization. From [Create a lead](https://docs.versionseven.ai/api-reference/leads/create-lead), this means the request named no `campaign_id` to enrol the existing lead in, or raced an identical request. Changing a lead's email or LinkedIn URL to another lead's answers it too. When it's known, `details.existing_lead_id` identifies the existing lead. |
| 409 | `LEAD_SUPPRESSED` | The contact is on your organization's do-not-contact list, so the lead wasn't created, enrolled or updated. `details.suppressed_by` is `email`, `domain` or `linkedin_url`, and `details.value` is the entry that matched. |
| 409 | `IDEMPOTENCY_KEY_REUSED` | This `Idempotency-Key` was already used with a different request. Use a new key for each distinct request. |
| 409 | `IDEMPOTENCY_IN_PROGRESS` | The first request with this `Idempotency-Key` is still running. Retry after the `Retry-After` interval. |
| 413 | `PAYLOAD_TOO_LARGE` | The request body is larger than 1 MB. |
| 429 | `RATE_LIMITED` | Too many requests for this API key: more than 100 a minute to one endpoint, or 600 a minute in total. Retry after the number of seconds in the `Retry-After` header. See [Rate limits](https://docs.versionseven.ai/guides/rate-limits). |
| 500 | `INTERNAL_ERROR` | Something failed on our side. The response never includes internal details; quote its `request_id` when you contact support. |
| 503 | `UPSTREAM_TIMEOUT` | A service the API depends on timed out. The request is safe to retry. |
| 503 | `AUTH_UNAVAILABLE` | The API key couldn't be checked because the authentication service was unavailable. The request is safe to retry. |

## Response headers

| Header | Description |
| --- | --- |
| `X-Request-ID` | Correlation ID for the request, also returned as `request_id` in error bodies. Send your own `X-Request-ID`, up to 128 letters, digits, `.`, `_`, `:` or `-`, and it's used instead. |
| `RateLimit-Limit` | Requests allowed to this endpoint per minute. |
| `RateLimit-Remaining` | Requests you can still send to this endpoint right now. |
| `RateLimit-Reset` | Seconds until the endpoint's full limit is available again. |
| `Retry-After` | On a `429`, and on `409 IDEMPOTENCY_IN_PROGRESS`: seconds to wait before retrying. |
| `Idempotent-Replay` | `true` when the response is a stored replay of an earlier request with the same `Idempotency-Key`. |