## 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

- `created_from: optional string`

  Start date for filtering by `created_at` date.

- `created_to: optional string`

  End date for filtering by `created_at` date.

- `email: optional string`

  Filter customers by `email` address.

- `external_id: optional string`

  Filter by your system's `external_id`.

- `name: optional string`

  Filter customers by `name` (partial match).

- `page_number: optional number`

  Page number for paginated results. Starts at 1.

- `page_size: optional number`

  Number of results per page. Maximum: 1000.

- `search_text: optional string`

  General search term to filter customers.

- `sort_by: optional "name" or "created_at"`

  - `"name"`

  - `"created_at"`

- `sort_order: optional "asc" or "desc"`

  - `"asc"`

  - `"desc"`

- `status: optional array of "pending" or "review" or "verified" or 2 more`

  Filter customers by their current `status`.

  - `"pending"`

  - `"review"`

  - `"verified"`

  - `"inactive"`

  - `"rejected"`

- `types: optional array of "individual" or "business"`

  Filter by customer type `individual` or `business`.

  - `"individual"`

  - `"business"`

### Header Parameters

- `"Correlation-Id": optional string`

- `"Request-Id": optional string`

- `"Straddle-Account-Id": optional string`

### Returns

- `CustomerSummaryPagedV1 = object { data, meta, response_type }`

  - `data: array of object { id, created_at, email, 6 more }`

    - `id: string`

      Unique identifier for the customer.

    - `created_at: string`

      Timestamp of when the customer record was created.

    - `email: string`

      The customer's email address.

    - `name: string`

      Full name of the individual or business name.

    - `phone: string`

      The customer's phone number in E.164 format.

    - `status: "pending" or "review" or "verified" or 2 more`

      - `"pending"`

      - `"review"`

      - `"verified"`

      - `"inactive"`

      - `"rejected"`

    - `type: "individual" or "business"`

      - `"individual"`

      - `"business"`

    - `updated_at: string`

      Timestamp of the most recent update to the customer record.

    - `external_id: optional string`

      Unique identifier for the customer in your database, used for cross-referencing between Straddle and your systems.

  - `meta: object { api_request_id, api_request_timestamp, max_page_size, 6 more }`

    - `api_request_id: string`

      Unique identifier for this API request, useful for troubleshooting.

    - `api_request_timestamp: string`

      Timestamp for this API request, useful for troubleshooting.

    - `max_page_size: number`

      Maximum allowed page size for this endpoint.

    - `page_number: number`

      Page number for paginated results.

    - `page_size: number`

      Number of items per page in this response.

    - `sort_by: string`

      The field that the results were sorted by.

    - `sort_order: "asc" or "desc"`

      - `"asc"`

      - `"desc"`

    - `total_items: number`

    - `total_pages: number`

      The number of pages available.

  - `response_type: "object" or "array" or "error" or "none"`

    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.

    - `"object"`

    - `"array"`

    - `"error"`

    - `"none"`

### Example

```http
curl https://sandbox.straddle.com/v1/customers \
    -H "Authorization: Bearer $STRADDLE_API_KEY"
```

#### Response

```json
{
  "data": [
    {
      "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
      "created_at": "2019-12-27T18:11:19.117Z",
      "email": "dev@stainless.com",
      "name": "name",
      "phone": "+46991022",
      "status": "pending",
      "type": "individual",
      "updated_at": "2019-12-27T18:11:19.117Z",
      "external_id": "external_id"
    }
  ],
  "meta": {
    "api_request_id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
    "api_request_timestamp": "2019-12-27T18:11:19.117Z",
    "max_page_size": 0,
    "page_number": 0,
    "page_size": 0,
    "sort_by": "sort_by",
    "sort_order": "asc",
    "total_items": 0,
    "total_pages": 0
  },
  "response_type": "object"
}
```