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

# List customers

> Returns a paginated list of customers in the workspace.



## OpenAPI

````yaml GET /customers/
openapi: 3.0.3
info:
  title: Piriod API
  version: 1.0.0
  description: >
    Piriod API for billing, payments, procurement and collections.


    All requests require:

    - `Authorization: Token <api_token>` header.

    - `x-simple-workspace: <workspace_id>` header (the account/workspace
    identifier).

    - Optionally `x-piriod-test-mode: true` to operate against test-mode data.


    See the Documentation tab for getting started, integration flows,
    authentication,

    error handling and pagination/filtering guides.
servers:
  - url: https://api.piriod.com
    description: Production
security:
  - TokenAuth: []
paths:
  /customers/:
    get:
      tags:
        - Billing
      summary: List customers
      description: Returns a paginated list of customers in the workspace.
      parameters:
        - $ref: '#/components/parameters/WorkspaceHeader'
        - $ref: '#/components/parameters/TestModeHeader'
        - $ref: '#/components/parameters/PageQuery'
        - $ref: '#/components/parameters/PageSizeQuery'
        - $ref: '#/components/parameters/OrderingQuery'
        - name: country
          in: query
          schema:
            type: string
          description: Filter by country ID.
        - name: email
          in: query
          schema:
            type: string
        - name: name
          in: query
          schema:
            type: string
        - name: tax_id
          in: query
          schema:
            type: string
        - name: created
          in: query
          schema:
            type: string
            format: date-time
          description: 'Use lookups: `created__gte`, `created__lte`.'
        - name: subscriptions
          in: query
          schema:
            type: string
          description: Filter by linked subscription ID.
        - name: sources
          in: query
          schema:
            type: string
          description: Filter by linked source ID.
      responses:
        '200':
          description: Paginated customer list.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Paginated'
                  - type: object
                    properties:
                      results:
                        type: array
                        items:
                          $ref: '#/components/schemas/Customer'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
components:
  parameters:
    WorkspaceHeader:
      name: x-simple-workspace
      in: header
      required: true
      schema:
        type: string
      description: Workspace (account) identifier. Required for every request.
      example: acc_01H8XYZ123ABC
    TestModeHeader:
      name: x-piriod-test-mode
      in: header
      required: false
      schema:
        type: boolean
        default: false
      description: Whether to operate against test-mode data. Defaults to `false`.
    PageQuery:
      name: page
      in: query
      required: false
      schema:
        type: integer
        minimum: 1
        default: 1
      description: Page number to retrieve (1-indexed).
    PageSizeQuery:
      name: page_size
      in: query
      required: false
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 20
      description: Number of items per page.
    OrderingQuery:
      name: ordering
      in: query
      required: false
      schema:
        type: string
      description: |
        Field to sort results by. Prefix with `-` for descending order
        (e.g. `-created`).
  schemas:
    Paginated:
      type: object
      required:
        - count
        - results
      properties:
        count:
          type: integer
          description: Total number of items matching the filter.
          example: 142
        next:
          type: string
          format: uri
          nullable: true
          description: URL of the next page, or `null` if last page.
        previous:
          type: string
          format: uri
          nullable: true
          description: URL of the previous page, or `null` if first page.
        results:
          type: array
          items: {}
          description: The items in the current page.
    Customer:
      type: object
      properties:
        id:
          type: string
          readOnly: true
          example: cus_01H8XYZ123ABC
        name:
          type: string
          maxLength: 100
        address:
          type: string
          maxLength: 64
        country:
          $ref: '#/components/schemas/Country'
        state:
          $ref: '#/components/schemas/State'
        currency:
          type: string
          description: ISO currency code (e.g. CLP, USD).
          example: CLP
        email:
          type: string
          format: email
          nullable: true
        phone:
          type: string
          nullable: true
          maxLength: 16
        website:
          type: string
          format: uri
          nullable: true
        zip_code:
          type: string
          nullable: true
          maxLength: 16
        manager:
          type: string
          nullable: true
          maxLength: 64
          description: Account manager name (free text).
        reference:
          type: string
          nullable: true
          maxLength: 64
          description: External reference for the customer.
        tax_id:
          type: string
          nullable: true
          maxLength: 32
          description: >
            Tax identifier. Required when the customer's country has tax
            regulation

            (e.g. Chile RUT, Mexico RFC, Colombia NIT) and matches the account's
            country.
        tax_settings:
          type: object
          description: >
            Country-specific tax configuration. Schema and required keys depend
            on the

            tax agency of the customer's country.
        metadata:
          type: object
          description: Arbitrary key/value metadata. Filterable via `?metadata__key=value`.
        send_invoices:
          type: boolean
          default: true
          description: Whether to email invoices to the customer.
        send_collections:
          type: boolean
          default: true
          description: Whether to email collection reminders to the customer.
        send_vouchers:
          type: boolean
          default: true
          description: Whether to email payment receipts to the customer.
        status:
          type: string
          enum:
            - active
            - archived
            - pending
          default: active
        contacts:
          type: array
          readOnly: true
          items:
            $ref: '#/components/schemas/Contact'
        sources:
          type: array
          readOnly: true
          items:
            type: string
          description: IDs of reusable payment sources currently chargeable or pending.
        aggregations:
          allOf:
            - $ref: '#/components/schemas/Aggregations'
          readOnly: true
        test_mode:
          type: boolean
          readOnly: true
        created:
          type: string
          format: date-time
          readOnly: true
        updated:
          type: string
          format: date-time
          readOnly: true
      required:
        - name
        - address
        - country
        - state
    Country:
      type: object
      properties:
        id:
          type: string
          example: CL
        name:
          type: string
          example: Chile
        code:
          type: string
          example: '+56'
        has_regulation:
          type: boolean
        currencies:
          type: array
          items:
            type: string
            example: CLP
    State:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        country:
          type: string
          example: CL
    Contact:
      type: object
      properties:
        id:
          type: string
          readOnly: true
          example: con_01H8XYZ123ABC
        customer:
          type: string
          nullable: true
          description: Customer ID this contact belongs to.
        orgunit:
          type: string
          nullable: true
          description: Organisation unit ID. Optional sub-grouping inside a customer.
        name:
          type: string
          maxLength: 64
        email:
          type: string
          format: email
        phone:
          type: string
          maxLength: 12
          nullable: true
        invoicing:
          type: boolean
          default: true
          description: Whether this contact receives invoice emails.
        collections:
          type: boolean
          default: true
          description: Whether this contact receives collection reminders.
        created:
          type: string
          format: date-time
          readOnly: true
        updated:
          type: string
          format: date-time
          readOnly: true
      required:
        - name
        - email
    Aggregations:
      type: object
      properties:
        sales:
          type: number
          format: decimal
          description: Total finalized + paid sales for the customer.
        sales_current_period:
          type: number
          format: decimal
          description: Sales finalized within the current calendar month.
        balance:
          type: number
          format: decimal
          description: >-
            Outstanding balance across non-succeeded payments on
            finalized/pending invoices.
    Error:
      type: object
      properties:
        detail:
          type: string
          description: Human-readable error message.
      example:
        detail: Authentication credentials were not provided.
  responses:
    Unauthorized:
      description: Authentication credentials missing or invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Forbidden:
      description: The caller is authenticated but not allowed to access this resource.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    TokenAuth:
      type: apiKey
      in: header
      name: Authorization
      description: |
        Use header `Authorization: Token <api_token>`.
        API tokens are obtained from the Piriod dashboard.

````