List Customers

The workspace's customers, a page at a time, newest first unless you choose another order. v3 calls an account a customer (cst_…); v2 called it an account.

Takes a workspace-scoped API key or a dashboard session. An account-scoped key is refused with 401.

Replaces GET /api/v2/accounts.

Authorization:

Every request is signed with your API key: a short-lived JWT, signed with your private key, sent in one header on /v3/* and /api/v2/* alike.

Headers:
  Authorization: APIKey {SIGNED_JWT}

How to build and sign the JWT: Authentication.

Endpoint

GET

/v3/customers

Query parameters

Parameter	Type	Description
`page`	integer	Page number, from 1. Default `1`.
`limit`	integer	Items per page. Default `25`. A value over `100` is read as `100`, and the response's `limit` says what was used. See Lists.
`q`	string	Free-text search, at least 3 characters. Matches name, email, reference and id. A full customer id (`cst_…` or its UUID) matches that customer exactly.
`customer_type`	string	Only `individual` or only `business` customers.
`verification_status`	string	Only customers in this verification bucket: `incomplete`, `pending`, `approved` or `failed`. See the response schema.
`created_at_gte`	string	Created at or after this instant (RFC 3339, e.g. `2026-01-01T00:00:00Z`). A bare date (`2026-01-01`) is read as midnight UTC.
`created_at_lt`	string	Created before this instant. Same format as `created_at_gte`.
`sort`	string	Comma-separated fields, most significant first, `-` for descending: `-created_at`, `name`, `status,-created_at`. Orderable fields: `name`, `email`, `customer_type`, `status`, `created_at`. At most three, each once. Default `-created_at`.

Response Sample

{
  "data": [
    {
      "id": "cst_01k8x42qwge80v7at8esvk9ny1",
      "reference": "019a3a41-5f90-7201-b3ab-48767734d7c1",
      "name": "Marcus Chen",
      "email": "marcus.chen@example.com",
      "customer_type": "individual",
      "status": "pending",
      "verification_status": "incomplete",
      "created_at": "2025-10-31T12:32:34Z",
      "updated_at": "2025-10-31T12:32:34Z"
    },
    {
      "id": "cst_01k8x40x9gfx6sv8a99hswy9bd",
      "reference": "019a3a40-7530-7f4d-9da1-494c73cf256d",
      "name": "Samantha Reyes",
      "email": "samantha@example.com",
      "customer_type": "individual",
      "status": "active",
      "phone": "+14155550123",
      "verification_status": "approved",
      "created_at": "2025-10-31T12:31:34Z",
      "updated_at": "2025-11-02T09:14:05Z"
    },
    {
      "id": "cst_01k8x404w8ezyts68ghqdnpqxb",
      "reference": "client-reference-123",
      "name": "Northwind Traders LLC",
      "email": "finance@northwind.example",
      "customer_type": "business",
      "status": "pending",
      "verification_status": "pending",
      "frozen_at": "2025-11-05T16:20:00Z",
      "created_at": "2025-10-31T12:31:09Z",
      "updated_at": "2025-11-05T16:20:00Z"
    }
  ],
  "page": 1,
  "limit": 25,
  "total_items": 3,
  "total_pages": 1
}

Response Schema

The list envelope (see API v3 overview), without the cursor fields. Each item in data:

Field	Type	Description
`id`	string (`cst_…`)	The customer. v2's account `id`, as a TypeID.
`reference`	string	v2's `reference`. A customer created in v3 gets its id's UUID here.
`name`	string	Name. v2's `accountName`.
`email`	string	Email.
`customer_type`	string	`individual` or `business`.
`status`	string	Account lifecycle: `pending`, `active` or `closed`.
`phone`	string	Phone from the customer's verification record. Omitted when there is none.
`verification_status`	string	Where the customer's verification stands (a KYC record for an individual, KYB for a business): `incomplete` (no record yet, sent back for changes, or a business record `ready_for_review`), `pending` (open or under review), `approved`, `failed` (rejected).
`blocked_at`	string (RFC 3339)	When the customer was blocked. Omitted unless blocked.
`frozen_at`	string (RFC 3339)	When the customer was frozen (no outgoing transactions). Omitted unless frozen.
`created_at`	string (RFC 3339)	When the customer was created.
`updated_at`	string (RFC 3339)	When it last changed.

Errors

Status	`message`	When
`400`	`invalid_sort`	`sort` names a field that cannot be ordered by, repeats one, or has more than three.
`400`	`failed to parse request`	`customer_type` or `verification_status` is not one of its values, or a `created_at_*` value is not a date.
`401`	`unauthorized`	Missing or invalid signature, or the caller is an account-scoped key or a customer session.
`403`	`forbidden`	A dashboard member whose role does not allow this. A workspace-scoped key always may.
`422`	`Validation failed`	`q` is shorter than 3 characters; `details` names it.

Coming from v2

v2 (`GET /api/v2/accounts`)	v3
`limit` default 100, no cap	`limit` default 25, capped at 100
`search`	`q` (also matches reference and id)
`status` filter	none; filter by `verification_status`, `customer_type` or creation date instead
`total`	`total_items` and `total_pages`
`id` (uuid)	`id` (`cst_…`)
`accountType`, `accountName`	`customer_type`, `name`
`firstName`, `lastName`	not returned
`createdAt`, `updatedAt`	`created_at`, `updated_at`
none	`verification_status`, `phone`, `blocked_at`, `frozen_at`, `sort`

Support and Resources

If you need assistance or have any questions, our support team is here to help. You can contact our support team at support@blockwyre.com.

Stay Updated

Stay up-to-date with the latest news, updates, and features from BlockWyre by following us on social media:

Instagram: BlockWyre Instagram
Twitter: BlockWyre Twitter
Facebook: BlockWyre Facebook
LinkedIn: BlockWyre LinkedIn

We are excited to have you on board and look forward to seeing how you leverage BlockWyre's powerful tools to enhance your financial operations. Happy integrating!

Endpoint

Query parameters​

Response Sample​

Response Schema​

Errors​

Coming from v2​

Support and Resources​

Stay Updated​