Upload Document
Upload a document for a customer.
In: header
Upload identity documents for individual customers. Requires country of issuance and optionally the document side (front/back).
The unique identifier of the target entity for which the document is being uploaded
1 <= lengthOptional description or notes about the document
The document file to upload. Accepted formats: PDF, JPEG, PNG, HEIC, TIFF. Maximum file size: 15MB
The ISO3166-1 Alpha-3 country code associated with the document (e.g., USA, GBR, FRA). See Country Codes.
The side of the document if it has multiple sides (e.g., front, back). Leave undefined for single-sided documents.
"front" | "back"The target entity for which the document is being uploaded
"customer"ID documents for individual customers. See Document Guideline for requirements.
"drivers" | "id_card" | "passport" | "residence_permit"Upload company documents for business customers, such as incorporation certificates, shareholder registries, or proof of address.
The unique identifier of the target entity for which the document is being uploaded
1 <= lengthOptional description or notes about the document
The document file to upload. Accepted formats: PDF, JPEG, PNG, HEIC, TIFF. Maximum file size: 15MB
The target entity for which the document is being uploaded
"customer"Company documents for business customers. See Business Document Guideline for requirements.
"incorporation_cert" | "shareholder_registry" | "directors_registry" | "proof_of_address"Upload documents for business representatives. Supports identity documents (with country and side) and proof of address.
Upload an ID document for a business representative.
The unique identifier of the target entity for which the document is being uploaded
1 <= lengthOptional description or notes about the document
The document file to upload. Accepted formats: PDF, JPEG, PNG, HEIC, TIFF. Maximum file size: 15MB
The ISO3166-1 Alpha-3 country code associated with the document (e.g., USA, GBR, FRA). See Country Codes.
The side of the document if it has multiple sides (e.g., front, back). Leave undefined for single-sided documents.
"front" | "back"The target entity for which the document is being uploaded
"business_representative"ID documents for business representatives. See Document Guideline for requirements.
"drivers" | "id_card" | "passport" | "residence_permit"Upload other documents for business representatives.
The unique identifier of the target entity for which the document is being uploaded
1 <= lengthOptional description or notes about the document
The document file to upload. Accepted formats: PDF, JPEG, PNG, HEIC, TIFF. Maximum file size: 15MB
The target entity for which the document is being uploaded
"business_representative"Proof of address for business representatives. See Business Document Guideline for requirements.
"proof_of_address"Response Body
curl -X POST "https://api.spherepay.co/v2/document" \
-F targetId="customer_66c4168d418a410eae282b83883bdc39" \
-F target="customer" \
-F documentType="passport" \
-F country="USA" \
-F side="front" \
-F description="Passport photo page" \
-F file="(binary)"{
"targetId": "customer_66c4168d418a410eae282b83883bdc39",
"target": "customer",
"documentType": "passport",
"country": "USA",
"side": "front",
"description": "Passport photo page",
"fileName": "passport_front_20250101.pdf",
"fileSize": 2048576,
"mimeType": "application/pdf",
"createdAt": "2025-12-31T10:30:00.000Z"
}{
"status": 400,
"detail": "Invalid request parameters",
"code": "address/invalid",
"correlationId": "28c61e885c6e5eaa78c1a2183a9b883c"
}{
"status": 404,
"detail": "Resource not found",
"code": "resource/not-found",
"correlationId": "28c61e885c6e5eaa78c1a2183a9b883c"
}{
"status": 422,
"detail": "Validation failed",
"code": "validation/failed",
"correlationId": "28c61e885c6e5eaa78c1a2183a9b883c",
"errors": [
{
"detail": "Invalid email format",
"pointer": "/email"
},
{
"detail": "Name is required",
"pointer": "/name"
}
]
}