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

> Retrieve a list of partnerships for a company with filtering, sorting, and pagination support

## Authentication

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://app.journeybee.io/api/v1/partnerships" \
    -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/partnerships', {
    method: 'GET',
    headers: {
      'Authorization': 'Bearer your-api-key-uuid',
      'Content-Type': 'application/json'
    }
  });
  ```
</CodeGroup>

## Query Parameters

<ParamField query="userId" type="number" required>
  The ID of the user making the request (for authorization)
</ParamField>

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

<ParamField query="search" type="string">
  Search partners by name, email, website, country, or assigned users
</ParamField>

<ParamField query="view" type="string">
  Filter by partner type or assignment status. Options: `all`, `assigned`, `referral`, `reseller`
</ParamField>

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

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

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

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

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

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

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

<ParamField query="customFields" type="string">
  JSON string of custom field filters with format: `[{"id": 123, "value": {"text": "search"}}]`
</ParamField>

<ParamField query="sort" type="string">
  JSON string of sort options with format: `[{"type": "stage", "asc": true}]`. Types: `stage`, `category`, `tier`
</ParamField>

## Response Schema

<ResponseField name="partners" type="array">
  Array of partnership objects

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

    <ResponseField name="id" type="number">
      Company partnership ID
    </ResponseField>

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

    <ResponseField name="stage_label" type="string">
      Partnership stage label
    </ResponseField>

    <ResponseField name="stage_series" type="number">
      Partnership stage series (order)
    </ResponseField>

    <ResponseField name="partnership" type="object">
      Partnership details

      <Expandable title="Partnership Details">
        <ResponseField name="id" type="number">Partnership ID</ResponseField>
        <ResponseField name="created_at" type="string">Creation timestamp</ResponseField>
        <ResponseField name="stage" type="string">Partnership stage status</ResponseField>
        <ResponseField name="partner_type" type="string">Type: `referral` or `reseller`</ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="tier" type="object">
      Tier information

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

    <ResponseField name="category" type="object">
      Category information

      <Expandable title="Category Details">
        <ResponseField name="id" type="number">Category ID</ResponseField>
        <ResponseField name="label" type="string">Category name</ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="partner" type="object">
      Partner company information

      <Expandable title="Partner Details">
        <ResponseField name="id" type="number">Partner company ID</ResponseField>
        <ResponseField name="name" type="string">Partner company name</ResponseField>
        <ResponseField name="website_url" type="string">Partner website URL</ResponseField>

        <ResponseField name="logo" type="object">
          Logo information

          <Expandable title="Logo Details">
            <ResponseField name="id" type="number">Logo asset ID</ResponseField>
            <ResponseField name="uuid" type="string">Logo asset UUID</ResponseField>
          </Expandable>
        </ResponseField>

        <ResponseField name="address" type="object">
          Address information

          <Expandable title="Address Details">
            <ResponseField name="country_id" type="number">Country ID</ResponseField>
            <ResponseField name="country_label" type="string">Country name</ResponseField>
          </Expandable>
        </ResponseField>

        <ResponseField name="fallback_data" type="object">
          Fallback partner data for inactive partners
        </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>
        <ResponseField name="color" type="string">User color</ResponseField>
      </Expandable>
    </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="customFields" type="array">
      Array of custom field values

      <Expandable title="Custom Field Object">
        <ResponseField name="id" type="number">Custom field ID</ResponseField>
        <ResponseField name="label" type="string">Custom field label</ResponseField>
        <ResponseField name="type" type="string">Field type: `text`, `textarea`, `number`, `date`, `boolean`, `select`, `multi_select`</ResponseField>
        <ResponseField name="value" type="object">Custom field value object</ResponseField>
        <ResponseField name="custom_field_value_id" type="number">Custom field value ID</ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

## Example Request

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

  ```javascript JavaScript theme={null}
  const response = await fetch(
    'https://app.journeybee.io/api/v1/partnerships?userId=456&view=referral&search=tech',
    {
      method: 'GET',
      headers: {
        'Authorization': 'Bearer jb_api_1234567890abcdef',
        'Content-Type': 'application/json'
      }
    }
  );

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

## Example Response

<ResponseExample>
  ```json Example Response theme={null}
  [
    {
      "total": 1,
      "id": 789,
      "stage_id": 1,
      "stage_label": "Prospecting",
      "stage_series": 1,
      "partnership": {
        "id": 456,
        "created_at": "2024-01-15T10:30:00Z",
        "stage": "accepted",
        "partner_type": "referral"
      },
      "tier": {
        "id": 2,
        "label": "Gold",
        "background_color": "#FFD700",
        "text_color": "#000000"
      },
      "category": {
        "id": 3,
        "label": "Technology"
      },
      "partner": {
        "id": 234,
        "name": "TechCorp Solutions",
        "website_url": "https://techcorp.com",
        "logo": {
          "id": 567,
          "uuid": "logo-uuid-123"
        },
        "address": {
          "country_id": 1,
          "country_label": "United States"
        },
        "fallback_data": null
      },
      "assigned_users": [
        {
          "id": 456,
          "email": "john@company.com",
          "first_name": "John",
          "last_name": "Doe",
          "profile_image_id": 789,
          "profile_image_uuid": "profile-uuid-456",
          "color": "#3B82F6"
        }
      ],
      "tags": [
        {
          "id": 10,
          "label": "High Priority",
          "background_color": "#EF4444",
          "text_color": "#FFFFFF"
        }
      ],
      "customFields": [
        {
          "id": 5,
          "label": "Revenue Potential",
          "type": "number",
          "value": {
            "number": 100000
          },
          "custom_field_value_id": 123
        }
      ]
    }
  ]
  ```
</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>

<ResponseExample>
  ```json 404 Not Found theme={null}
  {
    "error": "Company not found or user not authorized"
  }
  ```
</ResponseExample>

## Notes

* Requires API key with `read_access` permission
* Results are paginated using cursor-based pagination
* Default view is determined by company's enabled partner types
* Custom field filters support complex querying by field type
* Search functionality includes fuzzy matching across multiple fields