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

# List Customers

> List your customers, or find the one with a given email.

Without filters, this lists your active customers, oldest first, 50 at a time. Pass `next_cursor` back as `cursor` to get the next page. When `next_cursor` is `null`, you've reached the end.

With `email`, it returns the active customer using that email, or an empty list. Archived customers aren't included, since their email can be used for a new customer.

URL-encode the email before you send it, since a `+` in an address is otherwise read as a space and the lookup comes back empty.


## OpenAPI

````yaml GET /v1/customers
openapi: 3.1.0
info:
  title: Juiced API
  description: >-
    API for submitting pings and leads to Juiced. Build on the v1 endpoints
    under `/v1`. The unversioned `/ping` and `/leads` endpoints are the frozen
    legacy contract and are deprecated.
  version: 1.0.0
servers:
  - url: https://usejuiced.com/api
    description: Production server
security:
  - Basic Auth: []
  - Bearer Token: []
tags:
  - name: v1
    description: The current API. Build on these endpoints.
  - name: Customers
    description: Create and look up your customers with an API key.
  - name: Legacy
    description: The frozen, deprecated unversioned endpoints.
paths:
  /v1/customers:
    get:
      tags:
        - Customers
      summary: List customers
      description: >-
        Lists your active customers, oldest first, 50 at a time. With `email`,
        returns the active customer using that email, or an empty list.


        Requires the `customers:read` ability.
      operationId: listCustomersV1
      parameters:
        - name: email
          in: query
          required: false
          schema:
            type: string
          description: >-
            Find the customer using this email. URL-encode it, since a `+` in an
            address is otherwise read as a space and the lookup comes back
            empty.
        - name: cursor
          in: query
          required: false
          schema:
            type: string
          description: The `next_cursor` from the previous page.
      responses:
        '200':
          description: A page of customers.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerListResponseV1'
              example:
                data:
                  - id: cus_01jbx8p4r6t8v0x2z4b6d8f0hk
                    name: Acme Roofing
                    email: owner@acme-roofing.com
                    phone: null
                    address: null
                    address_2: null
                    city: null
                    state: null
                    zip: null
                    country: null
                    paused: false
                    can_access_bidding: false
                    can_access_club: false
                    balance: 0
                    daily_lead_cap: null
                    weekly_lead_cap: null
                    monthly_lead_cap: null
                    daily_budget: null
                    weekly_budget: null
                    monthly_budget: null
                    archived_at: null
                    created_at: '2026-11-17T15:04:05Z'
                    updated_at: '2026-11-17T15:04:05Z'
                next_cursor: null
                version: v1
        '401':
          $ref: '#/components/responses/ApiKeyUnauthenticatedV1'
        '403':
          $ref: '#/components/responses/ApiKeyForbiddenV1'
        '429':
          $ref: '#/components/responses/RateLimitedV1'
        '500':
          $ref: '#/components/responses/ServerErrorV1'
      security:
        - API Key: []
components:
  headers:
    XRequestId:
      description: >-
        Unique ID for this request, sent on every v1 response (errors included).
        Quote it when contacting support.
      schema:
        type: string
        pattern: ^req_[0-9a-z]{26}$
        example: req_01jbx8k6y3a5c7e9g1j3m5p7rt
    RetryAfter:
      description: Seconds to wait before retrying.
      schema:
        type: integer
        example: 30
  schemas:
    CustomerListResponseV1:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/CustomerV1'
        next_cursor:
          type:
            - string
            - 'null'
          description: Pass as `cursor` to get the next page. `null` on the last page.
        version:
          type: string
          enum:
            - v1
    CustomerV1:
      title: Customer
      type: object
      properties:
        id:
          type: string
          pattern: ^cus_[0-9a-z]{26}$
          description: The customer's public ID.
        name:
          type: string
        email:
          type: string
          format: email
        phone:
          type:
            - string
            - 'null'
          description: Phone number.
        address:
          type:
            - string
            - 'null'
          description: Street address.
        address_2:
          type:
            - string
            - 'null'
          description: Second address line.
        city:
          type:
            - string
            - 'null'
          description: City.
        state:
          type:
            - string
            - 'null'
          description: State, province or region.
        zip:
          type:
            - string
            - 'null'
          description: Postal code.
        country:
          type:
            - string
            - 'null'
          description: 'Two-letter country code: `US`, `CA`, `AU` or `LV`.'
        paused:
          type: boolean
          description: Whether the customer is paused and gets no leads.
        can_access_bidding:
          type: boolean
          description: Whether the customer can place bids.
        can_access_club:
          type: boolean
          description: Whether the customer can join the Club.
        balance:
          type: number
          description: Available balance in dollars, after funds held for pending pings.
        daily_lead_cap:
          type:
            - integer
            - 'null'
          description: Most leads a day.
        weekly_lead_cap:
          type:
            - integer
            - 'null'
          description: Most leads a week.
        monthly_lead_cap:
          type:
            - integer
            - 'null'
          description: Most leads a month.
        daily_budget:
          type:
            - number
            - 'null'
          description: Most spent a day, in dollars.
        weekly_budget:
          type:
            - number
            - 'null'
          description: Most spent a week, in dollars.
        monthly_budget:
          type:
            - number
            - 'null'
          description: Most spent a month, in dollars.
        archived_at:
          type:
            - string
            - 'null'
          description: When the customer was archived.
          format: date-time
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    ErrorV1:
      title: Error
      type: object
      required:
        - error
        - version
      properties:
        error:
          type: object
          required:
            - code
            - message
          properties:
            code:
              type: string
              enum:
                - unauthenticated
                - validation_failed
                - quota_reached
                - ping_mismatch
                - idempotency_conflict
                - idempotency_in_progress
                - idempotency_reserved
                - idempotency_version_mismatch
                - rate_limited
                - not_found
                - method_not_allowed
                - bad_request
                - server_error
              description: Machine-readable error code. Branch on this, not on `message`.
            message:
              type: string
              description: Human-readable explanation.
            errors:
              type: object
              description: Only with `validation_failed`. Messages keyed by field.
              additionalProperties:
                type: array
                items:
                  type: string
            lead_id:
              type: string
              pattern: ^lead_[0-9a-z]{26}$
              description: >-
                Only with `idempotency_version_mismatch`. The lead the
                `transaction_id` already created.
        version:
          type: string
          enum:
            - v1
          description: Always `v1`.
  responses:
    ApiKeyUnauthenticatedV1:
      description: The API key is missing, unknown, revoked or expired.
      headers:
        X-Request-Id:
          $ref: '#/components/headers/XRequestId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorV1'
          example:
            error:
              code: unauthenticated
              message: >-
                Missing or invalid API key. Send an active jz_live_ key as a
                bearer token.
            version: v1
    ApiKeyForbiddenV1:
      description: >-
        The key lacks the ability this endpoint needs, your plan doesn't include
        the API, or your account is locked for an unpaid subscription.
      headers:
        X-Request-Id:
          $ref: '#/components/headers/XRequestId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorV1'
          examples:
            Missing ability:
              summary: Missing ability
              value:
                error:
                  code: bad_request
                  message: This API key does not have the customers:write ability.
                version: v1
            Plan without the API:
              summary: Plan without the API
              value:
                error:
                  code: bad_request
                  message: >-
                    The API is not included in your plan. Upgrade to a paid plan
                    to use it.
                version: v1
            Account locked:
              summary: Account locked
              value:
                error:
                  code: bad_request
                  message: This workspace is locked until its subscription is paid.
                version: v1
    RateLimitedV1:
      description: Too many requests.
      headers:
        X-Request-Id:
          $ref: '#/components/headers/XRequestId'
        Retry-After:
          $ref: '#/components/headers/RetryAfter'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorV1'
          example:
            error:
              code: rate_limited
              message: >-
                Too many requests. Retry after the number of seconds in the
                Retry-After header.
            version: v1
    ServerErrorV1:
      description: >-
        Something went wrong on our side. Quote the `X-Request-Id` header when
        contacting support.
      headers:
        X-Request-Id:
          $ref: '#/components/headers/XRequestId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorV1'
          example:
            error:
              code: server_error
              message: >-
                An unexpected error occurred. Quote the X-Request-Id header when
                contacting support.
            version: v1
  securitySchemes:
    Basic Auth:
      type: http
      scheme: basic
      description: >-
        Use your source's API key as the username and API secret as the
        password. Base64 encode the credentials in the format
        `api_key:api_secret`.
    Bearer Token:
      type: http
      scheme: bearer
      description: Use a bearer token generated for your source.
    API Key:
      type: http
      scheme: bearer
      description: >-
        An API key from **Configure → API Keys** (it starts with `jz_live_`),
        sent as a bearer token. See [API Keys](/api-reference/api-keys).

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.