---
title: "Upload a document"
method: POST
path: "/v0/customers/{id}/kyc/documents"
tags: ["Customers"]
---

# Upload a document

`POST /v0/customers/{id}/kyc/documents`

## Request

- Base URL: `https://orchestration.seismic.systems/api`
- URL: `https://orchestration.seismic.systems/api/v0/customers/{id}/kyc/documents`
- Auth: API key in header `Api-Key`

Attach a supporting document (proof of address, bank statement, ID scan, …) to the customer — or, via `owner=person`, to one of a business customer's associated persons. 12 MB transport ceiling. A PDF longer than 20 pages is split: the first 20 pages are stored under the requested `kind` and returned here, and each further span of 20 pages is stored as an extra `other` document named `FILENAME_2.pdf`, `FILENAME_3.pdf`, …. When a business profile sets `addresses.operating_is_remote`, the beneficial owner whose residential address matches the operating address already evidences that address in their own section of the package, so a company `proof_of_address` upload with that document's file name returns the existing document instead of storing a copy, and one with a different file name is stored as `other` with the description "Alternate proof of address for the company".

## Path parameters

- `id` string, uuid, required

## Request body `multipart/form-data`

- DocumentUploadForm: Multipart form for `POST /v0/customers/{id}/kyc/documents`.
  - `description` string, nullable: Free-text label, up to 256 characters. Required when `kind=other` unless `purpose=rfi_answer`; optional for every other kind.
  - `file` string, binary, required: The file contents.
  - `kind` 'business_formation' | 'articles_of_association' | 'memorandum_of_association' | 'dba_registration' | 'bank_statement' | 'ubo_bank_statement' | 'ownership_information' | 'shareholder_register' | 'certificate_of_incumbency' | 'flow_of_funds' | 'proof_of_nature_of_business' | 'compliance_screening' | 'government_issued_id' | 'passport' | 'drivers_licence_front' | 'drivers_licence_back' | 'identity_card_front' | 'identity_card_back' | 'selfie' | 'proof_of_address' | 'ubo_source_of_funds' | 'tax_document' | 'licensed_vendors_attestation' | 'proof_of_licensure' | 'proof_of_verification' | 'supplemental' | 'other', required
  - `owner` string, nullable: `customer` (default) or `person` — whose document this is.
  - `person_id` string, uuid, nullable: Associated-person id; required when `owner=person`.
  - `proof_of_address_type` 'utility_bill' | 'bank_statement' | 'rental_agreement' | 'tax_document' | 'government_correspondence': What a proof of address is. Declared with the upload, because each verification review files a proof of address under one of these and nothing else about the file says which.
  - `purpose` string, nullable: `rfi_answer` when the file answers an open request for information. The request names the file, so an `other` upload needs no `description`.

## Response `200`

The stored document's metadata, discriminated on `type`.

- union
  - object
    - `document` KycDocumentRef, required: Metadata-rich document reference returned by the customer documents endpoints for individuals.
      - `content_type` string, required
      - `deleted_at` string, date-time, nullable: When the document was soft-deleted, if it has been. Only ever populated on the internal admin documents view; the partner list omits soft-deleted documents entirely, so this is always absent there.
      - `description` string, nullable: User-supplied label; only ever set for multi-instance `other` docs.
      - `document_id` string, uuid, required
      - `filename` string, required
      - `kind` string, required
      - `proof_of_address_type` 'utility_bill' | 'bank_statement' | 'rental_agreement' | 'tax_document' | 'government_correspondence': What a proof of address is. Declared with the upload, because each verification review files a proof of address under one of these and nothing else about the file says which.
      - `size_bytes` integer, required
      - `uploaded_at` string, date-time, required
    - `type` 'individual', required
  - object
    - `document` KybDocumentRef, required: Metadata-rich document reference returned by the customer documents endpoints for businesses.
      - `content_type` string, required
      - `deleted_at` string, date-time, nullable: When the document was soft-deleted, if it has been. Only ever populated on the internal admin documents view; the partner list omits soft-deleted documents entirely, so this is always absent there.
      - `description` string, nullable: User-supplied label; only ever set for multi-instance `other` docs.
      - `document_id` string, uuid, required
      - `filename` string, required
      - `kind` 'business_formation' | 'articles_of_association' | 'memorandum_of_association' | 'dba_registration' | 'bank_statement' | 'ubo_bank_statement' | 'ownership_information' | 'shareholder_register' | 'certificate_of_incumbency' | 'flow_of_funds' | 'proof_of_nature_of_business' | 'compliance_screening' | 'government_issued_id' | 'passport' | 'drivers_licence_front' | 'drivers_licence_back' | 'identity_card_front' | 'identity_card_back' | 'selfie' | 'proof_of_address' | 'ubo_source_of_funds' | 'tax_document' | 'licensed_vendors_attestation' | 'proof_of_licensure' | 'proof_of_verification' | 'supplemental' | 'other', required
      - `proof_of_address_type` 'utility_bill' | 'bank_statement' | 'rental_agreement' | 'tax_document' | 'government_correspondence': What a proof of address is. Declared with the upload, because each verification review files a proof of address under one of these and nothing else about the file says which.
      - `size_bytes` integer, required
      - `uploaded_at` string, date-time, required
    - `type` 'business', required

## Other responses

- `400`: Missing/invalid form field, unsupported file type, or a PDF longer than 200 pages.
- `401`: Missing or invalid API key.
- `404`: Customer not found.
- `413`: File exceeds the upload ceiling.

---

[API](https://skmtc.dev/seismic/apis/seismic-orchestration-api.md) - [All operations](https://skmtc.dev/seismic/apis/seismic-orchestration-api/llms.txt) - [OpenAPI document](https://skmtc.dev/seismic/apis/seismic-orchestration-api/revisions/08ada1f159fa?raw)