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

# Create Deal

> Create a new deal

## Authentication

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://app.journeybee.io/api/v1/lead-deals" \
    -H "Authorization: Bearer your-api-key-uuid" \
    -H "Content-Type: application/json" \
    -d '{"lead_id": 789, "deal_value": 50000, "label": "Enterprise Deal"}'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://app.journeybee.io/api/v1/lead-deals', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer your-api-key-uuid',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      lead_id: 789,
      deal_value: 50000,
      label: "Enterprise Deal"
    })
  });
  ```
</CodeGroup>

## Request Body Schema

### Basic Deal Information

<ParamField body="lead_id" type="number" required>
  The ID of the lead this deal is associated with
</ParamField>

<ParamField body="deal_value" type="number">
  The value of the deal in the company's default currency
</ParamField>

<ParamField body="label" type="string">
  Deal name/title (auto-generated from lead info if not provided)
</ParamField>

<ParamField body="deal_label" type="string">
  Alternative field name for deal title (legacy support)
</ParamField>

### Stage & Pipeline Configuration

<ParamField body="stage_uuid" type="string">
  UUID of the initial stage to assign this deal to
</ParamField>

<ParamField body="partnership_id" type="number">
  Partnership ID if this is a partnership deal (enables commission calculations)
</ParamField>

### Tags & Custom Fields

<ParamField body="tags" type="array">
  Array of tag IDs to assign to this deal
</ParamField>

<ParamField body="customFields" type="array">
  Array of custom field values for this deal

  <Expandable title="Custom Field Object">
    <ParamField body="customFieldId" type="number" required>
      ID of the custom field
    </ParamField>

    <ParamField body="type" type="string" required>
      Field type: `text`, `textarea`, `number`, `date`, `boolean`, `select`, `multi_select`
    </ParamField>

    <ParamField body="value" type="object" required>
      Field value object matching the field type

      <Expandable title="Value Object Examples">
        <ParamField body="text" type="string">For text fields</ParamField>
        <ParamField body="number" type="number">For number fields</ParamField>
        <ParamField body="date" type="string">For date fields (ISO format)</ParamField>
        <ParamField body="boolean" type="boolean">For boolean fields</ParamField>
        <ParamField body="select" type="number">For select fields (option ID)</ParamField>
        <ParamField body="multi_select" type="array">For multi-select fields (array of option IDs)</ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="partnerCustomFields" type="array">
  Array of custom field values for the partner's copy of the deal

  <Expandable title="Partner Custom Field Object">
    <ParamField body="customFieldId" type="number" required>
      ID of the custom field
    </ParamField>

    <ParamField body="type" type="string" required>
      Field type: `text`, `textarea`, `number`, `date`, `boolean`, `select`, `multi_select`
    </ParamField>

    <ParamField body="value" type="object" required>
      Field value object matching the field type
    </ParamField>
  </Expandable>
</ParamField>

### Integration Support

<ParamField body="integrationName" type="string">
  Name of the integration that created this deal. Options: `Salesforce`, `Hubspot`, `Pipedrive`, `Slack`
</ParamField>

<ParamField body="integrationCustomFields" type="array">
  Custom fields from external integrations

  <Expandable title="Integration Custom Field Object">
    <ParamField body="uuid" type="string" required>
      Custom field UUID from integration
    </ParamField>

    <ParamField body="value" type="any" required>
      Field value from integration
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="powerups" type="object">
  Integration-specific data (e.g., CRM IDs)

  <Expandable title="Powerups Object">
    <ParamField body="pipedrive" type="object">
      Pipedrive integration data

      <Expandable title="Pipedrive Object">
        <ParamField body="deal_id" type="number">Pipedrive deal ID</ParamField>
        <ParamField body="person_id" type="number">Pipedrive person ID</ParamField>
        <ParamField body="organization_id" type="number">Pipedrive organization ID</ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

## Response Schema

<ResponseField name="id" type="number">
  The created deal ID
</ResponseField>

<ResponseField name="uuid" type="string">
  The created deal UUID
</ResponseField>

## Example Request

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://app.journeybee.io/api/v1/lead-deals" \
    -H "Authorization: Bearer jb_api_1234567890abcdef" \
    -H "Content-Type: application/json" \
    -d '{
      "lead_id": 789,
      "deal_value": 150000,
      "label": "TechCorp Enterprise Solution",
      "partnership_id": 456,
      "stage_uuid": "stage-uuid-789",
      "tags": [15, 16],
      "customFields": [
        {
          "customFieldId": 8,
          "type": "select",
          "value": {
            "select": 3
          }
        },
        {
          "customFieldId": 9,
          "type": "text",
          "value": {
            "text": "High-priority enterprise deal with fast-track timeline"
          }
        }
      ],
      "integrationName": "Salesforce",
      "powerups": {
        "salesforce": {
          "opportunity_id": "0061234567890ABC",
          "account_id": "0011234567890DEF"
        }
      }
    }'
  ```

  ```javascript JavaScript theme={null}
  const dealData = {
    lead_id: 789,
    deal_value: 150000,
    label: "TechCorp Enterprise Solution",
    partnership_id: 456,
    stage_uuid: "stage-uuid-789",
    tags: [15, 16],
    customFields: [
      {
        customFieldId: 8,
        type: "select",
        value: {
          select: 3
        }
      },
      {
        customFieldId: 9,
        type: "text",
        value: {
          text: "High-priority enterprise deal with fast-track timeline"
        }
      }
    ],
    integrationName: "Salesforce",
    powerups: {
      salesforce: {
        opportunity_id: "0061234567890ABC",
        account_id: "0011234567890DEF"
      }
    }
  };

  const response = await fetch('https://app.journeybee.io/api/v1/lead-deals', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer jb_api_1234567890abcdef',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(dealData)
  });

  const createdDeal = await response.json();
  ```
</CodeGroup>

## Example Response

<ResponseExample>
  ```json 201 Created theme={null}
  {
    "id": 456,
    "uuid": "deal-uuid-456"
  }
  ```
</ResponseExample>

## Error Responses

<ResponseExample>
  ```json 400 Bad Request theme={null}
  {
    "error": "Lead ID is required or invalid field values"
  }
  ```
</ResponseExample>

<ResponseExample>
  ```json 401 Unauthorized theme={null}
  {
    "error": "Invalid API key or insufficient permissions"
  }
  ```
</ResponseExample>

<ResponseExample>
  ```json 403 Forbidden theme={null}
  {
    "error": "Write access required for this operation"
  }
  ```
</ResponseExample>

<ResponseExample>
  ```json 404 Not Found theme={null}
  {
    "error": "Lead not found or partnership does not exist"
  }
  ```
</ResponseExample>

<ResponseExample>
  ```json 409 Conflict theme={null}
  {
    "error": "Duplicate deal or unique constraint violation"
  }
  ```
</ResponseExample>

## Notes

* Requires API key with `write_access` permission
* Triggers webhook events for external systems