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/kyc/tokens/{tokenID}/blacklist
Blacklist	POST	/v2/admin/kyc/tokens/{tokenID}/blacklist
Blacklist (bulk)	POST	/v2/admin/kyc/tokens/{tokenID}/blacklist/bulk
Blacklist	DELETE	/v2/admin/kyc/tokens/{tokenID}/blacklist/{userAddress}
Whitelist	GET	/v2/admin/kyc/tokens/{tokenID}/whitelist
Whitelist	POST	/v2/admin/kyc/tokens/{tokenID}/whitelist
Whitelist (bulk)	POST	/v2/admin/kyc/tokens/{tokenID}/whitelist/bulk
Whitelist	DELETE	/v2/admin/kyc/tokens/{tokenID}/whitelist/{userAddress}
Distribution	GET	/v2/admin/kyc/tokens/{tokenID}/distribution
Distribution	POST	/v2/admin/kyc/tokens/{tokenID}/distribution
Distribution (bulk)	POST	/v2/admin/kyc/tokens/{tokenID}/distribution/bulk
Distribution	DELETE	/v2/admin/kyc/tokens/{tokenID}/distribution/{userAddress}
Blacklist groups	GET	/v2/admin/kyc/tokens/{tokenID}/blacklist/groups
Blacklist groups	POST	/v2/admin/kyc/tokens/{tokenID}/blacklist/groups/{groupID}
Blacklist groups	DELETE	/v2/admin/kyc/tokens/{tokenID}/blacklist/groups/{kycTokenGroupID}
Whitelist groups	GET	/v2/admin/kyc/tokens/{tokenID}/whitelist/groups
Whitelist groups	POST	/v2/admin/kyc/tokens/{tokenID}/whitelist/groups/{groupID}
Whitelist groups	DELETE	/v2/admin/kyc/tokens/{tokenID}/whitelist/groups/{kycTokenGroupID}
Token addresses (all types)	GET	/v2/admin/kyc/tokens/{tokenID}

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/{kycTokenGroupID}	56 (RemoveKycGroupFromWhitelist)
POST /tokens/{tokenID}/blacklist/groups/{groupID}	57 (AddKycGroupToBlacklist)
DELETE /tokens/{tokenID}/blacklist/groups/{kycTokenGroupID}	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/kyc/tokens/{tokenID}/{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?".