Skip to main content
Upload Document
curl --request POST \
  --url https://api.spherepay.co/v2/document \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: multipart/form-data' \
  --form targetId=customer_66c4168d418a410eae282b83883bdc39 \
  --form target=customer \
  --form documentType=passport \
  --form country=USA \
  --form side=front \
  --form 'description=Passport photo page' \
  --form 'file=(binary)' \
  --form 0.file='@example-file' \
  --form 1.file='@example-file' \
  --form 2.file='@example-file' \
  --form 3.file='@example-file' \
  --form 4.file='@example-file'
{
  "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"
}
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.

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

multipart/form-data

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

​
targetId
string
required

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

Minimum string length: 1
Example:

"customer_66c4168d418a410eae282b83883bdc39"

​
file
file
required

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

​
country
string
required

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

Example:

"USA"

​
target
enum<string>
required

The target entity for which the document is being uploaded

Available options:
customer
Example:

"customer"

​
documentType
enum<string>
required

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

Available options:
drivers,
id_card,
passport,
residence_permit
Example:

"passport"

​
description
string

Optional description or notes about the document

Example:

"Front side of driver's license"

​
side
enum<string>

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

Available options:
front,
back
Example:

"front"

Response

Response for an ID document uploaded for an individual customer.

​
targetId
string
required

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

Example:

"customer_66c4168d418a410eae282b83883bdc39"

​
createdAt
string
required

The date and time the document was created

Example:

"2025-12-31T10:30:00.000Z"

​
fileName
string
required

The name of the document file

Example:

"passport_front_20250101.pdf"

​
fileSize
number
required

The size of the document in bytes

Example:

2048576

​
mimeType
string
required

The MIME type of the document file

Example:

"application/pdf"

​
target
enum<string>
required

The target entity for which the document is being uploaded

Available options:
customer
Example:

"customer"

​
documentType
enum<string>
required

The type of the document

Available options:
drivers,
id_card,
passport,
residence_permit
Example:

"passport"

​
side
enum<string> | null
required

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

Available options:
front,
back
Example:

"front"

​
description
string

The description of the document

Example:

"Passport photo page"

​
country
string

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

Example:

"USA"

Last modified on June 18, 2026