Browse the docs

Get cardholder KYC status by cardholder id

GET /v2/api-gateway/cardholders/{id}/kyc

Returns the KYC status of the cardholder. 404 when the cardholder has never started KYC (no kyc-link created yet).

Request

Authentication: your API key in the x-api-key header.

Path parameters

Field	Type	Description
`id` required	string, uuid	The Moon cardholder id (`id`, a UUID), not your `external_id`.

Example request

cURL

curl --request GET \
     --url 'https://api.themooncard.com/v2/api-gateway/cardholders/3f5b1c2e-8d4a-4b6f-9e2a-1c7d8e9f0a1b/kyc' \
     --header 'x-api-key: YOUR_API_KEY'

Responses

200 Success

Field	Type	Description
`status` required	string	Current KYC status, e.g. `NOT_STARTED`, `IN_REVIEW`, `APPROVED`, `DECLINED`, `RETRY`.
`url` required	string, nullable	Hosted verification URL last issued for this cardholder, or null.
`created_at` required	string	ISO-8601 timestamp.
`updated_at` required	string	ISO-8601 timestamp.

JSON

{
  "status": "APPROVED",
  "url": "https://verify.paywithmoon.com/kyc?token=eyJhbGciOiJIUzI1NiJ9.xyz789",
  "created_at": "2026-08-01T09:12:44.000Z",
  "updated_at": "2026-08-02T14:20:05.000Z"
}

400 Error

Validation failed (errors[] lists each offending field) or a domain rule rejected the request ({ message, code }).

The body is the standard error object: see Errors.

401 Error

Missing or invalid credentials, e.g. { "message": "Invalid API Key", "code": "UNAUTHORIZED" }.

The body is the standard error object: see Errors.

404 Error

Cardholder not found or not owned by you (CARDHOLDER_NOT_FOUND), or KYC not initiated for this cardholder.

The body is the standard error object: see Errors.

500 Error

Unexpected server error. Body is { message: "Internal server error", code: "INTERNAL_SERVER_ERROR" }.

The body is the standard error object: see Errors.

Last updated June 5, 2026