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

> This endpoint lists all customers.

## 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 customers.
</ParamField>

<ParamField body="partner_id" type="string - optional">
  Only return customers referred by this partner.
</ParamField>

<ParamField body="search" type="string - optional">
  Filter customers by email. Partial matches are supported.
</ParamField>

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

<ParamField body="status" type="string - optional">
  Filter customers by status. Valid values are: 'lead', 'trialing', 'active',
  'canceled'
</ParamField>

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

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

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

<ParamField body="limit" type="string - optional">
  A limit on the number of customers 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
  customer ID. To receive the next page use the last customer 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
  customer ID. To receive the previous page use the first customer 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 customers matching the query
</ResponseField>

<ResponseField name="data" type="object{object}">
  <Expandable title="properties" defaultOpen={true}>
    <ResponseField name="data" type="array[object]">
      <Expandable title="properties" defaultOpen={false}>
        <ResponseField name="id" type="string">
          Unique identifier for the customer, `uuid` or prefixed with `cust_`
        </ResponseField>

        <ResponseField name="email" type="string">
          Your unique identifier for the customer
        </ResponseField>

        <ResponseField name="partner_id" type="string">
          ID of the referring partner
        </ResponseField>

        <ResponseField name="name" type="string">
          Customer's name
        </ResponseField>

        <ResponseField name="customer_id" type="string">
          Your internal customer identifier
        </ResponseField>

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

        <ResponseField name="updated_at" type="string">
          ISO 8601 timestamp of when the customer became active
        </ResponseField>

        <ResponseField name="status" type="string">
          Current status of the customer. Valid values are: 'lead', 'trialing', 'active',
          'canceled'
        </ResponseField>

        <ResponseField name="program_id" type="string">
          Program ID the customer belongs to
        </ResponseField>

        <ResponseField name="organization_id" type="string">
          Organization ID
        </ResponseField>

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

            <ResponseField name="id" type="string">
              Unique identifier for the partner
            </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="status" type="string">
              Partner's status. Valid values are: 'active', 'pending', 'suspended', 'rejected'.
            </ResponseField>

            <ResponseField name="created_at" type="string">
              ISO 8601 timestamp of when the partner was created
            </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
            </ResponseField>

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

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

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

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

<ResponseExample>
  ```json Response theme={"system"}
  {
    "success": true,
    "has_more": true,
    "total_count": 85,
    "data": {
      "data": [
        {
          "id": "cust_dK9bzRGn46BhVgNFHD6fDgXW",
          "email": "customer@example.com",
          "partner_id": "part_s7mbzRGn46BhVgNFHD6fDgXW",
          "name": "Jim Halpert",
          "customer_id": "jim_halpert_789",
          "created_at": "2025-01-15T14:30:00.000Z",
          "updated_at": "2025-01-15T14:30:00.000Z",
          "status": "active",
          "program_id": "prg_YRsbPDAKhWfdqJbFACheh",
          "organization_id": "org_JE3mfYNL9ci7sFaJazAv2"
        }
      ]
    }
  }
  ```

  ```json Expand Response theme={"system"}
  {
    "success": true,
    "has_more": true,
    "total_count": 85,
    "data": {
      "data": [
        {
          "id": "cust_dK9bzRGn46BhVgNFHD6fDgXW",
          "email": "customer@example.com",
          "partner_id": "part_s7mbzRGn46BhVgNFHD6fDgXW",
          "name": "Jim Halpert",
          "customer_id": "jim_halpert_789",
          "created_at": "2025-01-15T14:30:00.000Z",
          "updated_at": "2025-01-15T15:00:00.000Z",
          "status": "active",
          "program_id": "prg_YRsbPDAKhWfdqJbFACheh",
          "organization_id": "org_JE3mfYNL9ci7sFaJazAv2",
          "partner": {
            "id": "part_s7mbzRGn46BhVgNFHD6fDgXW",
            "first_name": "Michael",
            "last_name": "Scott",
            "email": "michael.scott@dundermifflin.com",
            "company_name": "Dunder Mifflin",
            "status": "active",
            "created_at": "2025-01-13T10:06:11.251Z"
          },
          "program": {
            "id": "prg_YRsbPDAKhWfdqJbFACheh",
            "status": "active",
            "name": "Tolt's Partnership Program",
            "product_name": "Tolt",
            "subdomain": "affiliates",
            "type": "public",
            "currency_code": "USD",
            "created_at": "2024-03-05T10:28:08.984+00:00"
          }
        }
      ]
    }
  }
  ```
</ResponseExample>