LIlightsparkdev
Documents

Replace a document

Changed on

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.

The request follows the same per-type field rules as POST /documents, except that documentHolder isn't sent. Grid overwrites every metadata field with the values in this request, so resend documentNumber, issuingAuthority, and side even if they haven't changed.

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

Request body multipart/form-data

filestring binary required

The document file. Grid accepts three formats, matched on the Content-Type of the multipart part rather than the file extension: application/pdf, image/jpeg, and image/png. Any other type, including image/heic, image/webp, and image/tiff, returns 400 INVALID_INPUT. The file must be 10 MB or smaller.

documentType'PASSPORT' | 'DRIVERS_LICENSE' | 'NATIONAL_ID' | 'RESIDENCE_PERMIT' | '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, RESIDENCE_PERMIT 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 a two-sided document, such as a driver's license or national ID, an image shows.

countrystring required

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

documentNumberstring

Identification number printed on the document, such as a passport number. Required when documentType is PASSPORT, DRIVERS_LICENSE, NATIONAL_ID, or RESIDENCE_PERMIT.

issuingAuthoritystring

Name of the government agency or organization that issued the document. Required when documentType is PASSPORT, DRIVERS_LICENSE, NATIONAL_ID, or RESIDENCE_PERMIT.

Example request

{
  "documentType": "PASSPORT",
  "side": "FRONT",
  "country": "US",
  "documentNumber": "A12345678",
  "issuingAuthority": "U.S. Department of State"
}

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.

documentType'PASSPORT' | 'DRIVERS_LICENSE' | 'NATIONAL_ID' | 'RESIDENCE_PERMIT' | '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, RESIDENCE_PERMIT 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 a two-sided document, such as a driver's license or national ID, an image shows.

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

  • 9e646a130ea0Revision changes
    • warning

      added the new RESIDENCE_PERMIT enum value to the response property for the response status

    • info

      added the new RESIDENCE_PERMIT enum value to the request property ////

  • d996ddfb9d2bRevision changes
    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status