# List customers

Returns a paginated list of <a href="https://docs.solidgate.com/billing/manage-customers/customers/" target="_blank">customers</a>.

Endpoint: POST /customers/list
Version: 2.0.0
Security: bearerAuth

## Request fields (application/json):

  - `filters` (object)
    Filters for customers.

  - `filters.type` (object)
    Operator and value for customer type filter.

  - `filters.type.operator` (string, required)
    Comparison operator.
    Enum: "EQ"

  - `filters.type.value` (string, required)
    Customer type value to filter by.
    Enum: "INDIVIDUAL", "BUSINESS"

  - `filters.status` (object)
    Operator and value for customer status filter.

  - `filters.status.operator` (string, required)
    Comparison operator.
    Enum: "EQ"

  - `filters.status.value` (string, required)
    Customer status value to filter by.
    Enum: "ACTIVE", "INACTIVE"

  - `filters.email` (object)
    Operator and value for customer email filter.

  - `filters.email.operator` (string, required)
    Comparison operator. `CONTAINS` performs case-insensitive substring search.
    Enum: "CONTAINS"

  - `filters.email.value` (string, required)
    Customer email value to filter by.
    Example: customer@example.com

  - `filters.merchant_customer_id` (object)
    Operator and value for merchant customer identifier filter.

  - `filters.merchant_customer_id.operator` (string, required)
    Comparison operator. Use `EQ` for a single value or `IN` for multiple values.
    Enum: "EQ", "IN"

  - `filters.merchant_customer_id.value` (string, required)
    Single merchant customer identifier for `EQ`, or a comma-separated list of identifiers for `IN`.

  - `pagination` (object)
    Pagination details.

  - `pagination.page_size` (integer, required)
    Number of items returned in this response.
    Example: 20

  - `pagination.next_page_token` (string)
    Token to retrieve the next page of results. It is empty on the last page.
    Example: eyJMYXN0SUQiOiIxYTYyYjQ0Ni01ZDM0LTRiYTQtOGRlZS02NTM5NTU0NjY2MTQifQ==

## Response 200 fields (application/json):

  - `items` (array)
    List of customers for the current page.

  - `items.type` (string, required)
    Customer type.
    Example: INDIVIDUAL

  - `items.business_details` (object)
    Business-specific details for a customer profile.

  - `items.business_details.name` (string)
    Legal business name.
    Example: Acme Corporation

  - `items.business_details.legal_address` (object)
    Registered legal address of the business.

  - `items.business_details.legal_address.city` (string, required)
    City name.
    Example: Anytown

  - `items.business_details.legal_address.country` (string, required)
    Country according to the ISO-3166 alpha-3 country code.
    Enum: "AUS", "BRA", "CAN", "CHN", "IND", "KOR", "MEX", "MYS", "NZL", "USA"

  - `items.business_details.legal_address.line1` (string, required)
    Address line 1.
    Example: 123 Main St

  - `items.business_details.legal_address.line2` (string)
    Address line 2.
    Example: Suite 456

  - `items.business_details.legal_address.state` (string, required)
    State or province.
    Example: CA

  - `items.business_details.legal_address.postal_code` (string, required)
    Postal or ZIP code.
    Example: 12345

  - `pagination` (object)
    Pagination details.

  - `pagination.page_size` (integer, required)
    Number of items returned in this response.
    Example: 20

  - `pagination.next_page_token` (string)
    Token to retrieve the next page of results. It is empty on the last page.
    Example: eyJMYXN0SUQiOiIxYTYyYjQ0Ni01ZDM0LTRiYTQtOGRlZS02NTM5NTU0NjY2MTQifQ==

## Response 400 fields (application/json):

  - `code` (string, required)
    Code identifying the error type.
    Enum: "VALIDATION"

  - `message` (string, required)
    Message describing the error.
    Example: One or more fields failed validation due to constraints

  - `context` (object, required)
    Additional context about the validation error, including specific constraints.
    Example: {"constraints":{"email":{"type":"TYPE","message":"The 'email' field must be a valid email address"},"age":{"type":"MIN","message":"The 'age' field must be a number greater than or equal to 18"}}}

## Response 401 fields (application/json):

  - `code` (string, required)
    Code identifying the error type.
    Enum: "UNAUTHENTICATED"

  - `message` (string, required)
    Message describing the error.
    Example: Credentials are invalid or missing

## Response 403 fields (application/json):

  - `code` (string, required)
    Code identifying the error type.
    Enum: "PERMISSION_DENIED"

  - `message` (string, required)
    Message describing the error.
    Example: Permission denied

## Response 429 fields (application/json):

  - `code` (string, required)
    Code identifying the error type.
    Enum: "RATE_LIMIT"

  - `message` (string, required)
    Message describing the error.
    Example: Rate limit exhausted

  - `context` (object)
    Additional context about the error.

  - `context.next_try_at` (string)
    Timestamp indicating when to retry the request.
    Example: 2024-12-31T23:59:59.000000Z