cURL

curl --request POST \
  --url https://api.lightspark.com/grid/2025-10-13/verifications \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001"
}
'

import LightsparkGrid from '@lightsparkdev/grid';

const client = new LightsparkGrid({
  username: process.env['GRID_CLIENT_ID'], // This is the default and can be omitted
  password: process.env['GRID_CLIENT_SECRET'], // This is the default and can be omitted
});

const verification = await client.verifications.submit({
  customerId: 'Customer:019542f5-b3e7-1d02-0000-000000000001',
});

console.log(verification.id);

package com.lightspark.grid.example

import com.lightspark.grid.client.LightsparkGridClient
import com.lightspark.grid.client.okhttp.LightsparkGridOkHttpClient
import com.lightspark.grid.models.verifications.Verification
import com.lightspark.grid.models.verifications.VerificationRequest

fun main() {
    val client: LightsparkGridClient = LightsparkGridOkHttpClient.fromEnv()

    val params: VerificationRequest = VerificationRequest.builder()
        .customerId("Customer:019542f5-b3e7-1d02-0000-000000000001")
        .build()
    val verification: Verification = client.verifications().submit(params)
}

{
  "id": "Verification:019542f5-b3e7-1d02-0000-000000000001",
  "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001",
  "verificationStatus": "RESOLVE_ERRORS",
  "errors": [
    {
      "resourceId": "Customer:019542f5-b3e7-1d02-0000-000000000001",
      "type": "MISSING_FIELD",
      "field": "customer.address.line1",
      "reason": "Business address line 1 is required"
    },
    {
      "resourceId": "Customer:019542f5-b3e7-1d02-0000-000000000001",
      "type": "MISSING_PROOF_OF_ADDRESS_DOCUMENT",
      "acceptedDocumentTypes": [
        "PROOF_OF_ADDRESS"
      ],
      "reason": "Proof of address document is required"
    },
    {
      "resourceId": "BeneficialOwner:019542f5-b3e7-1d02-0000-000000000002",
      "type": "MISSING_FIELD",
      "field": "personalInfo.birthDate",
      "reason": "Date of birth is required for beneficial owners"
    }
  ],
  "createdAt": "2025-10-03T12:00:00Z"
}

KYC/KYB Verifications

Submit customer for verification

Trigger KYC (individual) or KYB (business) verification for a customer. The response indicates whether all required information has been provided. If data is missing, the errors array describes exactly what needs to be supplied before verification can proceed.

Call this endpoint again after resolving errors to re-submit.

What to collect for KYB

Before submitting a BUSINESS customer, collect the following via POST /customers, POST /beneficial-owners, and POST /documents:

Business identifying information

Entity full legal name
Doing Business As (DBA) name, if applicable
Physical address — principal place of business
Countries of operation
Identification number — U.S. taxpayer identification number, or, for a foreign business without one, alternative government-issued documentation certifying the existence of the business

Ownership and control structure — collected for one control person (an individual with significant responsibility to control, manage, or direct the legal entity) and all beneficial owners (every individual who owns 25% or more, directly or indirectly). For each, provide:

Full name
Date of birth
Address
Identification number:
- U.S. persons — SSN or ITIN
- Non-U.S. persons — one or more of: ITIN, passport (with country of issuance), alien identification card, or another government-issued photo ID evidencing nationality or residence

Required documents

Company formation and existence documents (certificate of incorporation, articles of association, etc.)
Proof of ownership and control structure (organization and ownership chart, shareholder agreements, operating agreements, register of members, or certification of controlling person and beneficial owners)
Proof of address dated within the last 3 months (utility bill, bank statement, lease agreement, or official correspondence)
Tax ID or equivalent identifying-number documents
For non-U.S. beneficial owners — passport plus one additional government-issued ID

POST

verifications

cURL

curl --request POST \
  --url https://api.lightspark.com/grid/2025-10-13/verifications \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001"
}
'

import LightsparkGrid from '@lightsparkdev/grid';

const client = new LightsparkGrid({
  username: process.env['GRID_CLIENT_ID'], // This is the default and can be omitted
  password: process.env['GRID_CLIENT_SECRET'], // This is the default and can be omitted
});

const verification = await client.verifications.submit({
  customerId: 'Customer:019542f5-b3e7-1d02-0000-000000000001',
});

console.log(verification.id);

package com.lightspark.grid.example

import com.lightspark.grid.client.LightsparkGridClient
import com.lightspark.grid.client.okhttp.LightsparkGridOkHttpClient
import com.lightspark.grid.models.verifications.Verification
import com.lightspark.grid.models.verifications.VerificationRequest

fun main() {
    val client: LightsparkGridClient = LightsparkGridOkHttpClient.fromEnv()

    val params: VerificationRequest = VerificationRequest.builder()
        .customerId("Customer:019542f5-b3e7-1d02-0000-000000000001")
        .build()
    val verification: Verification = client.verifications().submit(params)
}

{
  "id": "Verification:019542f5-b3e7-1d02-0000-000000000001",
  "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001",
  "verificationStatus": "RESOLVE_ERRORS",
  "errors": [
    {
      "resourceId": "Customer:019542f5-b3e7-1d02-0000-000000000001",
      "type": "MISSING_FIELD",
      "field": "customer.address.line1",
      "reason": "Business address line 1 is required"
    },
    {
      "resourceId": "Customer:019542f5-b3e7-1d02-0000-000000000001",
      "type": "MISSING_PROOF_OF_ADDRESS_DOCUMENT",
      "acceptedDocumentTypes": [
        "PROOF_OF_ADDRESS"
      ],
      "reason": "Proof of address document is required"
    },
    {
      "resourceId": "BeneficialOwner:019542f5-b3e7-1d02-0000-000000000002",
      "type": "MISSING_FIELD",
      "field": "personalInfo.birthDate",
      "reason": "Date of birth is required for beneficial owners"
    }
  ],
  "createdAt": "2025-10-03T12:00:00Z"
}

Authorizations

Authorization

string

header

required

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

Body

application/json

customerId

string

required

The ID of the customer to verify

Example:

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

Response

Verification status returned. Check verificationStatus and errors to determine next steps.

string

required

Unique identifier for this verification

Example:

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

customerId

string

required

The ID of the customer being verified

Example:

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

verificationStatus

enum<string>

required

Current status of the KYC/KYB verification

Available options:

RESOLVE_ERRORS,

PENDING_MANUAL_REVIEW,

IN_PROGRESS,

APPROVED,

REJECTED,

READY_FOR_VERIFICATION

Example:

"RESOLVE_ERRORS"

errors

object[]

required

List of issues preventing verification from proceeding. Empty when verificationStatus is APPROVED or IN_PROGRESS.

Show child attributes

createdAt

string<date-time>

required

When this verification was created

Example:

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

updatedAt

string<date-time>

When this verification was last updated

Example:

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

List verifications

Get a verification

⌘I

Using the API

API documentation

Submit customer for verification

What to collect for KYB

Authorizations

Body

Response