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

# Get Deals

> Retrieve a list of deals (lead deals) with advanced filtering, partner visibility controls, and commission data

## Authentication

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://app.journeybee.io/api/v1/lead-deals?view=received" \
    -H "Authorization: Bearer your-api-key-uuid" \
    -H "Content-Type: application/json"
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://app.journeybee.io/api/v1/lead-deals?view=received', {
    method: 'GET',
    headers: {
      'Authorization': 'Bearer your-api-key-uuid',
      'Content-Type': 'application/json'
    }
  });
  ```
</CodeGroup>

## Query Parameters

<ParamField query="view" type="string">
  Filter by deal type/source. Options: `received`, `sent`, `reseller`, `campaigns`
</ParamField>

<ParamField query="cursor" type="string">
  Pagination cursor (ISO timestamp) for fetching the next set of results
</ParamField>

<ParamField query="search" type="string">
  Search deals by deal name, lead company name, email, phone, assigned users, or partner companies
</ParamField>

<ParamField query="assigned" type="number">
  Filter by assignment status. Use `1` to show only assigned deals
</ParamField>

<ParamField query="unassigned" type="number">
  Filter by assignment status. Use `1` to show only unassigned deals
</ParamField>

<ParamField query="showPartnersStages" type="number">
  For reseller deals, show partner's stages instead of your stages. Use `1` to enable
</ParamField>

<ParamField query="stages" type="string">
  Comma-separated list of stage IDs to filter by
</ParamField>

<ParamField query="phases" type="string">
  Comma-separated list of phase IDs to filter by (for sent deals)
</ParamField>

<ParamField query="tags" type="string">
  Comma-separated list of tag IDs to filter by
</ParamField>

<ParamField query="users" type="string">
  Comma-separated list of user IDs to filter by assigned users
</ParamField>

<ParamField query="partnershipIds" type="string">
  Comma-separated list of partnership IDs to filter by
</ParamField>

## Response Schema

<ResponseField name="deals" type="array">
  Array of deal objects

  <Expandable title="Deal Object">
    <ResponseField name="total" type="number">
      Total number of deals matching the query
    </ResponseField>

    <ResponseField name="id" type="number">
      Deal ID
    </ResponseField>

    <ResponseField name="uuid" type="string">
      Deal UUID
    </ResponseField>

    <ResponseField name="created_at" type="string">
      Deal creation timestamp
    </ResponseField>

    <ResponseField name="updated_at" type="string">
      Deal last update timestamp
    </ResponseField>

    <ResponseField name="label" type="string">
      Deal name/title
    </ResponseField>

    <ResponseField name="deal_value" type="number">
      Deal value in company's currency
    </ResponseField>

    <ResponseField name="lead_id" type="number">
      Associated lead ID
    </ResponseField>

    <ResponseField name="company_id" type="number">
      Company ID that owns this deal
    </ResponseField>

    <ResponseField name="partner_type" type="string">
      Partner relationship type: `referral`, `reseller`, `null`
    </ResponseField>

    <ResponseField name="stage_id" type="number">
      Current deal stage ID
    </ResponseField>

    <ResponseField name="stage_label" type="string">
      Current deal stage name
    </ResponseField>

    <ResponseField name="stage_series" type="number">
      Deal stage order/sequence
    </ResponseField>

    <ResponseField name="stage_phase" type="string">
      Deal stage phase category
    </ResponseField>

    <ResponseField name="payment_stage_id" type="number">
      Payment stage ID (for commission tracking)
    </ResponseField>

    <ResponseField name="payment_stage_label" type="string">
      Payment stage name
    </ResponseField>

    <ResponseField name="payment_stage_series" type="number">
      Payment stage order
    </ResponseField>

    <ResponseField name="payment_stage_phase" type="string">
      Payment stage phase
    </ResponseField>

    <ResponseField name="currency_id" type="number">
      Currency ID for deal value
    </ResponseField>

    <ResponseField name="currency_code" type="string">
      Currency code (e.g., USD, EUR)
    </ResponseField>

    <ResponseField name="partnership_id" type="number">
      Partnership ID for partnership deals
    </ResponseField>

    <ResponseField name="campaign_id" type="number">
      Campaign ID for campaign deals
    </ResponseField>

    <ResponseField name="campaign_title" type="string">
      Campaign name for campaign deals
    </ResponseField>

    <ResponseField name="company_campaign_id" type="number">
      Company campaign relationship ID
    </ResponseField>

    <ResponseField name="vendor_stage_id" type="number">
      Vendor stage ID (for reseller deals)
    </ResponseField>

    <ResponseField name="commission_amount" type="number">
      Commission amount for this deal
    </ResponseField>

    <ResponseField name="commission_percentage" type="number">
      Commission percentage applied
    </ResponseField>

    <ResponseField name="tags" type="array">
      Array of assigned tags

      <Expandable title="Tag Object">
        <ResponseField name="id" type="number">Tag ID</ResponseField>
        <ResponseField name="label" type="string">Tag label</ResponseField>
        <ResponseField name="background_color" type="string">Tag background color</ResponseField>
        <ResponseField name="text_color" type="string">Tag text color</ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="assigned_users" type="array">
      Array of assigned users

      <Expandable title="User Object">
        <ResponseField name="id" type="number">User ID</ResponseField>
        <ResponseField name="email" type="string">User email</ResponseField>
        <ResponseField name="first_name" type="string">User first name</ResponseField>
        <ResponseField name="last_name" type="string">User last name</ResponseField>
        <ResponseField name="profile_image_id" type="number">Profile image asset ID</ResponseField>
        <ResponseField name="profile_image_uuid" type="string">Profile image asset UUID</ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="associated_partner" type="array">
      Array of associated partner information

      <Expandable title="Partner Object">
        <ResponseField name="company_id" type="number">Partner company ID</ResponseField>
        <ResponseField name="company_name" type="string">Partner company name</ResponseField>
        <ResponseField name="company_logo_id" type="number">Partner logo asset ID</ResponseField>
        <ResponseField name="company_logo_uuid" type="string">Partner logo asset UUID</ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="campaign_partners" type="array">
      Array of campaign partner information (for campaign deals)

      <Expandable title="Campaign Partner Object">
        <ResponseField name="partners_company_id" type="number">Partner company ID</ResponseField>
        <ResponseField name="partners_company_name" type="string">Partner company name</ResponseField>
        <ResponseField name="partners_company_logo_id" type="number">Partner logo asset ID</ResponseField>
        <ResponseField name="partners_company_logo_uuid" type="string">Partner logo asset UUID</ResponseField>
        <ResponseField name="partnership_id" type="number">Partnership ID</ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

## Example Request

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://app.journeybee.io/api/v1/lead-deals?view=reseller&showPartnersStages=1&search=tech" \
    -H "Authorization: Bearer jb_api_1234567890abcdef" \
    -H "Content-Type: application/json"
  ```

  ```javascript JavaScript theme={null}
  const params = new URLSearchParams({
    view: 'reseller',
    showPartnersStages: '1',
    search: 'tech'
  });

  const response = await fetch(
    `https://app.journeybee.io/api/v1/lead-deals?${params}`,
    {
      method: 'GET',
      headers: {
        'Authorization': 'Bearer jb_api_1234567890abcdef',
        'Content-Type': 'application/json'
      }
    }
  );

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

## Example Response

<ResponseExample>
  ```json Example Response theme={null}
  [
    {
      "total": 1,
      "id": 456,
      "uuid": "deal-uuid-456",
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-15T14:20:00Z",
      "label": "TechCorp Enterprise Deal",
      "deal_value": 250000,
      "lead_id": 789,
      "company_id": 123,
      "partner_type": "reseller",
      "stage_id": 3,
      "stage_label": "Negotiation",
      "stage_series": 3,
      "stage_phase": "negotiation",
      "payment_stage_id": 2,
      "payment_stage_label": "Invoice Sent",
      "payment_stage_series": 2,
      "payment_stage_phase": "pending",
      "currency_id": 1,
      "currency_code": "USD",
      "partnership_id": 234,
      "campaign_id": null,
      "campaign_title": null,
      "company_campaign_id": null,
      "vendor_stage_id": 4,
      "commission_amount": 25000,
      "commission_percentage": 10,
      "tags": [
        {
          "id": 15,
          "label": "Enterprise",
          "background_color": "#8B5CF6",
          "text_color": "#FFFFFF"
        }
      ],
      "assigned_users": [
        {
          "id": 456,
          "email": "sales@company.com",
          "first_name": "Sarah",
          "last_name": "Johnson",
          "profile_image_id": 890,
          "profile_image_uuid": "profile-uuid-890"
        }
      ],
      "associated_partner": [
        {
          "company_id": 345,
          "company_name": "Partner Solutions Inc",
          "company_logo_id": 678,
          "company_logo_uuid": "logo-uuid-678"
        }
      ],
      "campaign_partners": []
    }
  ]
  ```
</ResponseExample>

## Error Responses

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

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

## Notes

* Requires API key with `read_access` permission
* Results are paginated using cursor-based pagination