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

# List customers

> List customers associated with a corporation.

Retrieves a paginated list of customers for a corporation with optional filtering and search capabilities.

## Query parameters

<ParamField query="corporation_id" type="string" required>
  The unique identifier for the corporation
</ParamField>

<ParamField query="cursor" type="string">
  Pagination cursor for fetching the next page of results
</ParamField>

<ParamField query="limit" type="int32" default="10">
  Maximum number of customers to return (max: 100)
</ParamField>

<ParamField query="name" type="string">
  Filter customers by exact name match
</ParamField>

<ParamField query="search_term" type="string">
  Search customers by name (partial match)
</ParamField>

<ParamField query="source_platforms" type="string">
  Comma-separated list of source platforms to filter by
</ParamField>

<ParamField query="source_platform_ids" type="string">
  Comma-separated list of source platform IDs to filter by
</ParamField>

<ParamField query="extend" type="string">
  Comma-separated list of fields to include in response. Options: `shipping_address`, `exemption_metadata`
</ParamField>

### Exemption filters

<ParamField query="certificate_types" type="string">
  Comma-separated list of certificate types to filter by
</ParamField>

<ParamField query="exemption_jurisdiction" type="string">
  Filter by exemption jurisdiction
</ParamField>

<ParamField query="expiration_status" type="string">
  Filter by certificate expiration status
</ParamField>

<ParamField query="exemption_status" type="string">
  Filter by exemption status
</ParamField>

<ParamField query="has_exemption" type="boolean">
  Filter customers by whether they have exemptions
</ParamField>

## Response

<ResponseField name="customers" type="array">
  Array of customer objects

  <Expandable title="customer properties">
    <ResponseField name="id" type="string">
      Unique identifier for the customer
    </ResponseField>

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

    <ResponseField name="email" type="string">
      Customer email address
    </ResponseField>

    <ResponseField name="corporation_id" type="string">
      The corporation ID this customer belongs to
    </ResponseField>

    <ResponseField name="created_at" type="int64">
      Unix timestamp of when the customer was created
    </ResponseField>

    <ResponseField name="source_platform_id" type="string">
      Source platform identifier (if applicable)
    </ResponseField>

    <ResponseField name="source_platform" type="string">
      Source platform name (if applicable)
    </ResponseField>

    <ResponseField name="business_identification_number" type="string">
      The customer's tax or business registration number, if provided
    </ResponseField>

    <ResponseField name="shipping_address" type="object">
      Customer's shipping address (included when `extend=shipping_address`)

      <Expandable title="shipping_address properties">
        <ResponseField name="line1" type="string">
          Street address line 1
        </ResponseField>

        <ResponseField name="line2" type="string">
          Street address line 2
        </ResponseField>

        <ResponseField name="city" type="string">
          City name
        </ResponseField>

        <ResponseField name="state" type="string">
          State or province code
        </ResponseField>

        <ResponseField name="postal_code" type="string">
          Postal or ZIP code
        </ResponseField>

        <ResponseField name="country" type="string">
          ISO 3166 2-letter country code
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="exemption_metadata" type="object">
      Exemption information (included when `extend=exemption_metadata`)
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="total_customers" type="int64">
  Total number of customers matching the query
</ResponseField>

<ResponseField name="cursor" type="string">
  Pagination cursor for the next page (if more results exist)
</ResponseField>

<RequestExample>
  ```bash theme={null}
  GET /customers?corporation_id=corp_123&limit=20&extend=shipping_address&search_term=acme
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "customers": [
      {
        "id": "cust_789",
        "name": "Acme Corporation",
        "email": "contact@acme.com",
        "corporation_id": "corp_123",
        "created_at": 1706000000,
        "shipping_address": {
          "line1": "123 Main St",
          "city": "San Francisco",
          "state": "CA",
          "postal_code": "94105",
          "country": "US"
        }
      }
    ],
    "total_customers": 1,
    "cursor": null
  }
  ```
</ResponseExample>


## OpenAPI

````yaml GET /customers
openapi: 3.0.1
info:
  title: Commenda Public APIs
  description: >-
    APIs for Commenda entity management, partner incorporation, indirect tax,
    compliance, and corporate operations.
  license:
    name: NONE
    url: NONE
  version: 1.0.0
servers:
  - url: https://api.prod.commenda.io/api/v1
    description: Commenda platform APIs, including Partner Incorporation and Commenda OS.
  - url: https://transaction-tax.api.in.commenda.io/api/v1
    description: Global Indirect Tax API.
security:
  - bearerAuth: []
paths:
  /customers:
    get:
      summary: List customers
      description: List customers associated with a corporation.
      operationId: listCustomers
      parameters:
        - name: corporation_id
          in: query
          description: >-
            The unique identifier for a corporation used to filter the relevant
            customer base.
          required: true
          schema:
            type: string
        - name: cursor
          in: query
          description: Cursor for pagination
          required: false
          schema:
            type: string
        - name: limit
          in: query
          description: Number of items to return per page
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 10
      responses:
        '200':
          description: List of customers associated with the requesting corporation
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/GetAllCustomersByCorporation'
                  message:
                    type: string
                    example: Successfully fetched customers.
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    GetAllCustomersByCorporation:
      type: object
      properties:
        customers:
          type: array
          items:
            $ref: '#/components/schemas/CustomerExtended'
        total_customers:
          type: integer
          description: Total number of customers associated with the corporation.
        cursor:
          type: string
          description: Pagination cursor for the next set of results.
    Error:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          properties:
            type:
              type: string
              description: 'Specific Error type. Example: CLIENT_INVALID_REQUEST_BODY.'
              example: CLIENT_INVALID_REQUEST_BODY
            doc_url:
              type: string
              description: >-
                A link to the docs with details about this error. Example:
                https://sales-tax-docs.commenda.io/
              example: https://sales-tax-docs.commenda.io/
            title:
              type: string
              description: >-
                A short title describing the error. Example: Missing query
                parameters.
              example: Failed to validate the request body
            detail:
              type: string
              description: >-
                A json string with a description on how to fix the error.
                Example {"description":"Please pass in a valid corporation_id"}
            status:
              type: number
              description: >-
                The status code. It should be the same as the HTTP protocol
                status code. Example: 200
              example: 400
            instance:
              type: string
              description: >-
                The relative path that was hit by the user. Example:
                /api/v1/corporations/1
            Errors:
              type: array
              items:
                type: object
                properties:
                  details:
                    type: string
                    description: More details on how to solve this particular error.
                  pointer:
                    type: string
                    description: >-
                      Relative reference to missing or invalid piece of passed
                      information.
    CustomerExtended:
      allOf:
        - $ref: '#/components/schemas/CustomerInfo'
        - type: object
          properties:
            exemption_metadata:
              $ref: '#/components/schemas/ExemptionMetadata'
    CustomerInfo:
      type: object
      properties:
        id:
          type: string
          description: The unique identifier for this customer.
          example: b6d009b0-d174-463f-b030-94643c28e209
        corporation_id:
          type: string
          description: >-
            The unique identifier for the corporation associated with this
            customer.
          example: 2535af08-a139-4d0c-9827-1651e46dfbcf
        name:
          type: string
          description: A display name for this customer.
          example: John Doe
        email:
          type: string
          description: Email address of the customer.
          format: email
        shipping_address:
          $ref: '#/components/schemas/Address'
        external_id:
          type: string
          description: External identifier for the customer.
        business_identification_number:
          type: string
          description: >-
            Business identification number for the customer (e.g., tax ID, VAT
            number, or EIN).
    ExemptionMetadata:
      type: object
      properties:
        total_certificates:
          type: integer
          description: Total number of exemption certificates for this customer
        certificate_types:
          type: array
          items:
            type: string
          description: List of unique certificate types held by this customer
        total_exempted_states:
          type: integer
          description: Total number of states where the customer has exemptions
        expired_exemptions_count:
          type: integer
          description: Number of expired exemption certificates
        inactive_exemptions_count:
          type: integer
          description: Number of inactive exemption certificates
        exempted_states:
          type: array
          items:
            type: string
          description: List of states where the customer has exemptions
        active_exemptions_count:
          type: integer
          description: Number of active exemption certificates
        non_expired_exemptions_count:
          type: integer
          description: Number of non-expired exemption certificates
    Address:
      type: object
      required:
        - country
      description: >
        Address object. Only `country` is required at the schema level. All
        other field requirements (including `postal_code` and `state`) vary by
        country — use the `/address-requirements` endpoint to check which fields
        are REQUIRED, OPTIONAL, or IGNORED for a given country. When provided,
        postal codes and state codes are validated against country-specific
        formats and allowed values.
      properties:
        address_line_1:
          type: string
          example: 1776 Main St
          description: Primary street address. Required for some countries (e.g., US).
        address_line_2:
          type: string
          example: 'Apt. #123'
          description: >-
            Secondary address line (apartment, suite, etc.). Optional for most
            countries.
        address_line_3:
          type: string
          description: Tertiary address line. Ignored for most countries.
        postal_code:
          type: string
          description: >
            Postal or ZIP code. Required for many countries (e.g., US, GB, DE,
            FR) and optional for others (e.g., CA). Format varies by country.
            For US addresses, either 5-digit ZIP or 9-digit ZIP+4 is accepted.
            Use the `/address-requirements` endpoint to check whether this field
            is required and to get the validation regex for each country.
          example: '90401'
        city:
          type: string
          example: Santa Monica
          description: City name. Required for some countries (e.g., US).
        state:
          $ref: '#/components/schemas/State'
          description: >
            State or province code. Required for some countries (e.g., US) and
            optional for others (e.g., GB, DE). Must be a valid ISO 3166-2
            subdivision code for the given country when provided. Use the
            `/address-requirements` endpoint to check whether this field is
            required and to get the list of valid state codes for each country.
        country:
          $ref: '#/components/schemas/Country'
    State:
      type: string
      example: CA
      description: >-
        2-letter code for each state. Suffix of the ISO 3166-2 code. Ex: CA, NY,
        TX.
    Country:
      type: string
      example: US
      description: 'ISO 3166 2-letter country code. Ex: US, IN, GB.'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````