Agent Management12

Agent Operations13

API Tokens4

Cards6

Contact Verification4

Cross-Currency Transfers6

Customers9

Discoveries1

Documents5

Embedded Wallet Auth12

Exchange Rates1

External Accounts12

Internal Accounts5

Invitations4

KYC/KYB Verifications9

Platform Configuration2

Same-Currency Transfers2

Sandbox20

Stablecoins12

Strong Customer Authentication16

Transactions6

Webhooks

Webhooks13

Documents

Replace a document

Changed on Sep 15, 2026

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

put/documents/{documentId}

Request

Base URL: https://api.lightspark.com/grid/2025-10-13
URL: https://api.lightspark.com/grid/2025-10-13/documents/{documentId}
Auth: HTTP basic

Path parameters

documentIdstring required

Document ID

Response

Document replaced successfully

idstring required

Unique identifier for this document

documentHolderstring required

ID of the entity that owns this document. Can be a Customer ID or a BeneficialOwner ID.

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.

countrystring required

Country that issued the document (ISO 3166-1 alpha-2)

documentNumberstring

Document identification number (e.g., passport number)

issuingAuthoritystring

Name of the government agency or organization that issued the document

fileNamestring required

Original file name of the uploaded document

createdAtstring date-time required

When this document was uploaded

updatedAtstring date-time

When this document was last updated

Example response

{
  "id": "Document:019542f5-b3e7-1d02-0000-000000000001",
  "documentHolder": "BeneficialOwner:019542f5-b3e7-1d02-0000-000000000001",
  "documentType": "PASSPORT",
  "side": "FRONT",
  "country": "US",
  "documentNumber": "A12345678",
  "issuingAuthority": "U.S. Department of State",
  "fileName": "passport_scan.pdf",
  "createdAt": "2025-10-03T12:00:00Z",
  "updatedAt": "2025-10-03T12:00:00Z"
}

Changes

Sep 15, 20260bea6bdd0b0b Revision changes
- warning
  the //// request property's maxLength was set to 100
- warning
  the //// request property's maxLength was set to 255
Sep 15, 20263966e5d38aad Revision changes
- breaking
  removed the required property from the response with the status
- breaking
  removed the required property from the response with the status
- breaking
  removed the required property from the response with the status
- breaking
  removed the required property from the response with the status
- breaking
  removed the required property from the response with the status
- breaking
  removed the required property from the response with the status
- breaking
  removed the required property from the response with the status
- breaking
  removed the required property from the response with the status
- breaking
  removed the required property from the response with the status
- breaking
  removed the required property from the response with the status
- warning
  added the new ACCOUNT_NOT_FOUND enum value to the response property for the response status
- warning
  added the new AUTH_METHOD_NOT_FOUND enum value to the response property for the response status
- warning
  added the new CUSTOMER_NOT_FOUND enum value to the response property for the response status
- warning
  added the new DOCUMENT_HOLDER_NOT_FOUND enum value to the response property for the response status
- warning
  added the new INSUFFICIENT_FUNDS enum value to the response property for the response status
- warning
  added the new NOT_FOUND enum value to the response property for the response status
- warning
  added the new PAYMENT_URL_NOT_FOUND enum value to the response property for the response status
- warning
  added the new PLATFORM_NOT_FOUND enum value to the response property for the response status
- warning
  added the new QUOTE_EXPIRED enum value to the response property for the response status
- warning
  added the new QUOTE_RATE_UNAVAILABLE enum value to the response property for the response status
- warning
  added the new REQUEST_NOT_FOUND enum value to the response property for the response status
- warning
  added the new SESSION_NOT_FOUND enum value to the response property for the response status
- warning
  added the new STABLECOIN_AMOUNT_NOT_REPRESENTABLE enum value to the response property for the response status
- warning
  added the new STABLECOIN_BURN_SOURCE_NOT_SUPPORTED enum value to the response property for the response status
- warning
  added the new STABLECOIN_EXTERNAL_ACCOUNT_LINK_FAILED enum value to the response property for the response status
- warning
  added the new STABLECOIN_EXTERNAL_ACCOUNT_LINK_METHOD_REQUIRED enum value to the response property for the response status
- warning
  added the new STABLECOIN_EXTERNAL_ACCOUNT_NOT_FOUND enum value to the response property for the response status
- warning
  added the new STABLECOIN_EXTERNAL_ACCOUNT_NOT_LINKED enum value to the response property for the response status
- warning
  added the new STABLECOIN_EXTERNAL_ACCOUNT_NOT_SUPPORTED enum value to the response property for the response status
- warning
  added the new STABLECOIN_EXTERNAL_ACCOUNT_PROVIDER_LINK_FAILED enum value to the response property for the response status
- warning
  added the new STABLECOIN_EXTERNAL_ACCOUNT_PROVIDER_LINK_REQUIRED enum value to the response property for the response status
- warning
  added the new STABLECOIN_GRID_OPERATIONS_NOT_ENABLED enum value to the response property for the response status
- warning
  added the new STABLECOIN_NOT_FOUND enum value to the response property for the response status
- warning
  added the new STABLECOIN_NOT_PROVISIONED enum value to the response property for the response status
- warning
  added the new STABLECOIN_OPERATION_NOT_FOUND enum value to the response property for the response status
- warning
  added the new STABLECOIN_OPERATION_NOT_SUPPORTED enum value to the response property for the response status
- warning
  added the new STABLECOIN_PROVIDER_ERROR enum value to the response property for the response status
- warning
  added the new STABLECOIN_PROVIDER_SOURCE_NOT_LINKED enum value to the response property for the response status
- warning
  added the new STABLECOIN_VERIFICATION_FAILED enum value to the response property for the response status
- warning
  added the new VERIFICATION_NOT_FOUND enum value to the response property for the response status
- info
  added the required property to the response with the status
- info
  added the required property to the response with the status
- info
  added the required property to the response with the status
- info
  added the required property to the response with the status
- info
  added the required property to the response with the status

Operation history (8 revisions)