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

# Get a Customer

> Get one customer by ID, including their balance.

Use the `id` returned when the customer was created, which starts with `cus_`. Archived customers are returned too, with `archived_at` set.


## OpenAPI

````yaml GET /v1/customers/{id}
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/{id}:
    get:
      tags:
        - Customers
      summary: Get a customer
      description: |-
        Gets one customer by ID, archived ones included.

        Requires the `customers:read` ability.
      operationId: getCustomerV1
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            pattern: ^cus_[0-9a-z]{26}$
          description: The customer's ID.
      responses:
        '200':
          description: The customer.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerResponseV1'
              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'
                version: v1
        '401':
          $ref: '#/components/responses/ApiKeyUnauthenticatedV1'
        '403':
          $ref: '#/components/responses/ApiKeyForbiddenV1'
        '404':
          description: No customer in your account has this ID.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorV1'
              example:
                error:
                  code: not_found
                  message: No customer matches this request.
                version: v1
        '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:
    CustomerResponseV1:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/CustomerV1'
        version:
          type: string
          enum:
            - v1
    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`.
    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
  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.