Configuring Customers

Customers must complete identity verification before processing conversions. The required information varies based on your platform’s regulatory status.

Regulated Platforms

Regulated platforms have lighter KYC requirements since they handle compliance verification internally.

The KYC/KYB flow allows you to onboard customers through direct API calls.Regulated financial institutions can:

Direct API Onboarding: Create customers directly via API calls with minimal verification
Internal KYC/KYB: Handle identity verification through your own compliance systems
Reduced Documentation: Only provide essential customer information required by your payment counterparty or service provider.
Faster Onboarding: Streamlined process for known, verified customers

Creating Customers via Direct API

For regulated platforms, you can create customers directly through the API without requiring external KYC verification:To register a new customer in the system, use the POST /customers endpoint:

curl -X POST "https://api.lightspark.com/grid/2025-10-13/customers" \
  -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "platformCustomerId": "customer_12345",
    "customerType": "INDIVIDUAL",
    "fullName": "Jane Doe",
    "birthDate": "1992-03-25",
    "nationality": "US",
    "address": {
      "line1": "123 Pine Street",
      "city": "Seattle",
      "state": "WA",
      "postalCode": "98101",
      "country": "US"
    }
  }'

The examples below show a more comprehensive set of data. Not all fields are strictly required by the API for customer creation itself, but become necessary based on currency and UMA provider requirements if using UMA.

Individual customer
Business Customer

{
  "platformCustomerId": "9f84e0c2a72c4fa",
  "customerType": "INDIVIDUAL",
  "fullName": "John Sender",
  "birthDate": "1985-06-15",
  "address": {
    "line1": "Paseo de la Reforma 222",
    "line2": "Piso 15",
    "city": "Ciudad de México",
    "state": "Ciudad de México",
    "postalCode": "06600",
    "country": "MX"
  }
}

{
  "platformCustomerId": "b87d2e4a9c13f5b",
  "customerType": "BUSINESS",
  "businessInfo": {
    "legalName": "Acme Corporation",
    "country": "US",
    "registrationNumber": "789012345",
    "taxId": "123-45-6789",
    "incorporatedOn": "2018-03-14",
    "businessType": "INFORMATION"
  },
  "address": {
    "line1": "456 Oak Avenue",
    "line2": "Floor 12",
    "city": "Seattle",
    "state": "WA",
    "postalCode": "98101",
    "country": "US"
  }
}

Unregulated Platforms

Unregulated platforms rely on Grid to run KYC for individuals and KYB for businesses. You can onboard customers either through the hosted KYC/KYB link flow below, or by submitting customer data directly through the API. Both paths cover KYC and KYB, produce the same status transitions — on kycStatus for individuals, kybStatus for businesses — and emit the same CUSTOMER.KYC_* / CUSTOMER.KYB_* webhooks. You can also mix them: supply what you already hold through the API, then let the hosted flow collect the rest.

Either path works for unregulated platforms:

Hosted flow: Redirect customers to a Grid-hosted link (or embed the provider SDK). Covers individuals and businesses alike. Best when you want Grid to handle the entire collection UX.
Direct API onboarding: Collect customer information in your own UI and submit it via the API. For INDIVIDUAL customers (KYC), personal information goes through POST /customers. For BUSINESS customers (KYB), you also register beneficial owners via POST /beneficial-owners. Submit for review with POST /verifications.

Hosted KYC and KYB Link Flow

The hosted flow provides a secure, hosted interface where customers complete verification. It serves both customer types — there is no separate KYB link endpoint. POST /customers/{customerId}/kyc-link generates the link, and customerType selects which flow the provider runs:

INDIVIDUAL — identity verification (KYC), tracked on kycStatus.
BUSINESS — business verification (KYB), tracked on kybStatus. The applicant confirms the company details, uploads the formation, ownership, and proof-of-address documents, and declares the control person and every beneficial owner holding 25% or more.

The flow is two steps: create the customer with the information you have, then generate the link. The status starts at UNVERIFIED and moves to PENDING once the customer completes the flow and review begins.

1. Create the customer

Individual (KYC)
Business (KYB)

Supply at least customerType and any fields you already have.

curl -X POST "https://api.lightspark.com/grid/2025-10-13/customers" \
  -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "customerType": "INDIVIDUAL",
    "platformCustomerId": "9f84e0c2a72c4fa",
    "region": "US",
    "currencies": ["USD", "USDC"],
    "email": "jane.doe@example.com",
    "fullName": "Jane Doe"
  }'

customerType: BUSINESS requires these fields — the request fails without them:

Field	Notes
`businessInfo.legalName`	Full legal entity name
`businessInfo.country`	Country of incorporation, ISO 3166-1 alpha-2. Sets the applicant’s jurisdiction and the tax-ID format validated against
`businessInfo.taxId`	Validated against `businessInfo.country`
`businessInfo.incorporatedOn`	`YYYY-MM-DD`

curl -X POST "https://api.lightspark.com/grid/2025-10-13/customers" \
  -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "customerType": "BUSINESS",
    "platformCustomerId": "biz-acme-001",
    "region": "US",
    "currencies": ["USD", "USDC"],
    "email": "finance@acme.com",
    "businessInfo": {
      "legalName": "Acme Corporation, Inc.",
      "country": "US",
      "taxId": "47-1234567",
      "incorporatedOn": "2018-03-14",
      "registrationNumber": "5523041",
      "entityType": "LLC"
    }
  }'

Everything else is optional to the schema, but three groups matter in practice:

Contact channels — email and/or phoneNumber, plus businessInfo.primaryContactFirstName and primaryContactLastName, are required in regions that verify a named representative before verification begins (for example the EU).
Currency-driven fields — anything listed in providerRequiredCustomerFields for a currency the business will transact in.
Everything the review needs — address, registrationNumber, entityType, countriesOfOperation, businessType, purposeOfAccount, sourceOfFunds, and the expected-activity fields aren’t enforced at creation. Whatever you omit, the applicant is asked for in the flow.

Persist the returned id (the Grid customer ID) — you’ll need it for the next step.

Business information you supply is prefilled into the hosted flow, so send as much as you have — via POST /customers or a later PATCH /customers/{customerId} — before generating the link. Every field you pass is one the applicant doesn’t retype, and one fewer chance for their answer to diverge from your record.

2. Generate the link

curl -X POST "https://api.lightspark.com/grid/2025-10-13/customers/Customer:019542f5-b3e7-1d02-0000-000000000001/kyc-link" \
  -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "redirectUri": "https://yourapp.com/onboarding-complete"
  }'

Response:

{
  "kycUrl": "https://kyc.lightspark.com/onboard/abc123def456",
  "expiresAt": "2027-01-15T14:32:00Z",
  "provider": "SUMSUB",
  "token": "_act-sbx-jwt-eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

The response field is named kycUrl for both customer types; for a BUSINESS customer it opens the KYB flow. For providers that support direct SDK integration (currently SUMSUB), a token is also returned — pass it to the provider’s web SDK to embed verification in your own UI instead of redirecting. Both update the customer’s status identically.

The flow end to end

Create the customer

Call POST /customers with customerType and any pre-fill fields you have. The returned id is the customer’s Grid ID. Their status — kycStatus for an individual, kybStatus for a business — starts at UNVERIFIED, becomes PENDING while under review, and lands on APPROVED or REJECTED when the decision is made. (HOLD means the customer may be asked to supply more information.)

Verify contact channels (only where required)

Some regions (for example, the EU) require the customer’s email and/or phone to be verified before verification can begin. For a business customer, these are the primary contact’s details. When this applies, the customer carries a contactVerification object listing only the channels that are required — for example { "email": "PENDING", "phone": "PENDING" }, or just { "email": "PENDING" } if a provider requires email alone. When the object is absent, no contact verification is required and you can skip this step.For each channel that’s present, drive a send-then-confirm pair (the provider delivers a one-time code by email/SMS):

POST /customers/{customerId}/verify-email, then POST /customers/{customerId}/verify-email/confirm with { "code": "..." }
POST /customers/{customerId}/verify-phone, then POST /customers/{customerId}/verify-phone/confirm with { "code": "..." }

Re-POST the send endpoint to resend a code. Each channel moves PENDING → VERIFIED. (verify-email/verify-phone return 409 for a channel the provider doesn’t require.)

Generating the link before every present channel is VERIFIED returns 409.

Generate the link

Call POST /customers/{customerId}/kyc-link. Each call returns a fresh single-use kycUrl and expiresAt; previously-issued links remain single-use but aren’t invalidated.

The redirectUri you pass is embedded in the generated kycUrl and is used to automatically return the customer to your application after they complete verification.

Send the customer through verification

Redirect the customer to kycUrl, or — if you want to embed the flow directly — initialize the provider’s SDK with the returned token. A business applicant completes the company details, uploads the company documents, and declares the beneficial owners here.

The hosted URL is single-use and expires at expiresAt. If a customer needs to retry, call the endpoint again to generate a new link.

Track the decision

Reaching your redirectUri only means the customer finished the hosted flow — not that they were approved. Wait for the final decision in one of two ways:

Webhook (recommended): Subscribe to CUSTOMER.KYC_APPROVED / CUSTOMER.KYC_REJECTED (and CUSTOMER.KYB_APPROVED / CUSTOMER.KYB_REJECTED for business customers) to be notified when the customer reaches a terminal status. CUSTOMER.KYC_PENDING (and the KYB_PENDING sibling) also fires when the customer is submitted for review — subscribe to it as well if you want to surface an “under review” state to the customer.
Polling: Call GET /customers/{customerId} and inspect kycStatus (individuals) or kybStatus (businesses).

GET /verifications?customerId=... gives the finer-grained verificationStatus and errors array. That detail drives direct API onboarding; in the hosted flow the customer resolves it inside the flow, so integrate against kycStatus / kybStatus.

Handle completion

On APPROVED, the customer is ready to transact — proceed with account setup and unlock funding. On REJECTED, surface the appropriate next step (for example, regenerate the link or request manual review). While the status is PENDING, let the customer finish account setup but block funding and money movement.

Testing the business flow in sandbox: a businessInfo.registrationNumber not ending in 001, 002, or 003 auto-approves the customer on the spot, leaving the hosted flow nothing to verify — so it asks for no documents and no beneficial owners. Use a 003 suffix to exercise document and UBO collection. See Sandbox testing.

Direct API Onboarding

Prefer to collect identity information in your own UI and submit it to Grid yourself? Use the API directly instead of redirecting to a hosted link. The customer’s kycStatus transitions the same way and you receive the same CUSTOMER.KYC_APPROVED / CUSTOMER.KYC_REJECTED / CUSTOMER.KYC_PENDING (and CUSTOMER.KYB_* equivalents) webhooks.The shape of the flow depends on the customer type:

KYC (INDIVIDUAL customers) — supply the customer’s personal information through the customer endpoint. No beneficial owners are involved.
KYB (BUSINESS customers) — create the business customer, then register its beneficial owners, directors, and officers individually.

KYC (individual)
KYB (business)

Create the customer with personal information

Call POST /customers with customerType: INDIVIDUAL and the personal information collected from the customer (legal name, date of birth, address, nationality, etc.). The returned id is the customer’s Grid ID; kycStatus starts at UNVERIFIED and moves to PENDING once you submit for verification.

fullName must contain both a given name and a family name (for example, "Jane Doe"). The name is split into first/last for the verification provider, and a single-word name is rejected at submission.

curl -X POST "https://api.lightspark.com/grid/2025-10-13/customers" \
  -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "customerType": "INDIVIDUAL",
    "platformCustomerId": "9f84e0c2a72c4fa",
    "fullName": "Jane Doe",
    "birthDate": "1985-06-15",
    "nationality": "US",
    "email": "jane.doe@example.com",
    "address": {
      "line1": "123 Pine Street",
      "city": "Seattle",
      "state": "WA",
      "postalCode": "98101",
      "country": "US"
    }
  }'

Where the customer’s provider requires it (for example, EU customers), the customer carries a contactVerification object and their email and phone must be VERIFIED before you submit for verification. Drive each channel with the send-then-confirm pairs (verify-email / verify-email/confirm and verify-phone / verify-phone/confirm) described in the Hosted flow’s “Verify email and phone” step. When contactVerification is absent, no contact verification is required.

Upload the identity document

Individual verification requires an identity document — a PASSPORT (single image), or a DRIVERS_LICENSE / NATIONAL_ID (uploaded as separate FRONT and BACK images via the side field). Some jurisdictions or currencies also request additional documents such as proof of address. Upload each one with POST /documents using multipart/form-data; identity documents also require documentNumber and issuingAuthority.

curl -X POST "https://api.lightspark.com/grid/2025-10-13/documents" \
  -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET" \
  -F "documentHolder=Customer:019542f5-b3e7-1d02-0000-000000000001" \
  -F "documentType=PASSPORT" \
  -F "documentNumber=A12345678" \
  -F "issuingAuthority=U.S. Department of State" \
  -F "country=US" \
  -F "file=@./passport.jpg"

Submit for verification

Call POST /verifications to submit the customer for review. The response includes a verificationStatus. If anything is missing, verificationStatus is RESOLVE_ERRORS and the errors array describes exactly what to collect before retrying.

curl -X POST "https://api.lightspark.com/grid/2025-10-13/verifications" \
  -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001"
  }'

Submitted successfully:

{
  "id": "Verification:019542f5-b3e7-1d02-0000-000000000002",
  "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001",
  "verificationStatus": "IN_PROGRESS",
  "errors": [],
  "createdAt": "2025-10-03T12:00:00Z"
}

Blocked by missing data:

{
  "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_IDENTITY_DOCUMENT",
      "acceptedDocumentTypes": ["PASSPORT", "DRIVERS_LICENSE", "NATIONAL_ID"],
      "reason": "Identity document is required"
    }
  ],
  "createdAt": "2025-10-03T12:00:00Z"
}

Track the decision

Track terminal kycStatus transitions via the CUSTOMER.KYC_APPROVED / CUSTOMER.KYC_REJECTED webhook (recommended) or by polling GET /customers/{customerId}. CUSTOMER.KYC_PENDING also fires when the customer is submitted for review — subscribe to it if you want to surface an “under review” state. On APPROVED, unlock funding and money movement.

When Grid runs KYB for a business customer, the following information and documents are collected before onboarding completes. Use this list to plan what to gather from the business — provide it via POST /customers, POST /beneficial-owners, and POST /documents (or through the hosted flow).

Business identifying information

Entity full legal name
Doing Business As (DBA) name, if applicable
Physical address — the principal place of business, local office, or other physical location of the entity opening the account
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 — a single individual with significant responsibility to control, manage, or direct the legal entity, and
All beneficial owners — every individual who owns 25% or more of the legal entity, directly or indirectly.

For every such individual, provide:

Full name
Date of birth
Address
Identification number, by residency:
- U.S. persons — Social Security Number (SSN) or Individual Taxpayer Identification Number (ITIN)
- Non-U.S. persons — one or more of: ITIN, passport number with country of issuance, alien identification card number, or another government-issued document evidencing nationality or residence and bearing a photograph or similar safeguard

Required documents

Company formation and existence documents. For example:
- Certificate of incorporation
- Articles of association
Proof of ownership and control structure. For example:
- Corporate organization and ownership chart
- Shareholder agreements
- Operating agreements
- Register of members
- Certification of controlling person and beneficial owners
Proof of address, dated within the last 3 months. For example:
- Utility bill
- Bank statement
- Lease agreement
- Official correspondence
Tax ID or equivalent identifying-number documents
For non-U.S. beneficial owners — passport plus one additional government-issued ID. For example:
- National ID

Create the business customer

Call POST /customers with customerType: BUSINESS and the business information (legal name, country of incorporation, registration number, tax ID, registered address).

curl -X POST "https://api.lightspark.com/grid/2025-10-13/customers" \
  -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "customerType": "BUSINESS",
    "platformCustomerId": "b87d2e4a9c13f5b",
    "businessInfo": {
      "legalName": "Acme Corporation",
      "country": "US",
      "registrationNumber": "789012345",
      "taxId": "123-45-6789",
      "incorporatedOn": "2018-03-14",
      "businessType": "INFORMATION"
    },
    "address": {
      "line1": "456 Oak Avenue",
      "city": "Seattle",
      "state": "WA",
      "postalCode": "98101",
      "country": "US"
    }
  }'

Register each beneficial owner, director, or officer with POST /beneficial-owners. Each one is verified individually with their own personal information.

curl -X POST "https://api.lightspark.com/grid/2025-10-13/beneficial-owners" \
  -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001",
    "roles": ["DIRECTOR"],
    "ownershipPercentage": 40,
    "personalInfo": {
      "firstName": "Jane",
      "lastName": "Doe",
      "birthDate": "1985-06-15",
      "nationality": "US",
      "address": {
        "line1": "123 Pine Street",
        "city": "Seattle",
        "state": "WA",
        "postalCode": "98101",
        "country": "US"
      },
      "idType": "SSN",
      "identifier": "123-45-6789"
    }
  }'

Upload supporting documents

Upload business documents (registration, articles of incorporation) and any documents required for individual beneficial owners with POST /documents. Reference the company by customerId and each owner by beneficialOwnerId.

curl -X POST "https://api.lightspark.com/grid/2025-10-13/documents" \
  -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET" \
  -F "documentHolder=BeneficialOwner:019542f5-b3e7-1d02-0000-00000000abcd" \
  -F "documentType=PASSPORT" \
  -F "documentNumber=B98765432" \
  -F "issuingAuthority=U.S. Department of State" \
  -F "country=US" \
  -F "file=@./owner-passport.jpg"

Submit for verification

Call POST /verifications to submit the business for review. The response includes a verificationStatus. If beneficial owners, fields, or documents are missing, verificationStatus is RESOLVE_ERRORS and the errors array tells you exactly what to collect — note that resourceId may point at either the customer or a specific beneficial owner.

curl -X POST "https://api.lightspark.com/grid/2025-10-13/verifications" \
  -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001"
  }'

Blocked by missing data:

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

Submitted successfully:

{
  "id": "Verification:019542f5-b3e7-1d02-0000-000000000002",
  "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001",
  "verificationStatus": "IN_PROGRESS",
  "errors": [],
  "createdAt": "2025-10-03T12:00:00Z"
}

Track the decision

Track terminal kycStatus transitions via the CUSTOMER.KYB_APPROVED / CUSTOMER.KYB_REJECTED webhook (recommended) or by polling GET /customers/{customerId}. CUSTOMER.KYB_PENDING also fires when the business is submitted for review — subscribe to it if you want to surface an “under review” state. On APPROVED, unlock funding and money movement.

Monitor verification status

After a customer completes the KYC/KYB verification process, you’ll receive webhook notifications about their KYC status. These notifications are sent to your configured webhook endpoint.

For regulated platforms, customers are created with APPROVED KYC status by default.

Webhook Payload (sent to your endpoint):

{
  "id": "Webhook:019542f5-b3e7-1d02-0000-000000000020",
  "type": "CUSTOMER.KYC_APPROVED",
  "timestamp": "2025-07-21T17:32:28Z",
  "data": {
    "id": "Customer:019542f5-b3e7-1d02-0000-000000000001",
    "platformCustomerId": "9f84e0c2a72c4fa",
    "customerType": "INDIVIDUAL",
    "umaAddress": "$john.doe@uma.domain.com",
    "kycStatus": "APPROVED",
    "fullName": "John Michael Doe",
    "birthDate": "1990-01-15",
    "nationality": "US",
    "address": {
      "line1": "123 Main Street",
      "line2": "Apt 4B",
      "city": "Seattle",
      "state": "WA",
      "postalCode": "98101",
      "country": "US"
    },
    "createdAt": "2025-07-21T17:32:28Z",
    "updatedAt": "2025-07-21T17:32:28Z",
    "isDeleted": false
  }
}

Webhook Headers:

Content-Type: application/json
X-Grid-Signature: {"v": "1", "s": "base64_signature..."}

string

required

Unique identifier for this webhook delivery. Use this for idempotency to prevent processing duplicate webhooks.

string

required

Status-specific event type. KYC/KYB webhooks use CUSTOMER.* types:

CUSTOMER.KYC_APPROVED: Individual customer verification completed successfully
CUSTOMER.KYC_REJECTED: Individual customer verification was rejected
CUSTOMER.KYC_PENDING: Individual customer is awaiting review
CUSTOMER.KYB_APPROVED / CUSTOMER.KYB_REJECTED / CUSTOMER.KYB_PENDING: business equivalents (only fires for customerType: BUSINESS)

object

required

The full customer resource object, same as the corresponding GET /customers/{id} endpoint would return. Includes all customer fields such as id, kycStatus, fullName, birthDate, nationality, address, etc.

CUSTOMER.KYC_PENDING (or CUSTOMER.KYB_PENDING) fires when a customer enters kycStatus: PENDING (for example, after they are submitted for review). Final outcomes use CUSTOMER.KYC_APPROVED / CUSTOMER.KYC_REJECTED (and the CUSTOMER.KYB_* siblings for business customers).

Webhook Implementation Example

// Example webhook handler for KYC status updates.
// CUSTOMER.KYC_APPROVED and CUSTOMER.KYC_REJECTED are terminal decisions;
// CUSTOMER.KYC_PENDING is an intermediate signal that the customer has been
// submitted for review (useful for surfacing "we're still reviewing" UI).
app.post('/webhooks/kyc-status', async (req, res) => {
  const { type, data } = req.body;

  switch (type) {
    case 'CUSTOMER.KYC_APPROVED':
      // Activate customer account
      await activateCustomer(data.id);
      await sendWelcomeEmail(data.id);
      break;

    case 'CUSTOMER.KYC_REJECTED':
      // Notify support and customer
      await notifySupport(data.id, 'KYC_REJECTED');
      await sendRejectionEmail(data.id);
      break;

    case 'CUSTOMER.KYC_PENDING':
      // Intermediate: customer submitted for review, no decision yet
      await markCustomerUnderReview(data.id);
      break;

    case 'CUSTOMER.KYB_APPROVED':
      // Business customer decision: activate
      await activateCustomer(data.id);
      await sendWelcomeEmail(data.id);
      break;

    case 'CUSTOMER.KYB_REJECTED':
      // Business customer decision: notify
      await notifySupport(data.id, 'KYB_REJECTED');
      await sendRejectionEmail(data.id);
      break;

    case 'CUSTOMER.KYB_PENDING':
      // Intermediate: business customer submitted for review
      await markCustomerUnderReview(data.id);
      break;

    default:
      // Log unexpected types
      console.log(`Unexpected webhook type ${type} for customer ${data.id}`);
  }

  res.status(200).send('OK');
});

Only customers with APPROVED status can create quotes and process conversions.

Customer types

Individual customers

For personal conversions and consumer wallets.Required fields: fullName, birthDate, addressConditionally required: email and phoneNumber are required in regions that verify contact information before identity verification (e.g., the EU).

curl -X POST 'https://api.lightspark.com/grid/2025-10-13/customers' \
  -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET" \
  -H 'Content-Type: application/json' \
  -d '{
    "platformCustomerId": "user_12345",
    "customerType": "INDIVIDUAL",
    "fullName": "Alice Johnson",
    "email": "alice@example.com",
    "birthDate": "1990-01-15",
    "address": {...}
  }'

Business customers

For corporate conversions and business accounts.Required fields: customerType, plus businessInfo.legalName, businessInfo.country, businessInfo.taxId, and businessInfo.incorporatedOn. Most providers also require address for KYB.

curl -X POST 'https://api.lightspark.com/grid/2025-10-13/customers' \
  -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET" \
  -H 'Content-Type: application/json' \
  -d '{
    "platformCustomerId": "biz_67890",
    "customerType": "BUSINESS",
    "email": "finance@acme.com",
    "businessInfo": {
      "legalName": "Acme Corporation",
      "country": "US",
      "taxId": "12-3456789",
      "incorporatedOn": "2018-03-14",
      "businessType": "INFORMATION"
    },
    "address": {...}
  }'

Overview

Onboarding

Managing accounts

Conversion flows

Global Accounts

Platform tools

Creating Customers via Direct API

Hosted KYC and KYB Link Flow

1. Create the customer

2. Generate the link

The flow end to end

Direct API Onboarding

Business identifying information

Ownership and control structure

Required documents

Monitor verification status

Customer types

Next steps

​Creating Customers via Direct API

​Hosted KYC and KYB Link Flow

​1. Create the customer

​2. Generate the link

​The flow end to end

​Direct API Onboarding

​Business identifying information

​Ownership and control structure

​Required documents

​Monitor verification status

​Customer types

​Next steps

Creating Customers via Direct API

Hosted KYC and KYB Link Flow

1. Create the customer

2. Generate the link

The flow end to end

Direct API Onboarding

Business identifying information

Ownership and control structure

Required documents

Monitor verification status

Customer types

Next steps