New: Streamlined onboarding defaults  View changelog →
Document

Upload Document

Upload a document for a customer.

POST
/v2/document

Authorization

AuthorizationBearer <token>

In: header

Request Body

Upload documents for individual customers. Supports identity documents (with country and side) and liveness report.

Upload identity documents for individual customers. Requires country of issuance and optionally the document side (front/back).

targetIdstring

The unique identifier of the target entity for which the document is being uploaded

Length1 <= length
description?string

Optional description or notes about the document

filefile

The document file to upload. Accepted formats: PDF, JPEG, PNG, HEIC, TIFF. Maximum file size: 15MB

countrystring

The ISO3166-1 Alpha-3 country code associated with the document (e.g., USA, GBR, FRA). See Country Codes.

side?string

The side of the document if it has multiple sides (e.g., front, back). Leave undefined for single-sided documents.

Value in"front" | "back"
targetstring

The target entity for which the document is being uploaded

Value in"customer"
documentTypestring

ID documents for individual customers. See Document Guideline for requirements.

Value in"drivers" | "id_card" | "passport" | "residence_permit"

Upload other documents for individual customers, such as liveness report.

targetIdstring

The unique identifier of the target entity for which the document is being uploaded

Length1 <= length
description?string

Optional description or notes about the document

filefile

The document file to upload. Accepted formats: PDF, JPEG, PNG, HEIC, TIFF. Maximum file size: 15MB

targetstring

The target entity for which the document is being uploaded

Value in"customer"
documentTypestring

Liveness report document for individual customers

Value in"liveness_report"

Upload company documents for business customers, such as incorporation certificates, shareholder registries, or proof of address.

targetIdstring

The unique identifier of the target entity for which the document is being uploaded

Length1 <= length
description?string

Optional description or notes about the document

filefile

The document file to upload. Accepted formats: PDF, JPEG, PNG, HEIC, TIFF. Maximum file size: 15MB

targetstring

The target entity for which the document is being uploaded

Value in"customer"
documentTypestring

Company documents for business customers. See Business Document Guideline for requirements.

Value in"incorporation_cert" | "shareholder_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.

targetIdstring

The unique identifier of the target entity for which the document is being uploaded

Length1 <= length
description?string

Optional description or notes about the document

filefile

The document file to upload. Accepted formats: PDF, JPEG, PNG, HEIC, TIFF. Maximum file size: 15MB

countrystring

The ISO3166-1 Alpha-3 country code associated with the document (e.g., USA, GBR, FRA). See Country Codes.

side?string

The side of the document if it has multiple sides (e.g., front, back). Leave undefined for single-sided documents.

Value in"front" | "back"
targetstring

The target entity for which the document is being uploaded

Value in"business_representative"
documentTypestring

ID documents for business representatives. See Document Guideline for requirements.

Value in"drivers" | "id_card" | "passport" | "residence_permit"

Upload other documents for business representatives.

targetIdstring

The unique identifier of the target entity for which the document is being uploaded

Length1 <= length
description?string

Optional description or notes about the document

filefile

The document file to upload. Accepted formats: PDF, JPEG, PNG, HEIC, TIFF. Maximum file size: 15MB

targetstring

The target entity for which the document is being uploaded

Value in"business_representative"
documentTypestring

Proof of address for business representatives. See Business Document Guideline for requirements.

Value in"proof_of_address" | "liveness_report"

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"
    }
  ]
}