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.

POST /verifications

Submit customer for verification

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"
}
'

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_DOCUMENT",
      "acceptedDocumentTypes": [
        "PROOF_OF_ADDRESS",
        "UTILITY_BILL",
        "BANK_STATEMENT"
      ],
      "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

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"