Saltar al contenido principal
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' \
  --form 5.file='@example-file'
import requests

url = "https://api.spherepay.co/v2/document"

files = {
    "0.file": ("example-file", open("example-file", "rb")),
    "1.file": ("example-file", open("example-file", "rb")),
    "2.file": ("example-file", open("example-file", "rb")),
    "3.file": ("example-file", open("example-file", "rb")),
    "4.file": ("example-file", open("example-file", "rb")),
    "5.file": ("example-file", open("example-file", "rb"))
}
payload = {
    "targetId": "customer_66c4168d418a410eae282b83883bdc39",
    "target": "customer",
    "documentType": "passport",
    "country": "USA",
    "side": "front",
    "description": "Passport photo page",
    "file": "(binary)"
}
headers = {"Authorization": "Bearer <token>"}

response = requests.post(url, data=payload, files=files, headers=headers)

print(response.text)
const form = new FormData();
form.append('targetId', 'customer_66c4168d418a410eae282b83883bdc39');
form.append('target', 'customer');
form.append('documentType', 'passport');
form.append('country', 'USA');
form.append('side', 'front');
form.append('description', 'Passport photo page');
form.append('file', '(binary)');
form.append('0.file', '{
  "fileName": "example-file"
}');
form.append('1.file', '{
  "fileName": "example-file"
}');
form.append('2.file', '{
  "fileName": "example-file"
}');
form.append('3.file', '{
  "fileName": "example-file"
}');
form.append('4.file', '{
  "fileName": "example-file"
}');
form.append('5.file', '{
  "fileName": "example-file"
}');

const options = {method: 'POST', headers: {Authorization: 'Bearer <token>'}};

options.body = form;

fetch('https://api.spherepay.co/v2/document', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));
<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.spherepay.co/v2/document",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"targetId\"\r\n\r\ncustomer_66c4168d418a410eae282b83883bdc39\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"target\"\r\n\r\ncustomer\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"documentType\"\r\n\r\npassport\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"country\"\r\n\r\nUSA\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"side\"\r\n\r\nfront\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"description\"\r\n\r\nPassport photo page\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"\r\n\r\n(binary)\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"0.file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n  \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"1.file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n  \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"2.file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n  \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"3.file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n  \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"4.file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n  \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"5.file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n  \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001--",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: multipart/form-data"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.spherepay.co/v2/document"

	payload := strings.NewReader("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"targetId\"\r\n\r\ncustomer_66c4168d418a410eae282b83883bdc39\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"target\"\r\n\r\ncustomer\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"documentType\"\r\n\r\npassport\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"country\"\r\n\r\nUSA\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"side\"\r\n\r\nfront\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"description\"\r\n\r\nPassport photo page\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"\r\n\r\n(binary)\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"0.file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n  \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"1.file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n  \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"2.file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n  \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"3.file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n  \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"4.file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n  \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"5.file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n  \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001--")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}
HttpResponse<String> response = Unirest.post("https://api.spherepay.co/v2/document")
  .header("Authorization", "Bearer <token>")
  .body("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"targetId\"\r\n\r\ncustomer_66c4168d418a410eae282b83883bdc39\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"target\"\r\n\r\ncustomer\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"documentType\"\r\n\r\npassport\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"country\"\r\n\r\nUSA\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"side\"\r\n\r\nfront\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"description\"\r\n\r\nPassport photo page\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"\r\n\r\n(binary)\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"0.file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n  \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"1.file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n  \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"2.file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n  \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"3.file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n  \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"4.file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n  \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"5.file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n  \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001--")
  .asString();
require 'uri'
require 'net/http'

url = URI("https://api.spherepay.co/v2/document")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request.body = "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"targetId\"\r\n\r\ncustomer_66c4168d418a410eae282b83883bdc39\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"target\"\r\n\r\ncustomer\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"documentType\"\r\n\r\npassport\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"country\"\r\n\r\nUSA\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"side\"\r\n\r\nfront\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"description\"\r\n\r\nPassport photo page\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"\r\n\r\n(binary)\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"0.file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n  \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"1.file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n  \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"2.file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n  \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"3.file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n  \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"4.file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n  \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"5.file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n  \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001--"

response = http.request(request)
puts response.read_body
{
  "id": "documentFile_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
  "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"
    }
  ]
}
Sube un documento de identidad para un cliente o representante empresarial como parte del proceso de verificación KYC o KYB. Los documentos se envían como datos de formulario multipart. Los formatos de archivo aceptados son PDF, JPEG, PNG, HEIC y TIFF, con un tamaño máximo de archivo de 15 MB. Los campos target y documentType determinan cómo SpherePay enruta y procesa la carga — los clientes individuales, los clientes empresariales y los representantes empresariales tienen cada uno su propio conjunto de tipos de documentos aceptados.
Los documentos para clientes individuales se suben con target: "customer". Los documentos para representantes empresariales (UBOs) usan target: "business_representative" y el targetId debe ser el ID del representante, no el del cliente.

Autorizaciones

​
Authorization
string
header
requerido

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

Cuerpo

multipart/form-data

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

​
targetId
string
requerido

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

Minimum string length: 1
Ejemplo:

"customer_66c4168d418a410eae282b83883bdc39"

​
file
file
requerido

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

​
country
string
requerido

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

Ejemplo:

"USA"

​
target
enum<string>
requerido

The target entity for which the document is being uploaded

Opciones disponibles:
customer
Ejemplo:

"customer"

​
documentType
enum<string>
requerido

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

Opciones disponibles:
passport,
drivers,
id_card,
residence_permit
Ejemplo:

"passport"

​
description
string

Optional description or notes about the document

Ejemplo:

"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.

Opciones disponibles:
front,
back
Ejemplo:

"front"

Respuesta

Response for an ID document uploaded for an individual customer.

​
id
string
requerido

The unique identifier of the document

Ejemplo:

"documentFile_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6"

​
targetId
string
requerido

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

Ejemplo:

"customer_66c4168d418a410eae282b83883bdc39"

​
createdAt
string
requerido

The date and time the document was created

Ejemplo:

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

​
fileName
string
requerido

The name of the document file

Ejemplo:

"passport_front_20250101.pdf"

​
fileSize
number
requerido

The size of the document in bytes

Ejemplo:

2048576

​
mimeType
string
requerido

The MIME type of the document file

Ejemplo:

"application/pdf"

​
description
string
requerido

The description of the document

Ejemplo:

"Passport photo page"

​
target
enum<string>
requerido

The target entity for which the document is being uploaded

Opciones disponibles:
customer
Ejemplo:

"customer"

​
documentType
enum<string>
requerido

The type of the document

Opciones disponibles:
drivers,
passport,
id_card,
residence_permit
Ejemplo:

"passport"

​
country
string
requerido

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

Ejemplo:

"USA"

​
side
enum<string>
requerido

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

Opciones disponibles:
front,
back
Ejemplo:

"front"

Última modificación el 22 de junio de 2026