> ## 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 KYC and KYB Identity Documents > Upload a document for a customer. 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, and PNG, validated by file signature rather than extension. Maximum file size is 10 MB per file, or 8 MB for identity documents (`passport`, `drivers`, `id_card`, `residence_permit`, `br_digital_drivers`, `br_digital_id`). 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. ## OpenAPI ````yaml openapi/spherepay.yaml POST /v2/document openapi: 3.0.0 info: contact: {} description: The Sphere REST API for payments, transfers, and accounts. title: Sphere API version: '2' servers: - description: Production url: https://api.spherepay.co security: - bearer: [] tags: [] paths: /v2/document: post: summary: Upload Document description: Upload a document for a customer. operationId: postV2Document parameters: [] requestBody: content: multipart/form-data: schema: oneOf: - description: >- Upload documents for individual customers. Supports identity documents (with country and side) and other documents (liveness report, tax forms, source of funds). example: country: USA description: Passport photo page documentType: passport file: (binary) side: front target: customer targetId: customer_66c4168d418a410eae282b83883bdc39 oneOf: - description: >- Upload identity documents for individual customers. Requires country of issuance and optionally the document side (front/back). properties: country: description: >- The ISO3166-1 Alpha-3 country code associated with the document (e.g., USA, GBR, FRA). See [Country Codes](/concepts/reference/supported-countries). example: USA type: string description: description: Optional description or notes about the document example: Front side of driver's license type: string documentType: description: >- ID documents for individual customers. See [Document Guideline](/concepts/onboarding/identification-types) for requirements. enum: - passport - drivers - id_card - residence_permit - br_digital_drivers - br_digital_id example: passport type: string file: description: >- The document file to upload. Accepted formats: PDF, JPEG, PNG. Maximum file size: 8MB. Minimum file size: 10KB. format: binary type: string side: description: >- The side of the document if it has multiple sides (e.g., front, back). Leave undefined for single-sided documents. enum: - front - back example: front type: string target: description: >- The target entity for which the document is being uploaded enum: - customer example: customer type: string targetId: description: >- The unique identifier of the target entity for which the document is being uploaded example: customer_66c4168d418a410eae282b83883bdc39 minLength: 1 type: string required: - targetId - file - country - target - documentType title: ID Document type: object - description: >- Upload non-ID documents for individual customers, such as liveness report, tax forms, or source-of-funds documentation. properties: description: description: Optional description or notes about the document example: Front side of driver's license type: string documentType: description: Non-ID documents for individual customers. enum: - proof_of_address_document - liveness_report_document - w8_ben_document - source_of_funds_document example: proof_of_address_document type: string file: description: >- The document file to upload. Accepted formats: PDF, JPEG, PNG. Maximum file size: 8MB. Minimum file size: 10KB. format: binary type: string target: description: >- The target entity for which the document is being uploaded enum: - customer example: customer type: string targetId: description: >- The unique identifier of the target entity for which the document is being uploaded example: customer_66c4168d418a410eae282b83883bdc39 minLength: 1 type: string required: - targetId - file - target - documentType title: Other Document type: object title: Individual - description: >- Upload company documents for business customers, such as incorporation certificates, shareholder registries, or proof of address. example: description: Certificate of incorporation documentType: incorporation_cert_document file: (binary) target: customer targetId: customer_66c4168d418a410eae282b83883bdc39 properties: description: description: Optional description or notes about the document example: Front side of driver's license type: string documentType: description: >- Company documents for business customers. See [Business Document Guideline](/concepts/onboarding/identification-types) for requirements. enum: - proof_of_address_document - incorporation_cert_document - incorporation_articles_document - shareholder_registry_document - directors_registry_document - w8_ben_e_document - corporate_resolution_document - bank_statement_document - financial_statements_document - source_of_funds_document - regulated_activity_document - flow_of_funds_document - proof_of_nature_of_business_document example: incorporation_cert_document type: string file: description: >- The document file to upload. Accepted formats: PDF, JPEG, PNG. Maximum file size: 8MB. Minimum file size: 10KB. format: binary type: string target: description: >- The target entity for which the document is being uploaded enum: - customer example: customer type: string targetId: description: >- The unique identifier of the target entity for which the document is being uploaded example: customer_66c4168d418a410eae282b83883bdc39 minLength: 1 type: string required: - targetId - file - target - documentType title: Business type: object - description: >- Upload documents for business representatives. Supports identity documents (with country and side) and proof of address. example: country: USA description: Passport photo page documentType: passport file: (binary) side: front target: business_representative targetId: business_representative_66c4168d418a410eae282b83883bdc39 oneOf: - description: Upload an ID document for a business representative. properties: country: description: >- The ISO3166-1 Alpha-3 country code associated with the document (e.g., USA, GBR, FRA). See [Country Codes](/concepts/reference/supported-countries). example: USA type: string description: description: Optional description or notes about the document example: Front side of driver's license type: string documentType: description: >- ID documents for business representatives. See [Document Guideline](/concepts/onboarding/identification-types) for requirements. enum: - passport - drivers - id_card - residence_permit - br_digital_drivers - br_digital_id example: passport type: string file: description: >- The document file to upload. Accepted formats: PDF, JPEG, PNG. Maximum file size: 8MB. Minimum file size: 10KB. format: binary type: string side: description: >- The side of the document if it has multiple sides (e.g., front, back). Leave undefined for single-sided documents. enum: - front - back example: front type: string target: description: >- The target entity for which the document is being uploaded enum: - business_representative example: business_representative type: string targetId: description: >- The unique identifier of the target entity for which the document is being uploaded example: customer_66c4168d418a410eae282b83883bdc39 minLength: 1 type: string required: - targetId - file - country - target - documentType title: ID Document type: object - description: Upload other documents for business representatives. properties: description: description: Optional description or notes about the document example: Front side of driver's license type: string documentType: description: Other documents for business representatives. enum: - proof_of_address_document - liveness_report_document - w9_document - w8_ben_document - source_of_funds_document example: proof_of_address_document type: string file: description: >- The document file to upload. Accepted formats: PDF, JPEG, PNG. Maximum file size: 8MB. Minimum file size: 10KB. format: binary type: string target: description: >- The target entity for which the document is being uploaded enum: - business_representative example: business_representative type: string targetId: description: >- The unique identifier of the target entity for which the document is being uploaded example: customer_66c4168d418a410eae282b83883bdc39 minLength: 1 type: string required: - targetId - file - target - documentType title: Other Document type: object title: UBO - description: >- Upload supporting documents for transfers/payouts (e.g., invoices, contracts). Documents are uploaded first before linking to a transfer later. example: description: Invoice for third-party payment file: (binary) target: transfer properties: description: description: Optional description or notes about the document example: Invoice for third-party payment type: string file: description: >- The document file to upload. Accepted formats: PDF, JPEG, PNG. Maximum file size: 8MB. Minimum file size: 10KB. format: binary type: string target: description: >- The target entity for which the document is being uploaded enum: - transfer example: transfer type: string required: - target - file title: Transfer type: object required: true responses: '201': content: application/json: schema: oneOf: - description: >- Response containing an uploaded document for an individual customer. example: country: USA createdAt: '2025-12-31T10:30:00.000Z' description: Passport photo page documentType: passport fileName: passport_front_20250101.pdf fileSize: 2048576 id: documentFile_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6 mimeType: application/pdf side: front target: customer targetId: customer_66c4168d418a410eae282b83883bdc39 oneOf: - description: >- Response for an ID document uploaded for an individual customer. properties: country: description: >- The ISO3166-1 Alpha-3 country code associated with the document (e.g., USA, GBR, FRA) example: USA type: string createdAt: description: The date and time the document was created example: '2025-12-31T10:30:00.000Z' type: string description: description: The description of the document example: Passport photo page type: string documentType: description: The type of the document enum: - drivers - passport - id_card - residence_permit - br_digital_drivers - br_digital_id example: passport type: string fileName: description: The name of the document file example: passport_front_20250101.pdf type: string fileSize: description: The size of the document in bytes example: 2048576 type: number id: description: The unique identifier of the document example: documentFile_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6 type: string mimeType: description: The MIME type of the document file example: application/pdf type: string side: description: >- The side of the document if it has multiple sides (e.g., front, back). Leave undefined for single-sided documents. enum: - front - back example: front type: string target: description: >- The target entity for which the document is being uploaded enum: - customer example: customer type: string targetId: description: >- The unique identifier of the target entity for which the document is being uploaded example: customer_66c4168d418a410eae282b83883bdc39 type: string required: - id - targetId - createdAt - fileName - fileSize - mimeType - description - target - documentType - country - side title: ID Document type: object - description: >- Response for a non-identity individual-customer document: proof_of_address_document, liveness_report_document, w8_ben_document, or source_of_funds_document. properties: country: description: >- Country associated with the document when one was resolved for the upload example: DEU type: string createdAt: description: The date and time the document was created example: '2025-12-31T10:30:00.000Z' type: string description: description: The description of the document example: Passport photo page type: string documentType: description: >- Non-ID document type (liveness report, tax form, or source-of-funds declaration) enum: - passport - drivers - id_card - residence_permit - br_digital_drivers - br_digital_id - proof_of_address_document - liveness_report_document - w8_ben_document - source_of_funds_document example: proof_of_address_document type: string fileName: description: The name of the document file example: passport_front_20250101.pdf type: string fileSize: description: The size of the document in bytes example: 2048576 type: number id: description: The unique identifier of the document example: documentFile_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6 type: string mimeType: description: The MIME type of the document file example: application/pdf type: string side: description: Document side, if applicable enum: - front - back example: null type: string target: description: >- The target entity for which the document is being uploaded enum: - customer example: customer type: string targetId: description: >- The unique identifier of the target entity for which the document is being uploaded example: customer_66c4168d418a410eae282b83883bdc39 type: string required: - id - targetId - createdAt - fileName - fileSize - mimeType - description - target - documentType - country - side title: Other Document type: object title: Individual - description: >- Response containing an uploaded company document for a business customer. example: createdAt: '2025-12-31T10:30:00.000Z' description: Certificate of incorporation documentType: incorporation_cert_document fileName: incorporation_cert.pdf fileSize: 1024000 id: documentFile_b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7 mimeType: application/pdf target: customer targetId: customer_66c4168d418a410eae282b83883bdc39 properties: createdAt: description: The date and time the document was created example: '2025-12-31T10:30:00.000Z' type: string description: description: The description of the document example: Passport photo page type: string documentType: description: The type of the document enum: - proof_of_address_document - incorporation_cert_document - incorporation_articles_document - shareholder_registry_document - directors_registry_document - w8_ben_e_document - corporate_resolution_document - bank_statement_document - financial_statements_document - source_of_funds_document - regulated_activity_document - flow_of_funds_document - proof_of_nature_of_business_document example: incorporation_cert_document type: string fileName: description: The name of the document file example: passport_front_20250101.pdf type: string fileSize: description: The size of the document in bytes example: 2048576 type: number id: description: The unique identifier of the document example: documentFile_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6 type: string mimeType: description: The MIME type of the document file example: application/pdf type: string target: description: >- The target entity for which the document is being uploaded enum: - customer example: customer type: string targetId: description: >- The unique identifier of the target entity for which the document is being uploaded example: customer_66c4168d418a410eae282b83883bdc39 type: string required: - id - targetId - createdAt - fileName - fileSize - mimeType - description - target - documentType title: Business Customer Document type: object - description: >- Response containing an uploaded document for a business representative (identity document, proof of address, or liveness report). example: country: USA createdAt: '2025-12-31T10:30:00.000Z' description: Passport photo page documentType: passport fileName: passport_front_20250101.pdf fileSize: 2048576 id: documentFile_c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8 mimeType: application/pdf side: front target: business_representative targetId: business_representative_66c4168d418a410eae282b83883bdc39 oneOf: - description: >- Response for an ID document uploaded for a business representative. properties: country: description: >- The ISO3166-1 Alpha-3 country code associated with the document (e.g., USA, GBR, FRA) example: USA type: string createdAt: description: The date and time the document was created example: '2025-12-31T10:30:00.000Z' type: string description: description: The description of the document example: Passport photo page type: string documentType: description: The type of the document enum: - drivers - passport - id_card - residence_permit - br_digital_drivers - br_digital_id example: passport type: string fileName: description: The name of the document file example: passport_front_20250101.pdf type: string fileSize: description: The size of the document in bytes example: 2048576 type: number id: description: The unique identifier of the document example: documentFile_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6 type: string mimeType: description: The MIME type of the document file example: application/pdf type: string side: description: >- The side of the document if it has multiple sides (e.g., front, back). Leave undefined for single-sided documents. enum: - front - back example: front type: string target: enum: - business_representative type: string targetId: description: >- The unique identifier of the target entity for which the document is being uploaded example: customer_66c4168d418a410eae282b83883bdc39 type: string required: - id - targetId - createdAt - fileName - fileSize - mimeType - description - target - documentType - country - side title: ID Document type: object - description: >- Response for other documents uploaded for business representatives. properties: createdAt: description: The date and time the document was created example: '2025-12-31T10:30:00.000Z' type: string description: description: The description of the document example: Passport photo page type: string documentType: description: The type of the document enum: - passport - drivers - id_card - residence_permit - br_digital_drivers - br_digital_id - proof_of_address_document - liveness_report_document - w9_document - w8_ben_document - source_of_funds_document example: proof_of_address_document type: string fileName: description: The name of the document file example: passport_front_20250101.pdf type: string fileSize: description: The size of the document in bytes example: 2048576 type: number id: description: The unique identifier of the document example: documentFile_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6 type: string mimeType: description: The MIME type of the document file example: application/pdf type: string target: description: >- The target entity for which the document is being uploaded enum: - business_representative example: business_representative type: string targetId: description: >- The unique identifier of the target entity for which the document is being uploaded example: customer_66c4168d418a410eae282b83883bdc39 type: string required: - id - targetId - createdAt - fileName - fileSize - mimeType - description - target - documentType title: Other Document type: object title: Business Representative Document - description: >- Response for a supporting document uploaded for a transfer. example: fileSize: 2048576 id: document_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6 mimeType: application/pdf originalFilename: invoice_2025.pdf target: transfer uploadedAt: '2025-12-31T10:30:00.000Z' properties: fileSize: description: The size of the document in bytes example: 2048576 type: number id: description: The unique identifier of the uploaded document example: document_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6 type: string mimeType: description: The MIME type of the document file example: application/pdf type: string originalFilename: description: The original filename of the uploaded document example: invoice_2025.pdf type: string target: description: The target entity for which the document was uploaded enum: - transfer example: transfer type: string uploadedAt: description: The date and time the document was uploaded example: '2025-12-31T10:30:00.000Z' oneOf: - type: string - {} required: - target - id - originalFilename - mimeType - fileSize - uploadedAt title: Transfer type: object description: '' '400': content: application/json: examples: Bad Request: summary: Bad Request value: code: address/invalid correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Invalid request parameters status: 400 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Bad Request '404': content: application/json: examples: Not Found: summary: Not Found value: code: resource/not-found correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Resource not found status: 404 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Not Found '422': content: application/json: examples: Validation Error: summary: Validation Error value: code: validation/failed correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Validation failed errors: - detail: Invalid email format pointer: /email - detail: Name is required pointer: /name status: 422 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Unprocessable Entity - Validation Error components: schemas: ProblemDetailsDto: properties: code: type: string correlationId: type: string detail: type: string errors: items: properties: detail: type: string header: type: string parameter: type: string pointer: type: string required: - detail type: object type: array status: type: integer title: type: string required: - status - detail type: object securitySchemes: bearer: bearerFormat: JWT scheme: bearer type: http ````