List KYC Groups

Lists the KYC groups that live on one KYC token, newest first. The KYC token itself is not looked up: an id that names no KYC token returns an empty page.

A group appears as soon as its creation is accepted (and stays if the on-chain creation fails), and leaves once its deletion is confirmed. Only the platform owner (root) node may call it.

Required permission: kyc:group:view

Request

GET /v2/admin/kycs/{kyc_token_id}/groups

Parameters

Name	Type	In	Description
kyc_token_id	string	path	Required. The KYC token's id, from List KYC Tokens
search	string	query	Optional. Part of a group name; matches ignoring letter case
page	integer	query	Required. Page number, starting at 1
per_page	integer	query	Required. Items per page, 1–100

Headers

Name	Description
Authorization	Required. Bearer <access_token>

Example

curl --request GET \
  --url '{{baseUrl}}/v2/admin/kycs/68c4a1f2b9e3d70012a5c3e8/groups?page=1&per_page=10' \
  --header 'Authorization: Bearer <access_token>'

Response

Status 200.

{
  "data": [
    {
      "id": "68d2e7a9c1b4f30045e1a9b2",
      "kyc_token_id": "68c4a1f2b9e3d70012a5c3e8",
      "group_id": 12,
      "name": "Accredited Investors",
      "created_at": "2026-10-02T09:14:31.512Z",
      "updated_at": "2026-10-02T09:14:31.512Z"
    }
  ],
  "total": 1,
  "page": 1,
  "per_page": 10
}

Response Fields

Field	Type	Description
data	array	The groups on this page, newest first
data[].id	string	The group's id. Every path and every token rule uses this value
data[].kyc_token_id	string	The KYC token the group lives on. Absent on groups created before groups were tied to a KYC token
data[].group_id	integer	The group's number on chain; unique across the platform
data[].name	string	The group's name
data[].created_at	string	When the group was created (ISO 8601)
data[].updated_at	string	When the group last changed (ISO 8601)
total	integer	Items matching the filters
page	integer	Page number
per_page	integer	Page size

Errors

Status	Code	Description
400	10015	Validation failed — see details
400	10016	kyc_token_id is not a valid id
403	10005 (domain 2)	Your node is not the platform owner (root) node

See Errors for the error format and common codes.