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.

Supported file types: PDF, JPEG, PNG. Maximum file size: 10 MB.

POST /documents

cURL

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 (PDF, JPEG, or PNG, max 10 MB)

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

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

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 (for two-sided documents like driver's licenses)

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"

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 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, 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"