Browse the docs

Add cardholder verification documents (multipart)

POST /v2/api-gateway/cardholders/{id}/verification-documents

Uploads one identity document for the cardholder to the KYC provider. A KYC session is started automatically when the cardholder has none yet. Returns the provider's document response. Follow with POST /cardholders/{id}/check to submit the documents for review, or use the hosted flow (POST /cardholders/{id}/kyc-link) instead.

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`.

Body

Field	Type	Description
`file`	string, binary	Document to upload.
`metadata`	string	Optional JSON string with document metadata.

Example request

cURL

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

Responses

200 Success

Document accepted; the body is the verification provider's receipt for it.

JSON

{
  "document_type": "PASSPORT",
  "country": "US",
  "uploaded_at": "2026-08-16T17:51:01.000Z",
  "warnings": []
}

400 Error

Validation failed, or the cardholder has no KYC session that can accept documents (KYC_NOT_INITIATED, APPLICANT_NOT_FOUND).

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.

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