Skip to main content
POST
/
2025-06-09
/
documents
Upload a User Document
curl --request POST \
  --url https://staging.crossmint.com/api/2025-06-09/documents \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <x-api-key>' \
  --data '
{
  "reference": {
    "userLocator": "email:user@example.com"
  },
  "documentType": "id-passport",
  "data": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==",
  "expiresAt": "2030-12-31"
}
'
{
  "id": "doc_abc123xyz",
  "documentType": "id-passport",
  "createdAt": "2024-12-05T10:30:00.000Z",
  "expiresAt": "2030-12-31"
}

Headers

​
X-API-KEY
string
required

API key required for authentication

Body

application/json
​
reference
object
required

Reference to the user who owns this document

Example:
{ "userLocator": "email:user@example.com" }
​
documentType
enum<string>
required

Type of document

Available options:
id-passport,
id-idcard-back,
id-idcard-front,
id-residency-permit,
proof-of-address,
proof-of-income,
selfie-front,
selfie-left,
selfie-right
Example:

"id-passport"

​
data
string
required

Base64 encoded document data

Minimum string length: 1
Example:

"data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg=="

​
expiresAt
string

Document expiration date in YYYY-MM-DD format

Pattern: ^\d{4}-\d{2}-\d{2}$
Example:

"2030-12-31"

Response

Document replaced successfully

​
id
string
required

Unique identifier for the document

Example:

"doc_abc123xyz"

​
documentType
enum<string>
required

Type of document

Available options:
id-passport,
id-idcard-back,
id-idcard-front,
id-residency-permit,
proof-of-address,
proof-of-income,
selfie-front,
selfie-left,
selfie-right
Example:

"id-passport"

​
createdAt
string
required

ISO 8601 timestamp when the document was created

Example:

"2024-12-05T10:30:00.000Z"

​
expiresAt
string

Document expiration date in YYYY-MM-DD format

Example:

"2030-12-31"