KYC HTTP API overview

All operations below use the path prefix /v2/admin/kyc. They are exposed by the Integration service and are called with an OAuth client access token (Authorization: Bearer <token>), for example from the client-credentials or resource-owner flow configured for your integration client.

Request and response shapes match the per-operation pages in this section (requires_approval, completed, paginated data / pagination, and so on).

Endpoint index

Area	Method	Path
KYC groups	GET	/v2/admin/kyc/groups
KYC groups	POST	/v2/admin/kyc/groups
KYC groups	GET	/v2/admin/kyc/groups/{groupID}
KYC groups	DELETE	/v2/admin/kyc/groups/{groupID}
Members	GET	/v2/admin/kyc/groups/{groupID}/members
Members	POST	/v2/admin/kyc/groups/{groupID}/members
Members (bulk)	POST	/v2/admin/kyc/groups/{groupID}/members/bulk
Members	DELETE	/v2/admin/kyc/groups/{groupID}/members/{userAddress}
Blacklist (addresses)	GET	/v2/admin/tokens/{tokenID}/kyc/blacklist
Blacklist	POST	/v2/admin/tokens/{tokenID}/kyc/blacklist
Blacklist (bulk)	POST	/v2/admin/tokens/{tokenID}/kyc/blacklist/bulk
Blacklist	DELETE	/v2/admin/tokens/{tokenID}/kyc/blacklist/{userAddress}
Whitelist	GET	/v2/admin/tokens/{tokenID}/kyc/whitelist
Whitelist	POST	/v2/admin/tokens/{tokenID}/kyc/whitelist
Whitelist (bulk)	POST	/v2/admin/tokens/{tokenID}/kyc/whitelist/bulk
Whitelist	DELETE	/v2/admin/tokens/{tokenID}/kyc/whitelist/{userAddress}
Distribution	GET	/v2/admin/tokens/{tokenID}/kyc/distribution
Distribution	POST	/v2/admin/tokens/{tokenID}/kyc/distribution
Distribution (bulk)	POST	/v2/admin/tokens/{tokenID}/kyc/distribution/bulk
Distribution	DELETE	/v2/admin/tokens/{tokenID}/kyc/distribution/{userAddress}
Blacklist groups	GET	/v2/admin/tokens/{tokenID}/kyc/blacklist/groups
Blacklist groups	POST	/v2/admin/tokens/{tokenID}/kyc/blacklist/groups/{groupID}
Blacklist groups	DELETE	/v2/admin/tokens/{tokenID}/kyc/blacklist/groups/{group_id}
Whitelist groups	GET	/v2/admin/tokens/{tokenID}/kyc/whitelist/groups
Whitelist groups	POST	/v2/admin/tokens/{tokenID}/kyc/whitelist/groups/{groupID}
Whitelist groups	DELETE	/v2/admin/tokens/{tokenID}/kyc/whitelist/groups/{group_id}
Token addresses (all types)	GET	/v2/admin/tokens/{tokenID}/kyc/addresses

For bodies, query parameters, examples, and status codes, use the matching topic in this folder (for example Create KYC Group, Add to blacklist, Add multiple members to KYC group).

Notes

• For DELETE on token blacklist or whitelist groups, the last path segment is the KycTokenGroup document id (link between a token and a KYC group), not the KYC group’s own id. Use GET .../blacklist/groups or GET .../whitelist/groups to read that id.
• Wallet addresses in URL paths should be path-encoded when needed.

Asynchronous / blockchain operations

Most mutating KYC endpoints touch the on-chain KYC contracts and therefore run asynchronously through the wallet pipeline. A 2xx response confirms only that the operation was queued — the corresponding node transaction reaches Done later. Each POST / DELETE here writes a row to the node_transactions collection with one of the KYC nodetransaction.Type values below; poll Get Node Transactions for that node to observe completion.

Endpoint family	Node transaction type
POST /groups	41 (CreateKycGroup)
DELETE /groups/{groupID}	42 (DeleteKycGroup)
POST /groups/{groupID}/members	43 (AddMemberToKycGroup)
DELETE /groups/{groupID}/members/{userAddress}	44 (RemoveMemberFromKycGroup)
POST /groups/{groupID}/members/bulk	45 (AddMembersToKycGroup)
POST /tokens/{tokenID}/whitelist	46 (AddMemberToWhitelist)
POST /tokens/{tokenID}/whitelist/bulk	47 (AddMembersToWhitelist)
DELETE /tokens/{tokenID}/whitelist/{userAddress}	48 (RemoveMemberFromWhitelist)
POST /tokens/{tokenID}/blacklist	49 (AddToBlacklistKyc)
POST /tokens/{tokenID}/blacklist/bulk	50 (AddMembersToBlacklist)
DELETE /tokens/{tokenID}/blacklist/{userAddress}	51 (RemoveMemberFromBlacklist)
POST /tokens/{tokenID}/distribution	52 (AddMemberToDistributionGroup)
DELETE /tokens/{tokenID}/distribution/{userAddress}	53 (RemoveMemberFromDistributionGroup)
POST /tokens/{tokenID}/distribution/bulk	54 (AddMembersToDistributionGroup)
POST /tokens/{tokenID}/whitelist/groups/{groupID}	55 (AddKycGroupTokenToWhitelist)
DELETE /tokens/{tokenID}/whitelist/groups/{group_id}	56 (RemoveKycGroupFromWhitelist)
POST /tokens/{tokenID}/blacklist/groups/{groupID}	57 (AddKycGroupToBlacklist)
DELETE /tokens/{tokenID}/blacklist/groups/{group_id}	58 (RemoveKycGroupFromBlacklist)

The KYC GET endpoints (lists, single reads) are synchronous and return the MongoDB-projected view immediately.

Reads of token-scoped lists (/v2/admin/tokens/{tokenID}/kyc/addresses/{whitelist|blacklist|distribution}) may show entries that are still on-chain-pending — they appear in the database as soon as the queued node transaction starts. The per-row status field (when present) and the upstream node-transaction status are the authoritative sources for "is this committed on-chain?".