---
title: "Replace a document"
method: PUT
path: "/documents/{documentId}"
tags: ["Documents"]
---

# Replace a document

`PUT /documents/{documentId}`

Replace an existing document with a new file and/or updated metadata.
The request must use multipart/form-data.

Use this when a stored document was rejected during review, which arrives
as an entry in the verification's `errors` array rather than as an error
on upload. Replacing marks the previously submitted file inactive, which
a second `POST /documents` would not do: that leaves the rejected file
active alongside the new one, and the rejection can carry. Call
`POST /verifications` afterwards to start a new review, since existing
errors persist until a new review produces a new verdict.

A file rejected on upload with `422 DOCUMENT_REJECTED` never creates a
document, so there is nothing to replace. Retry those with
`POST /documents`.

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

## Path parameters

- `documentId` string, required

## Response `200`

Document replaced 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 not found
- `422` — The verification provider rejected the file. `precheckErrors` names each problem it found. The stored document keeps its previous file and metadata, so retry with a corrected file.
- `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/:documentId/put.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)