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

# List Partners

> This endpoint lists all partners.

## Base URL `https://api.tolt.com`

<br />

### Query Parameters

<ParamField body="program_id*" type="string">
  The program ID from where you want to list the partners.
</ParamField>

<ParamField body="group_id" type="string - optional">
  Only return partners from this group.
</ParamField>

<ParamField body="email" type="string - optional">
  Return the partner with this exact email address (case-insensitive) within the
  program. Useful for checking whether a partner already exists before creating
  one. Unlike the default listing, an `email` lookup also returns partners who
  have not yet finished onboarding.
</ParamField>

<ParamField body="order" type="asc | desc - optional">
  The order of the partners to return by created\_at. Default is desc.
</ParamField>

<ParamField body="expand" type="array - optional">
  Specify which related objects to include in the response. Valid values are
  **'group'** and **'program'**. Use **expand\[]=group** or **expand\[]=program**
  to include the related objects.
</ParamField>

<ParamField body="include" type="array - optional">
  Specify additional related data to include in the response. Valid value is
  **'stats'**. Use **include\[]=stats**.
</ParamField>

<ParamField body="created_gte" type="string - optional">
  Only return partners created after this date.
</ParamField>

<ParamField body="created_lte" type="string - optional">
  Only return partners created before this date.
</ParamField>

<ParamField body="limit" type="string - optional">
  A limit on the number of partners to return. Default is 10, max is 100.
</ParamField>

<ParamField body="starting_after" type="string - optional">
  A cursor for use in pagination. starting\_after is an object ID that defines
  your place in the list. The value of the starting\_after parameter is the
  partner ID. To receive the next page use the last partner ID from the previous
  page.
</ParamField>

<ParamField body="ending_before" type="string - optional">
  A cursor for use in pagination. ending\_before is an object ID that defines
  your place in the list. The value of the ending\_before parameter is the
  partner ID. To receive the previous page use the first partner ID from the
  previous page.
</ParamField>

### Response

<ResponseField name="success" type="boolean">
  Whether the request was successful
</ResponseField>

<ResponseField name="has_more" type="boolean">
  Whether there are more pages of results available
</ResponseField>

<ResponseField name="total_count" type="integer">
  Total number of partners matching the query
</ResponseField>

<ResponseField name="data" type="array[Object]">
  <Expandable title="properties" defaultOpen={false}>
    <ResponseField name="id" type="string">
      Unique identifier for the partner, `uuid` or prefixed with `part_`.
    </ResponseField>

    <ResponseField name="first_name" type="string">
      Partner's first name
    </ResponseField>

    <ResponseField name="last_name" type="string">
      Partner's last name
    </ResponseField>

    <ResponseField name="email" type="string">
      Partner's email address
    </ResponseField>

    <ResponseField name="company_name" type="string">
      Partner's company name
    </ResponseField>

    <ResponseField name="program_id" type="string">
      Unique identifier for the program the partner belongs to, `uuid` or prefixed
      with `prg_`.
    </ResponseField>

    <ResponseField name="organization_id" type="string">
      Unique identifier for the organization, `uuid` or prefixed with `org_`.
    </ResponseField>

    <ResponseField name="group_id" type="string">
      Unique identifier for the partner's group, `uuid` or prefixed with `grp_`.
    </ResponseField>

    <ResponseField name="payout_method" type="string">
      Partner's selected payout method (e.g., 'paypal', 'crypto', 'wise', 'bank\_transfer', 'wire', 'none')
    </ResponseField>

    <ResponseField name="payout_details" type="object">
      Details specific to the selected payout method (e.g., PayPal email, bank details)
    </ResponseField>

    <ResponseField name="country_code" type="string">
      Two-letter ISO country code of the partner
    </ResponseField>

    <ResponseField name="created_at" type="string">
      ISO 8601 timestamp of when the partner was created
    </ResponseField>

    <ResponseField name="status" type="string">
      Current status of the partner (e.g., 'active', 'pending', 'suspended', 'rejected')
    </ResponseField>

    <ResponseField name="group" type="object">
      <Expandable title="group" defaultOpen={false}>
        Group details when expanded:

        <ResponseField name="id" type="string">
          Unique identifier for the group
        </ResponseField>

        <ResponseField name="name" type="string">
          Name of the group
        </ResponseField>

        <ResponseField name="description" type="string">
          Description of the group
        </ResponseField>

        <ResponseField name="created_at" type="string">
          ISO 8601 timestamp of when the group was created
        </ResponseField>

        <ResponseField name="public_key" type="string">
          Public identifier for the group
        </ResponseField>

        <ResponseField name="default" type="boolean">
          Whether this is the default group
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="program" type="object">
      <Expandable title="program" defaultOpen={false}>
        Program details when expanded:

        <ResponseField name="id" type="string">
          Unique identifier for the program
        </ResponseField>

        <ResponseField name="status" type="string">
          Program status
        </ResponseField>

        <ResponseField name="name" type="string">
          Program name
        </ResponseField>

        <ResponseField name="product_name" type="string">
          Name of the product
        </ResponseField>

        <ResponseField name="subdomain" type="string">
          Program's subdomain
        </ResponseField>

        <ResponseField name="type" type="string">
          Program type (e.g., 'public')
        </ResponseField>

        <ResponseField name="currency_code" type="string">
          Three-letter ISO currency code
        </ResponseField>

        <ResponseField name="cookie_duration" type="integer">
          Duration of tracking cookies in days
        </ResponseField>

        <ResponseField name="payout_methods" type="array">
          Available payout methods
        </ResponseField>

        <ResponseField name="payout_term" type="string">
          Payment terms in days
        </ResponseField>

        <ResponseField name="url_params" type="array">
          Supported URL parameters for tracking
        </ResponseField>

        <ResponseField name="created_at" type="string">
          ISO 8601 timestamp of when the program was created
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="stats" type="object">
      <Expandable title="stats" defaultOpen={false}>
        Stats details when included:

        <ResponseField name="total_clicks" type="integer">
          Total tracked clicks for this partner.
        </ResponseField>

        <ResponseField name="total_customers" type="integer">
          Total non-lead customers attributed to this partner.
        </ResponseField>

        <ResponseField name="total_revenue" type="integer">
          Total non-refunded transaction revenue for this partner (in cents).
        </ResponseField>

        <ResponseField name="total_commission" type="integer">
          Total commission amount for this partner (in cents).
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={"system"}
  curl -X GET 'https://api.tolt.com/v1/partners?program_id=prg_YRsbPDAKhWfdqJbFACheh' \
  -H 'Authorization: Bearer <API_KEY>' \
  -H 'Content-Type: application/json' \
  -d ''
  ```

  ```bash cURL - Find by email theme={"system"}
  curl -X GET 'https://api.tolt.com/v1/partners?program_id=prg_YRsbPDAKhWfdqJbFACheh&email=michael.scott@dundermifflin.com' \
  -H 'Authorization: Bearer <API_KEY>' \
  -H 'Content-Type: application/json' \
  -d ''
  ```

  ```bash cURL - Expand theme={"system"}
  curl -X GET 'https://api.tolt.com/v1/partners?program_id=prg_YRsbPDAKhWfdqJbFACheh&expand[]=group&expand[]=program' \
  -H 'Authorization: Bearer <API_KEY>' \
  -H 'Content-Type: application/json' \
  -d ''
  ```

  ```bash cURL - Include Stats theme={"system"}
  curl -X GET 'https://api.tolt.com/v1/partners?program_id=prg_YRsbPDAKhWfdqJbFACheh&expand[]=group&expand[]=program&include[]=stats' \
  -H 'Authorization: Bearer <API_KEY>' \
  -H 'Content-Type: application/json' \
  -d ''
  ```
</RequestExample>

<ResponseExample>
  ```bash Response theme={"system"}
  {
      "success": true,
      "has_more": true,
      "total_count": 160,
      "data": [
          {
              "id": "part_s7mbzRGn46BhVgNFHD6fDgXW",
              "first_name": "Michael",
              "last_name": "Scott",
              "email": "michael.scott@dundermifflin.com",
              "company_name": "Dunder Mifflin",
              "program_id": "prg_YRsbPDAKhWfdqJbFACheh",
              "organization_id": "org_JE3mfYNL9ci7sFaJazAv2",
              "group_id": "grp_Zc2uw9zm1eyBiD3MHcjV3RDn",
              "payout_method": "paypal",
              "payout_details": {
                  "email": "michael.paypal@dundermifflin.com",
              },
              "country_code": "US",
              "created_at": "2025-01-13T10:06:11.251Z",
          }
      ]
  }
  ```

  ```bash Expand + Include Stats Response theme={"system"}
  {
      "success": true,
      "has_more": true,
      "total_count": 160,
      "data": [
          {
              "id": "part_s7mbzRGn46BhVgNFHD6fDgXW",
              "first_name": "Michael",
              "last_name": "Scott",
              "email": "michael.scott@dundermifflin.com",
              "company_name": "Dunder Mifflin",
              "program_id": "prg_YRsbPDAKhWfdqJbFACheh",
              "organization_id": "org_JE3mfYNL9ci7sFaJazAv2",
              "group_id": "grp_Zc2uw9zm1eyBiD3MHcjV3RDn",
              "payout_method": "paypal",
              "payout_details": {
                  "email": "michael.paypal@dundermifflin.com",
              },
              "country_code": "US",
              "created_at": "2025-01-13T10:06:11.251Z",
              "group": {
                  "id": "grp_Zc2uw9zm1eyBiD3MHcjV3RDn",
                  "name": "Dunder Mifflin Group",
                  "description": "Dunder Mifflin Group 20% off",
                  "created_at": "2024-11-25T15:24:26.846428+00:00",
                  "public_key": "dunder-mifflin-group",
                  "default": true
              },
              "program": {
                  "id": "prg_YRsbPDAKhWfdqJbFACheh",
                  "status": "active",
                  "name": "Tolt's Partnership Program",
                  "product_name": "Tolt",
                  "subdomain": "affiliates",
                  "type": "public",
                  "currency_code": "USD",
                  "cookie_duration": 30,
                  "payout_methods": [
                      "none",
                      "crypto",
                      "wise",
                      "bank_transfer",
                      "wire",
                      "paypal"
                  ],
                  "payout_term": "15",
                  "url_params": [
                      "aff",
                      "via"
                  ],
                  "created_at": "2024-03-05T10:28:08.984+00:00"
              },
              "stats": {
                  "total_clicks": 1024,
                  "total_customers": 112,
                  "total_revenue": 145000,
                  "total_commission": 22000
              }
          }
      ]
  }
  ```
</ResponseExample>