---
title: "List customers"
method: GET
path: "/v1/customers"
tags: ["Customers"]
---

# List customers

`GET /v1/customers`

Lists or searches customers connected to your account. All supported query parameters are optional. If none are provided, the response will include all customers connected to your account. This endpoint supports advanced sorting and filtering options.

## Query parameters

- `page_number` integer — Page number for paginated results. Starts at 1.
- `page_size` integer — Number of results per page. Maximum: 1000.
- `sort_by` 'name' | 'created_at'
- `sort_order` 'asc' | 'desc'
- `created_from` string, date-time — Start date for filtering by `created_at` date.
- `created_to` string, date-time — End date for filtering by `created_at` date.
- `name` string — Filter customers by `name` (partial match).
- `external_id` string — Filter by your system's `external_id`.
- `email` string — Filter customers by `email` address.
- `status` CustomerStatusV1[] — Filter customers by their current `status`.
- `search_text` string — General search term to filter customers.
- `types` CustomerTypeV1[] — Filter by customer type `individual` or `business`.

## Headers

- `Straddle-Account-Id` string, uuid
- `Request-Id` string
- `Correlation-Id` string

## Response `200`

OK

- CustomerSummaryV1PagedResponse
  - `meta` PagedResponseMetadata1, required
    - `api_request_id` string, uuid, required — Unique identifier for this API request, useful for troubleshooting.
    - `api_request_timestamp` string, date-time, required — Timestamp for this API request, useful for troubleshooting.
    - `total_items` integer, required
    - `page_number` integer, required — Page number for paginated results.
    - `page_size` integer, required — Number of items per page in this response.
    - `max_page_size` integer, required — Maximum allowed page size for this endpoint.
    - `sort_by` string, required — The field that the results were sorted by.
    - `sort_order` 'asc' | 'desc', required
    - `total_pages` integer, required — The number of pages available.
  - `response_type` 'object' | 'array' | 'error' | 'none', required — Indicates the structure of the returned content. - "object" means the `data` field contains a single JSON object. - "array" means the `data` field contains an array of objects. - "error" means the `data` field contains an error object with details of the issue. - "none" means no data is returned.
  - `data` CustomerSummaryV1[], required
    - `id` string, uuid, required — Unique identifier for the customer.
    - `name` string, required — Full name of the individual or business name.
    - `type` 'individual' | 'business', required
    - `email` string, email, required — The customer's email address.
    - `phone` string, required — The customer's phone number in E.164 format.
    - `external_id` string, nullable — Unique identifier for the customer in your database, used for cross-referencing between Straddle and your systems.
    - `status` 'pending' | 'review' | 'verified' | 'inactive' | 'rejected', required
    - `created_at` string, date-time, required — Timestamp of when the customer record was created.
    - `updated_at` string, date-time, required — Timestamp of the most recent update to the customer record.

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `403` — Forbidden
- `404` — Not Found
- `422` — Validation Failed
- `500` — Server Error

---

[API](https://skmtc.net/straddleio/apis/straddle-api.md) · [All operations](https://skmtc.net/straddleio/apis/straddle-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/straddleio/straddle-api/versions/6e13cd88cda9/schema)