Add cardholder verification documents (multipart)
POST /v1/api-gateway/cardholder/{cardholder_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 /cardholder/{cardholderId}/check to submit the documents for review.
Request
Authentication: your API key in the x-api-key header.
Path parameters
| Field | Type | Description |
|---|---|---|
cardholder_ required | string, uuid | The Moon cardholder id (id, a UUID), not your end_. |
Body
| Field | Type | Description |
|---|---|---|
file | string, binary | Document to upload. |
metadata | string | JSON-encoded document metadata. |
Example request
cURL
curl --request POST \
--url 'https://api.themooncard.com/v1/api-gateway/cardholder/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_, APPLICANT_).
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 this organization.
The body is the standard error object: see Errors.
500 Error
Unexpected server error. Body is { message: "Internal server error", code: "INTERNAL_.
The body is the standard error object: see Errors.
Last updated April 30, 2026