Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.spherepay.co/llms.txt

Use this file to discover all available pages before exploring further.

Upload an identity document for a customer or business representative as part of the KYC or KYB verification process. Documents are submitted as multipart form data. Accepted file formats are PDF, JPEG, PNG, HEIC, and TIFF, with a maximum file size of 15 MB. The target and documentType fields determine how SpherePay routes and processes the upload — individual customers, business customers, and business representatives each have their own set of accepted document types.
Documents for individual customers are uploaded with target: "customer". Documents for business representatives (UBOs) use target: "business_representative" and the targetId must be the representative’s ID, not the customer’s.

​
Endpoint

POST https://api.spherepay.co/v2/document

​
Authentication

All requests must include a Bearer token in the Authorization header. 
Authorization: Bearer <token>

​
Request parameters

This endpoint accepts multipart/form-data.
​
targetId
string
required
The unique identifier of the entity the document belongs to. This is the customer ID for individual and business customers, or the business representative ID for UBO documents.
​
target
string
required
The type of entity the document is being uploaded for.Accepted values: "customer" | "business_representative"
​
documentType
string
required
The classification of document being uploaded. Accepted values depend on target:
  • Individual customer: "drivers" | "id_card" | "passport" | "residence_permit" | "liveness_report"
  • Business customer: "incorporation_cert" | "shareholder_registry" | "proof_of_address"
  • Business representative: "drivers" | "id_card" | "passport" | "residence_permit" | "proof_of_address" | "liveness_report"
​
file
file
required
The document file to upload. Accepted formats: PDF, JPEG, PNG, HEIC, TIFF. Maximum file size: 15 MB.
​
country
string
The ISO 3166-1 Alpha-3 country code of the issuing country (e.g., "USA", "GBR", "FRA"). Required for government-issued ID documents (drivers, id_card, passport, residence_permit).
​
side
string
The side of the document, for multi-sided documents. Leave unset for single-sided documents (e.g., passports).Accepted values: "front" | "back"
​
description
string
Optional free-text description or notes about the document.
  -H "Authorization: Bearer <token>" \
  -F targetId="customer_66c4168d418a410eae282b83883bdc39" \
  -F target="customer" \
  -F documentType="passport" \
  -F country="USA" \
  -F side="front" \
  -F description="Passport photo page" \
  -F file="@/path/to/passport_front.pdf"

​
Response fields

​
targetId
string
The ID of the entity the document was uploaded for.
​
target
string
The type of entity ("customer" or "business_representative").
​
documentType
string
The classification of the uploaded document.
​
country
string
The ISO 3166-1 Alpha-3 country code of the issuing country, if applicable.
​
side
string
The side of the document ("front" or "back"), if applicable.
​
description
string
The description provided at upload time, if any.
​
fileName
string
The stored file name of the uploaded document.
​
fileSize
number
The size of the uploaded file in bytes.
​
mimeType
string
The MIME type of the uploaded file (e.g., "application/pdf").
​
createdAt
string
ISO 8601 timestamp of when the document was uploaded.
{
  "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"
}
Last modified on May 12, 2026