Upload a document

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:

documentType	Also required	side
PASSPORT	documentNumber, issuingAuthority	Not allowed
DRIVERS_LICENSE	documentNumber, issuingAuthority	Required
NATIONAL_ID	documentNumber, issuingAuthority	Required
RESIDENCE_PERMIT	documentNumber, issuingAuthority	Required
Any other type	None	Optional

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

Upload a document

cURL

curl --request POST \
  --url https://api.lightspark.com/grid/2025-10-13/documents \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: multipart/form-data' \
  --form file=@example-file \
  --form documentType=PASSPORT \
  --form country=US \
  --form documentHolder=BeneficialOwner:019542f5-b3e7-1d02-0000-000000000001 \
  --form side=FRONT \
  --form documentNumber=A12345678 \
  --form 'issuingAuthority=U.S. Department of State'

201

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

Authorizations

Authorization · string · header · required

API token authentication using format <api token id>:<api client secret>

Body

multipart/form-data

file · file · 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 · enum<string> · 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

Available options: 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

Example:

"PASSPORT"

country · string · required

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

Example:

"US"

documentHolder · string · required

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

Example:

"BeneficialOwner:019542f5-b3e7-1d02-0000-000000000001"

side · enum<string>

Which side of the document this image shows. Required when documentType is DRIVERS_LICENSE, NATIONAL_ID, or RESIDENCE_PERMIT: upload the FRONT and BACK as two separate documents. A PASSPORT, or a DRIVERS_LICENSE issued in Brazil (country is BR), is a single image: sending side for either returns 400 INVALID_INPUT. Optional for all other document types.

Available options: FRONT, BACK

Example:

"FRONT"

documentNumber · string

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

Maximum string length: 100

Example:

"A12345678"

issuingAuthority · string

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

Maximum string length: 255

Example:

"U.S. Department of State"

Response

201

application/json

Document uploaded successfully

id · string · required

Unique identifier for this document

Example:

"Document:019542f5-b3e7-1d02-0000-000000000001"

documentHolder · string · required

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

Example:

"BeneficialOwner:019542f5-b3e7-1d02-0000-000000000001"

documentType · enum<string> · 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

Available options: 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

Example:

"PASSPORT"

country · string · required

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

Example:

"US"

fileName · string · required

Original file name of the uploaded document

Example:

"passport_scan.pdf"

createdAt · string<date-time> · required

When this document was uploaded

Example:

"2025-10-03T12:00:00Z"

side · enum<string>

Which side of the document this upload represents. Relevant for two-sided documents like driver's licenses or national IDs.

Available options: FRONT, BACK

Example:

"FRONT"

documentNumber · string

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

Example:

"A12345678"

issuingAuthority · string

Name of the government agency or organization that issued the document

Example:

"U.S. Department of State"

updatedAt · string<date-time>

When this document was last updated

Example:

"2025-10-03T12:00:00Z"