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

# List customers

> Lists the customers of your organization for the `live` or `test` mode of the API key used. Customers are returned sorted by creation date, with the most recently created customers appearing first. Use `limit` together with the `starting_after` and `ending_before` cursors to paginate the results. The `Link` response header contains the URL of the next page when more results are available.

**`v2`** · Base URL `https://api.fintoc.com/v2`


## OpenAPI

````yaml reference/fintoc-api-v2.json GET /customers
openapi: 3.1.0
info:
  title: fintoc-api-v2
  version: v2026-02-01
servers:
  - url: https://api.fintoc.com/v2
security: []
paths:
  /customers:
    get:
      tags:
        - Customers
      summary: List customers
      description: >-
        Lists the customers of your organization for the `live` or `test` mode
        of the API key used. Customers are returned sorted by creation date,
        with the most recently created customers appearing first. Use `limit`
        together with the `starting_after` and `ending_before` cursors to
        paginate the results. The `Link` response header contains the URL of the
        next page when more results are available.
      operationId: customers-list
      parameters:
        - name: ending_before
          in: query
          required: false
          schema:
            type: string
          description: >-
            Customer `id` cursor for use in pagination. Returns the page of
            results immediately before the customer with this `id`. Cannot be
            combined with `starting_after`.
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            default: 30
          description: >-
            Maximum number of customers to return per page. Defaults to 30, with
            a maximum of 300.
        - name: starting_after
          in: query
          required: false
          schema:
            type: string
          description: >-
            Customer `id` cursor for use in pagination. Returns the page of
            results immediately after the customer with this `id`. Cannot be
            combined with `ending_before`.
        - name: tax_id
          in: query
          required: false
          schema:
            type: string
          description: >-
            Tax identification number to filter by. For `cl_rut`, use a Chilean
            tax ID (RUT) with or without dots and hyphens (for example
            `11.111.111-1` or `111111111`). For `mx_rfc`, use a Mexican tax ID
            (RFC) in any casing. If you do not provide `tax_id_type`, Fintoc
            matches the value against both formats.
        - name: tax_id_type
          in: query
          required: false
          schema:
            type: string
            enum:
              - cl_rut
              - mx_rfc
          description: >-
            Country-specific tax identifier format to filter by. One of `cl_rut`
            for Chilean tax ID (RUT) or `mx_rfc` for Mexican tax ID (RFC). When
            you send `tax_id_type` without `tax_id`, the endpoint returns every
            customer with a tax ID in that format.
      responses:
        '200':
          description: >-
            List of customers for the current mode, sorted by creation date
            (most recent first).
          headers:
            Link:
              schema:
                type: string
              required: false
              description: >-
                Pagination header. Contains the URL of the next page
                (`rel="next"`) when more results are available.
          content:
            application/json:
              examples:
                customers_list:
                  value:
                    - id: cus_0ujsswThIGTUYm2K8FjOOfXtY1K
                      object: customer
                      address:
                        city: Santiago
                        country: cl
                        line1: Av. Providencia 123
                        line2: Depto 45
                        postal_code: '7500000'
                        state: RM
                      created_at: '2026-01-15T14:30:00Z'
                      email: jared@piedpiper.com
                      metadata:
                        order_id: '12345'
                      mode: live
                      name: Test Customer 1
                      phone: '+56911111111'
                      tax_id:
                        type: cl_rut
                        value: '111111111'
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/customer'
        '400':
          description: >-
            Invalid request. Returned when `starting_after` and `ending_before`
            are used together, or when `tax_id_type` is unsupported.
          content:
            application/json:
              examples:
                both_cursors:
                  value:
                    error:
                      type: invalid_params
                      code: invalid_params
                      message: >-
                        Cannot use starting_after and ending_before params at
                        the same time
                unsupported_tax_id_type:
                  value:
                    error:
                      type: invalid_request_error
                      code: invalid_enum
                      param: tax_id_type
                      message: >-
                        Invalid tax_id_type: us_ein. Must be one of 'cl_rut' or
                        'mx_rfc'.
                      doc_url: https://docs.fintoc.com/reference/errors
              schema:
                $ref: '#/components/schemas/error_object'
        '401':
          description: Invalid or missing API key.
          content:
            application/json:
              examples:
                invalid_api_key:
                  value:
                    error:
                      type: authentication_error
                      code: invalid_api_key
                      message: 'Invalid API Key: invalid-*oken'
              schema:
                $ref: '#/components/schemas/error_object'
        '404':
          description: The customer used as pagination cursor does not exist.
          content:
            application/json:
              examples:
                cursor_not_found:
                  value:
                    error:
                      type: missing_cursor
                      code: missing_cursor
                      message: Cursor cus_0ujsswThIGTUYm2K8FjOOfXtY1K not found
              schema:
                $ref: '#/components/schemas/error_object'
      security:
        - api_key: []
components:
  schemas:
    customer:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier of the customer.
          example: cus_0ujsswThIGTUYm2K8FjOOfXtY1K
        object:
          const: customer
          description: Type of the object. Always `customer`.
        address:
          type:
            - object
            - 'null'
          description: >-
            Customer's address. Only the fields with a value are returned.
            `null` when the customer has no address information.
          properties:
            city:
              type: string
              description: City.
              example: Santiago
            country:
              type: string
              description: Two-letter country code (ISO 3166-1 alpha-2), in lowercase.
              example: cl
            line1:
              type: string
              description: Primary address line.
              example: Av. Providencia 123
            line2:
              type: string
              description: Secondary address line.
              example: Depto 45
            postal_code:
              type: string
              description: Postal or ZIP code.
              example: '7500000'
            state:
              type: string
              description: State or region.
              example: RM
        created_at:
          type: string
          format: date-time
          description: ISO 8601 datetime, in UTC, of when the customer was created.
          example: '2026-01-15T14:30:00Z'
        email:
          type:
            - string
            - 'null'
          description: Customer's email, stored in lowercase. `null` if not provided.
          example: jared@piedpiper.com
        metadata:
          type: object
          description: >-
            Set of key-value pairs that you can attach to an object. Useful for
            storing additional information about the object in a structured
            format.
          example:
            order_id: '12345'
        mode:
          type: string
          enum:
            - live
            - test
          description: >-
            Mode of the customer, matching the mode of the API key used to
            create it. One of `live` or `test`.
          example: live
        name:
          type:
            - string
            - 'null'
          description: Customer's full name or business name. `null` if not provided.
          example: Test Customer 1
        phone:
          type:
            - string
            - 'null'
          description: >-
            Customer's phone number in E.164 format, including the country code
            (for example `+56911111111`). `null` if not provided.
          example: '+56911111111'
        tax_id:
          type:
            - object
            - 'null'
          description: >-
            Tax identifier of the customer (Chilean RUT or Mexican RFC). `null`
            if not provided.
          properties:
            type:
              type: string
              enum:
                - cl_rut
                - mx_rfc
              description: >-
                Type of tax identifier. One of `cl_rut` (Chilean RUT) or
                `mx_rfc` (Mexican RFC).
              example: cl_rut
            value:
              type: string
              description: >-
                Value of the tax identifier, normalized. RUTs are stored without
                dots or hyphens, and RFCs are stored in uppercase.
              example: '111111111'
          required:
            - type
            - value
      required:
        - id
        - object
        - address
        - created_at
        - email
        - metadata
        - mode
        - name
        - phone
        - tax_id
    error_object:
      type: object
      properties:
        error:
          type: object
          description: Details of the error that caused the request to fail.
          properties:
            code:
              type: string
              description: >-
                Machine-readable code identifying the specific error, for
                example `invalid_api_key`. Not returned by every error.
              example: invalid_api_key
            doc_url:
              type: string
              description: >-
                URL of a documentation page with more details about the error.
                Not returned by every error.
              example: https://docs.fintoc.com/reference/errors
            message:
              type: string
              description: Human-readable message describing the error.
              example: 'Invalid API Key: invalid-*oken'
            param:
              type:
                - string
                - 'null'
              description: >-
                Name of the request parameter that caused the error. `null` when
                the error cannot be tied to a single parameter, and not returned
                by every error.
              example: amount
            type:
              type: string
              description: >-
                Category of the error, for example `invalid_request_error`,
                `authentication_error`, or `api_error`.
              example: invalid_request_error
          required:
            - type
            - message
  securitySchemes:
    api_key:
      type: apiKey
      name: Authorization
      in: header

````