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

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)
}

200

missingInfo

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

200

application/json

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

id · 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"