LIlightsparkdev
Documents

Upload a document

Changed on

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.

Every upload requires file, documentType, country, and documentHolder. Identity documents require more fields:

documentTypeAlso requiredside
PASSPORTdocumentNumber, issuingAuthorityNot allowed
DRIVERS_LICENSEdocumentNumber, issuingAuthorityRequired
NATIONAL_IDdocumentNumber, issuingAuthorityRequired
RESIDENCE_PERMITdocumentNumber, issuingAuthorityRequired
Any other typeNoneOptional

Where side is required, upload the FRONT and BACK as two separate documents. A driver's license issued in Brazil (country is BR) is the exception: upload it as one image and omit side.

A missing required field, or a side that isn't allowed, returns 400 INVALID_INPUT.

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
post/documents

Request

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

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.

documentHolderstring required

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

Example request

{
  "documentType": "PASSPORT",
  "side": "FRONT",
  "country": "US",
  "documentNumber": "A12345678",
  "issuingAuthority": "U.S. Department of State",
  "documentHolder": "BeneficialOwner:019542f5-b3e7-1d02-0000-000000000001"
}

Response

Document uploaded 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