---
title: "Upload a document"
method: POST
path: "/documents"
tags: ["Documents"]
---

# Upload a document

`POST /documents`

Upload a verification document for a customer or beneficial owner.
The request must use multipart/form-data with the file in the `file` field
and metadata in the remaining fields.

Supported file types: `application/pdf`, `image/jpeg`, and `image/png`.
Grid matches on the `Content-Type` of the multipart part, not the file
extension. Any other type, and any file over 10 MB, returns
`400 INVALID_INPUT`.

Grid forwards the file to its verification provider, which screens it as
the request is handled and can reject it with `422 DOCUMENT_REJECTED`.
To pass that screen, a photo or scan of a document must:

- show the whole document, with all four corners inside the frame and
  nothing overlapping an edge
- be in focus and free of glare, so every field and the machine-readable
  zone can be read
- be in color, not a black-and-white copy
- be a photo or scan of the physical document, not a screen capture, and
  not retouched in an image editor
- be unexpired

## Response `201`

Document uploaded successfully

- Document
  - `id` string, required — Unique identifier for this document
  - `documentHolder` string, required — ID of the entity that owns this document. Can be a Customer ID or a BeneficialOwner ID.
  - `documentType` 'PASSPORT' | 'DRIVERS_LICENSE' | 'NATIONAL_ID' | 'PROOF_OF_ADDRESS' | 'BANK_STATEMENT' | 'TAX_RETURN' | 'CERTIFICATE_OF_INCORPORATION' | 'ARTICLES_OF_INCORPORATION' | 'ARTICLES_OF_ASSOCIATION' | 'STATE_REGISTRY_EXCERPT' | 'GOOD_STANDING_CERTIFICATE' | 'INFORMATION_STATEMENT' | 'INCUMBENCY_CERTIFICATE' | 'BUSINESS_LICENSE' | 'SHAREHOLDER_REGISTER' | 'POWER_OF_ATTORNEY' | 'UTILITY_BILL' | 'ELECTRICITY_BILL' | 'RENT_OR_LEASE_AGREEMENT' | 'DIRECTOR_REGISTRY' | 'TRUST_AGREEMENT' | 'STATE_COMPANY_REGISTRY' | 'PARTNERSHIP_CONTROL_AGREEMENT' | 'PARTNERSHIP_AGREEMENT' | 'SELFIE' | 'OTHER', required — Type of identity or business verification document. Document types are grouped by verification category: **Identity** — PASSPORT, DRIVERS_LICENSE, NATIONAL_ID **Business — Legal presence** — CERTIFICATE_OF_INCORPORATION, ARTICLES_OF_INCORPORATION, ARTICLES_OF_ASSOCIATION, STATE_REGISTRY_EXCERPT **Business — Control structure** — DIRECTOR_REGISTRY, TRUST_AGREEMENT, STATE_COMPANY_REGISTRY, PARTNERSHIP_CONTROL_AGREEMENT **Business — Ownership structure** — SHAREHOLDER_REGISTER, TRUST_AGREEMENT, PARTNERSHIP_AGREEMENT **Proof of address** — UTILITY_BILL, RENT_OR_LEASE_AGREEMENT, ELECTRICITY_BILL, BANK_STATEMENT, TAX_RETURN
  - `side` 'FRONT' | 'BACK' — Which side of the document this upload represents. Relevant for two-sided documents like driver's licenses or national IDs.
  - `country` string, required — Country that issued the document (ISO 3166-1 alpha-2)
  - `documentNumber` string — Document identification number (e.g., passport number)
  - `issuingAuthority` string — Name of the government agency or organization that issued the document
  - `fileName` string, required — Original file name of the uploaded document
  - `createdAt` string, date-time, required — When this document was uploaded
  - `updatedAt` string, date-time — When this document was last updated

## Other responses

- `400` — Bad request - Invalid file type, size, or parameters
- `401` — Unauthorized
- `404` — Document holder not found
- `422` — The verification provider rejected the file. `precheckErrors` names each problem it found. No document is created, so re-upload a corrected file with `POST /documents`.
- `500` — Internal service error

## Changes

- **2026-08-27** `9045e9cc4e51` — 1 info
  - added the non-success response with the status `422`
- **2026-08-14** `aaa1fb8782c8` — 1 warning
  - added the new `EXTERNAL_ACCOUNT_VERIFICATION_REQUIRED` enum value to the `code` response property for the response status `400`
- **2026-08-13** `df12ec487f0e` — 1 warning
  - added the new `TRANSACTION_SIZE_LIMIT_EXCEEDED` enum value to the `code` response property for the response status `400`
- **2026-08-11** `b06902b6595a` — 1 warning
  - added the new `CARDHOLDER_KYC_NOT_APPROVED` enum value to the `code` response property for the response status `400`
- **2026-08-06** `526036c12609` — 1 warning
  - added the new `END_USER_TERMS_VERSION_NOT_FOUND` enum value to the `code` response property for the response status `400`

[Full history](https://skmtc.dev/stainless-api/apis/grid-api/changes/documents/post.md)

---

[API](https://skmtc.dev/stainless-api/apis/grid-api.md) · [All operations](https://skmtc.dev/stainless-api/apis/grid-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/stainless-api/grid-api/revisions/2ec84c06fbec/schema)