---
title: "List clients"
method: GET
path: "/clients"
tags: ["accounts"]
---

# List clients

`GET /clients`

## Request

- The document declares no server URL.
- Auth: HTTP bearer

Every account connected to you, newest first.

## Query parameters

- `email` string, email, nullable: Exact match, lowercased.
- `status` 'provisioning' | 'ready' | 'failed'
- `limit` integer
- `cursor` string, nullable

## Headers

- `X-Hevn-Account` string, nullable: The client account to act for, as a `cl_…` id. Omit it to act as yourself.

## Response `200`

Successful Response

- PageClientResponse
  - `items` ClientResponse[], required: Resources in this page, in stable server-defined order.
    - `id` string, required: Stable public identifier for this account.
    - `status` 'provisioning' | 'ready' | 'failed', required
    - `name` string, nullable: Legal or trading name of the account.
    - `email` string, nullable: Email address associated with the account.
    - `phone` string, nullable: Phone number in international E.164 format.
    - `baseSmartWallet` string, nullable: Base smart-wallet address controlled by the account.
    - `kybStatus` 'notStarted' | 'pending' | 'approved' | 'rfi' | 'rejected'
    - `kybApplicationId` string, nullable: Latest immutable business-verification application identifier.
    - `verifiedAt` string, date-time, nullable: When the account was verified: identity verification for a person, KYB for a business.
    - `createdAt` string, date-time, required: UTC timestamp when the account was created.
    - `failure` ClientFailureResponse
      - `code` 'provisioning_failed' | 'request_rejected' | 'request_canceled', required
      - `message` string, required: Human-readable explanation safe to show to the account holder.
      - `retriable` boolean: Whether retrying later without changing the request may succeed.
    - `pollUrl` string, nullable: Relative API URL to poll with this response's id in `X-Hevn-Account`.
    - `transferPolicy` TransferPolicyResponse: Effective account-level money-movement controls. ``isFrozen`` overrides every permission. When the account is not frozen, ``recoveryModeActivated`` restricts it to first-party fiat withdrawals. The remaining flags are then evaluated for the requested operation.
      - `allowFiat` boolean, required: Allow account-initiated fiat payouts, subject to freeze and recovery controls.
      - `allowCrypto` boolean, required: Allow account-initiated on-chain transfers, including transfers to another platform account, subject to freeze and recovery controls.
      - `allowThirdParty` boolean, required: Allow fiat or on-chain payouts to an external contact. Email and escrow payments within the same platform group use narrower controls.
      - `allowEscrowThirdParty` boolean, required: Allow escrow to another platform account. This control is independent from allowThirdParty; same-group escrow also requires allowPartnerGroupPayments.
      - `allowSwap` boolean, required: Allow balance swaps, subject to freeze and recovery controls.
      - `allowPartnerGroupPayments` boolean, required: Allow email and escrow payments between accounts in the same platform group. Email payments also require allowCrypto; escrow also requires allowEscrowThirdParty.
      - `dualApproval` boolean, required: Require a separately approved transfer request before payment co-signing.
      - `isFrozen` boolean, required: Block every new money movement, overriding every allow flag.
      - `recoveryModeActivated` boolean, required: Restrict money movement to first-party fiat payouts whose Contact belongs to this account and whose account-holder name matches the account name.
  - `nextCursor` string, nullable: Opaque cursor for the next page; absent when this is the final page.

## Other responses

- `422`: Request validation failed

## Changes

- **2026-11-12** `299a3aa6f521`: 1 warning, 3 info
  - added the new `verification_not_applicable` enum value to the `error/code` response property for the response status `422`
  - added the optional property `items/items/verifiedAt` to the response with the `200` status
  - removed the `phone_required` enum value from the `error/code` response property for the response status `422`
  - removed the `rail_requirements_unmet` enum value from the `error/code` response property for the response status `422`
- **2026-10-23** `a02795de2d2b`: 9 warning, 6 info
  - deleted the `header` request parameter `x-api-key`
  - added the new `client_already_linked` enum value to the `error/code` response property for the response status `422`
  - added the new `kyb_documents_processing` enum value to the `error/code` response property for the response status `422`
  - added the new `link_code_expired` enum value to the `error/code` response property for the response status `422`
  - …11 more
- **2026-10-20** `19eb00e9f258`: 1 info
  - removed the `phone_in_use` enum value from the `error/code` response property for the response status `422`
- **2026-10-20** `bd6c9d69540e`: 1 warning
  - added the new `phone_in_use` enum value to the `error/code` response property for the response status `422`
- **2026-10-20** `19eb00e9f258`: 1 info
  - removed the `document_fields_missing` enum value from the `error/code` response property for the response status `422`

[Operation history](https://skmtc.dev/hevn-inc/apis/hevn-api/changes/clients/get.md)

---

[API](https://skmtc.dev/hevn-inc/apis/hevn-api.md) - [All operations](https://skmtc.dev/hevn-inc/apis/hevn-api/llms.txt) - [OpenAPI document](https://skmtc.dev/hevn-inc/apis/hevn-api/revisions/299a3aa6f521?raw)