KYC/KYB Verifications

Submit customer for verification

Changed on

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

Request

  • Base URL: https://api.lightspark.com/grid/2025-10-13
  • URL: https://api.lightspark.com/grid/2025-10-13/verifications
  • Auth: HTTP basic

Request body

customerIdstring required

The ID of the customer to verify

Example request

{
  "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001"
}

Response

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

idstring required

Unique identifier for this verification

customerIdstring required

The ID of the customer being verified

verificationStatus'RESOLVE_ERRORS' | 'PENDING_MANUAL_REVIEW' | 'IN_PROGRESS' | 'APPROVED' | 'REJECTED' | 'READY_FOR_VERIFICATION' required

Current status of the KYC/KYB verification

createdAtstring date-time required

When this verification was created

updatedAtstring date-time

When this verification was last updated

Example response

{
  "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",
      "acceptedDocumentTypes": [
        "PASSPORT"
      ],
      "reason": "Business address line 1 is required"
    }
  ],
  "createdAt": "2025-10-03T12:00:00Z",
  "updatedAt": "2025-10-03T12:00:00Z"
}

Changes

  • 3966e5d38aadRevision changes
    • breaking

      removed the required property from the response with the status

    • breaking

      removed the required property from the response with the status

    • breaking

      removed the required property from the response with the status

    • breaking

      removed the required property from the response with the status

    • breaking

      removed the required property from the response with the status

    • breaking

      removed the required property from the response with the status

    • breaking

      removed the required property from the response with the status

    • breaking

      removed the required property from the response with the status

    • warning

      added the new ACCOUNT_NOT_FOUND enum value to the response property for the response status

    • warning

      added the new AUTH_METHOD_NOT_FOUND enum value to the response property for the response status

    • warning

      added the new CUSTOMER_NOT_FOUND enum value to the response property for the response status

    • warning

      added the new DOCUMENT_HOLDER_NOT_FOUND enum value to the response property for the response status

    • warning

      added the new INSUFFICIENT_FUNDS enum value to the response property for the response status

    • warning

      added the new NOT_FOUND enum value to the response property for the response status

    • warning

      added the new PAYMENT_URL_NOT_FOUND enum value to the response property for the response status

    • warning

      added the new PLATFORM_NOT_FOUND enum value to the response property for the response status

    • warning

      added the new QUOTE_EXPIRED enum value to the response property for the response status

    • warning

      added the new QUOTE_RATE_UNAVAILABLE enum value to the response property for the response status

    • warning

      added the new REQUEST_NOT_FOUND enum value to the response property for the response status

    • warning

      added the new SESSION_NOT_FOUND enum value to the response property for the response status

    • warning

      added the new STABLECOIN_AMOUNT_NOT_REPRESENTABLE enum value to the response property for the response status

    • warning

      added the new STABLECOIN_BURN_SOURCE_NOT_SUPPORTED enum value to the response property for the response status

    • warning

      added the new STABLECOIN_EXTERNAL_ACCOUNT_LINK_FAILED enum value to the response property for the response status

    • warning

      added the new STABLECOIN_EXTERNAL_ACCOUNT_LINK_METHOD_REQUIRED enum value to the response property for the response status

    • warning

      added the new STABLECOIN_EXTERNAL_ACCOUNT_NOT_FOUND enum value to the response property for the response status

    • warning

      added the new STABLECOIN_EXTERNAL_ACCOUNT_NOT_LINKED enum value to the response property for the response status

    • warning

      added the new STABLECOIN_EXTERNAL_ACCOUNT_NOT_SUPPORTED enum value to the response property for the response status

    • warning

      added the new STABLECOIN_EXTERNAL_ACCOUNT_PROVIDER_LINK_FAILED enum value to the response property for the response status

    • warning

      added the new STABLECOIN_EXTERNAL_ACCOUNT_PROVIDER_LINK_REQUIRED enum value to the response property for the response status

    • warning

      added the new STABLECOIN_GRID_OPERATIONS_NOT_ENABLED enum value to the response property for the response status

    • warning

      added the new STABLECOIN_NOT_FOUND enum value to the response property for the response status

    • warning

      added the new STABLECOIN_NOT_PROVISIONED enum value to the response property for the response status

    • warning

      added the new STABLECOIN_OPERATION_NOT_FOUND enum value to the response property for the response status

    • warning

      added the new STABLECOIN_OPERATION_NOT_SUPPORTED enum value to the response property for the response status

    • warning

      added the new STABLECOIN_PROVIDER_ERROR enum value to the response property for the response status

    • warning

      added the new STABLECOIN_PROVIDER_SOURCE_NOT_LINKED enum value to the response property for the response status

    • warning

      added the new STABLECOIN_VERIFICATION_FAILED enum value to the response property for the response status

    • warning

      added the new VERIFICATION_NOT_FOUND enum value to the response property for the response status

    • info

      added the required property to the response with the status

    • info

      added the required property to the response with the status

    • info

      added the required property to the response with the status

    • info

      added the required property to the response with the status

  • aaa1fb8782c8Revision changes
    • warning

      added the new EXTERNAL_ACCOUNT_VERIFICATION_REQUIRED enum value to the response property for the response status