LIlightsparkdev
Customers

Add an individual customer from a reusable KYC share token

Changed on

Create an individual customer whose verification profile is built from a partner's shared data, including their identity document, so it does not need to be uploaded again. Fields sent in this request take priority over the shared data. Check the customer's verification status to address any KYC gaps and then submit the customer for verification using POST /verifications.

post/customers/share

Request

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

Request body

platformCustomerIdstring

Platform-specific customer identifier. If not provided, one will be generated by the system.

customerType'INDIVIDUAL' required

Whether the customer is an individual or a business entity

regionstring

Country code (ISO 3166-1 alpha-2) for the customer's region. Optional — send it only when the same currency is offered in more than one of your regions, to pick the one that applies to this customer.

currenciesstring[]

Currency codes the customer will use — ISO 4217 for fiat, tickers for crypto (e.g. "USDC"). Optional — send them if your platform supports more than one currency, so we know which ones this customer needs. Some combinations require separate customers.

emailstring email

Email address for the customer. Required in regions that verify the email address before identity verification (e.g. the EU); optional otherwise.

phoneNumberstring

Phone number for the customer in strict E.164 format. Required in regions that verify the phone number before identity verification (e.g. the EU); optional otherwise.

umaAddressstring

Optional UMA address identifier. If not provided during customer creation, one will be generated by the system. If provided during customer update, the UMA address will be updated to the provided value. This is an optional identifier to route payments to the customer. This is an optional identifier to route payments to the customer.

kycStatus'UNVERIFIED' | 'PENDING' | 'APPROVED' | 'REJECTED' | 'HOLD'

The current KYC status of a customer. HOLD means the customer is placed on hold and may be required to update or provide more information.

fullNamestring

Individual's full name

birthDatestring date

Date of birth in ISO 8601 format (YYYY-MM-DD)

nationalitystring

Country code (ISO 3166-1 alpha-2)

idType'SSN' | 'ITIN' | 'EIN' | 'NON_US_TAX_ID'

Type of tax identification

identifierstring

The individual's identification number, required to onboard them as a US account holder. Only SSN (format ###-##-####) and ITIN are currently accepted; other identification types are rejected. Write-only — never returned in customer responses.

countryOfIssuancestring

Country that issued the identification (ISO 3166-1 alpha-2). Optional for an individual account holder: SSN and ITIN are US-issued, so this defaults to US and is rejected if set to anything else.

sourceOfFundsCategoriesIndividualSourceOfFundsCategory[]

Structured source-of-funds categories (FLOW of funds for this account).

sourceOfFundsOtherDescriptionstring

Free-form description of the customer's source of funds. Required when sourceOfFundsCategories includes OTHER; otherwise omitted.

sourceOfWealthCategoriesSourceOfWealthCategory[]

Structured source-of-wealth categories (STOCK — origin of accumulated wealth).

sourceOfWealthOtherDescriptionstring

Free-form description of the customer's source of wealth. Required when sourceOfWealthCategories includes OTHER; otherwise omitted.

purposeOfAccount'CONTRACTOR_PAYOUTS' | 'CREATOR_PAYOUTS' | 'EMPLOYEE_PAYOUTS' | 'MARKETPLACE_SELLER_PAYOUTS' | 'SUPPLIER_PAYMENTS' | 'CROSS_BORDER_B2B' | 'AR_AUTOMATION' | 'AP_AUTOMATION' | 'EMBEDDED_PAYMENTS' | 'PLATFORM_FEE_COLLECTION' | 'P2P_TRANSFERS' | 'CHARITABLE_DONATIONS' | 'OTHER'

The intended purpose for using the Grid account

purposeOfAccountOtherDescriptionstring

Free-form description of the customer's intended purpose for the Grid account. Required when purposeOfAccount is OTHER; otherwise omitted.

expectedMonthlyTransactionCount'COUNT_UNDER_10' | 'COUNT_10_TO_100' | 'COUNT_100_TO_500' | 'COUNT_500_TO_1000' | 'COUNT_OVER_1000'

Expected number of transactions per month

expectedMonthlyTransactionVolume'VOLUME_UNDER_10K' | 'VOLUME_10K_TO_100K' | 'VOLUME_100K_TO_1M' | 'VOLUME_1M_TO_10M' | 'VOLUME_OVER_10M'

Expected total transaction volume per month in USD equivalent

annualIncomeRange'UNDER_50K' | 'RANGE_50K_100K' | 'RANGE_100K_250K' | 'RANGE_250K_1M' | 'OVER_1M'

Bucketed annual income (USD equivalent). Used for enhanced due diligence on higher-risk profiles.

netWorthRange'UNDER_100K' | 'RANGE_100K_500K' | 'RANGE_500K_1M' | 'RANGE_1M_5M' | 'RANGE_5M_25M' | 'OVER_25M'

Bucketed total net worth (USD equivalent). Used for enhanced due diligence on higher-risk profiles.

pepStatus'NONE' | 'DOMESTIC' | 'FOREIGN' | 'HIO' | 'FAMILY_OR_ASSOCIATE'

Political exposure declaration (Politically Exposed Person status). HIO = head of an international organization. FAMILY_OR_ASSOCIATE covers close family members and known close associates of a PEP.

Example request

{
  "platformCustomerId": "9f84e0c2a72c4fa",
  "customerType": "INDIVIDUAL",
  "region": "US",
  "currencies": [
    "USD",
    "USDC"
  ],
  "email": "john.doe@example.com",
  "phoneNumber": "+14155551234",
  "umaAddress": "$john.doe@uma.domain.com",
  "endUserTermsConsent": {
    "ipAddress": "198.51.100.24",
    "termsVersion": "V1",
    "acceptanceMethod": "CHECKBOX"
  },
  "agreementConsents": [
    {
      "type": "LIGHTSPARK_END_USER_TERMS",
      "ipAddress": "198.51.100.24",
      "termsVersion": "2025-10-13",
      "acceptanceMethod": "CHECKBOX"
    }
  ],
  "kycStatus": "APPROVED",
  "fullName": "John Michael Doe",
  "birthDate": "1990-01-15",
  "nationality": "US",
  "address": {
    "line1": "123 Main Street",
    "line2": "Apt 4B",
    "city": "San Francisco",
    "state": "CA",
    "postalCode": "94105",
    "country": "US"
  },
  "idType": "SSN",
  "identifier": "123-45-6789",
  "countryOfIssuance": "US",
  "sourceOfFundsCategories": [
    "SALARY"
  ],
  "sourceOfFundsOtherDescription": "Contest winnings",
  "sourceOfWealthCategories": [
    "SALARY",
    "INVESTMENTS"
  ],
  "sourceOfWealthOtherDescription": "Royalty income from published works",
  "purposeOfAccount": "CONTRACTOR_PAYOUTS",
  "purposeOfAccountOtherDescription": "Household budgeting between spouses",
  "expectedMonthlyTransactionCount": "COUNT_100_TO_500",
  "expectedMonthlyTransactionVolume": "VOLUME_100K_TO_1M",
  "annualIncomeRange": "RANGE_100K_250K",
  "netWorthRange": "RANGE_500K_1M",
  "pepStatus": "NONE",
  "shareToken": {
    "provider": "SUMSUB",
    "token": "_act-sbx-jwt-eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }
}

Response

Customer created successfully

idstring

System-generated unique identifier

platformCustomerIdstring required

Platform-specific customer identifier

customerType'INDIVIDUAL' required

Whether the customer is an individual or a business entity

regionstring

Country code (ISO 3166-1 alpha-2) representing the customer's regional identity and regulatory jurisdiction.

currenciesstring[]

List of currency codes enabled for this customer.

emailstring email

Email address for the customer.

phoneNumberstring

Phone number for the customer in strict E.164 format.

umaAddressstring required

Full UMA address (always present in responses, even if system-generated). This is an optional identifier to route payments to the customer.

createdAtstring date-time

Creation timestamp

updatedAtstring date-time

Last update timestamp

isDeletedboolean

Whether the customer is marked as deleted

kycStatus'UNVERIFIED' | 'PENDING' | 'APPROVED' | 'REJECTED' | 'HOLD'

The current KYC status of a customer. HOLD means the customer is placed on hold and may be required to update or provide more information.

fullNamestring

Individual's full name

birthDatestring date

Date of birth in ISO 8601 format (YYYY-MM-DD)

nationalitystring

Country code (ISO 3166-1 alpha-2)

idType'SSN' | 'ITIN' | 'EIN' | 'NON_US_TAX_ID'

Type of tax identification

identifierstring

The individual's identification number, required to onboard them as a US account holder. Only SSN (format ###-##-####) and ITIN are currently accepted; other identification types are rejected. Write-only — never returned in customer responses.

countryOfIssuancestring

Country that issued the identification (ISO 3166-1 alpha-2). Optional for an individual account holder: SSN and ITIN are US-issued, so this defaults to US and is rejected if set to anything else.

sourceOfFundsCategoriesIndividualSourceOfFundsCategory[]

Structured source-of-funds categories (FLOW of funds for this account).

sourceOfFundsOtherDescriptionstring

Free-form description of the customer's source of funds. Required when sourceOfFundsCategories includes OTHER; otherwise omitted.

sourceOfWealthCategoriesSourceOfWealthCategory[]

Structured source-of-wealth categories (STOCK — origin of accumulated wealth).

sourceOfWealthOtherDescriptionstring

Free-form description of the customer's source of wealth. Required when sourceOfWealthCategories includes OTHER; otherwise omitted.

purposeOfAccount'CONTRACTOR_PAYOUTS' | 'CREATOR_PAYOUTS' | 'EMPLOYEE_PAYOUTS' | 'MARKETPLACE_SELLER_PAYOUTS' | 'SUPPLIER_PAYMENTS' | 'CROSS_BORDER_B2B' | 'AR_AUTOMATION' | 'AP_AUTOMATION' | 'EMBEDDED_PAYMENTS' | 'PLATFORM_FEE_COLLECTION' | 'P2P_TRANSFERS' | 'CHARITABLE_DONATIONS' | 'OTHER'

The intended purpose for using the Grid account

purposeOfAccountOtherDescriptionstring

Free-form description of the customer's intended purpose for the Grid account. Required when purposeOfAccount is OTHER; otherwise omitted.

expectedMonthlyTransactionCount'COUNT_UNDER_10' | 'COUNT_10_TO_100' | 'COUNT_100_TO_500' | 'COUNT_500_TO_1000' | 'COUNT_OVER_1000'

Expected number of transactions per month

expectedMonthlyTransactionVolume'VOLUME_UNDER_10K' | 'VOLUME_10K_TO_100K' | 'VOLUME_100K_TO_1M' | 'VOLUME_1M_TO_10M' | 'VOLUME_OVER_10M'

Expected total transaction volume per month in USD equivalent

annualIncomeRange'UNDER_50K' | 'RANGE_50K_100K' | 'RANGE_100K_250K' | 'RANGE_250K_1M' | 'OVER_1M'

Bucketed annual income (USD equivalent). Used for enhanced due diligence on higher-risk profiles.

netWorthRange'UNDER_100K' | 'RANGE_100K_500K' | 'RANGE_500K_1M' | 'RANGE_1M_5M' | 'RANGE_5M_25M' | 'OVER_25M'

Bucketed total net worth (USD equivalent). Used for enhanced due diligence on higher-risk profiles.

pepStatus'NONE' | 'DOMESTIC' | 'FOREIGN' | 'HIO' | 'FAMILY_OR_ASSOCIATE'

Political exposure declaration (Politically Exposed Person status). HIO = head of an international organization. FAMILY_OR_ASSOCIATE covers close family members and known close associates of a PEP.

Example response

{
  "id": "Customer:019542f5-b3e7-1d02-0000-000000000001",
  "platformCustomerId": "9f84e0c2a72c4fa",
  "customerType": "INDIVIDUAL",
  "endUserTermsConsent": {
    "ipAddress": "198.51.100.24",
    "termsVersion": "V1",
    "acceptanceMethod": "CHECKBOX"
  },
  "agreementConsents": [
    {
      "type": "LIGHTSPARK_END_USER_TERMS",
      "ipAddress": "198.51.100.24",
      "termsVersion": "2025-10-13",
      "acceptanceMethod": "CHECKBOX"
    }
  ],
  "region": "US",
  "currencies": [
    "USD",
    "USDC"
  ],
  "email": "john.doe@example.com",
  "phoneNumber": "+14155551234",
  "umaAddress": "$john.doe@uma.domain.com",
  "createdAt": "2025-07-21T17:32:28Z",
  "updatedAt": "2025-07-21T17:32:28Z",
  "contactVerification": {
    "email": "VERIFIED",
    "phone": "VERIFIED"
  },
  "kycStatus": "APPROVED",
  "fullName": "John Michael Doe",
  "birthDate": "1990-01-15",
  "nationality": "US",
  "address": {
    "line1": "123 Main Street",
    "line2": "Apt 4B",
    "city": "San Francisco",
    "state": "CA",
    "postalCode": "94105",
    "country": "US"
  },
  "idType": "SSN",
  "identifier": "123-45-6789",
  "countryOfIssuance": "US",
  "sourceOfFundsCategories": [
    "SALARY"
  ],
  "sourceOfFundsOtherDescription": "Contest winnings",
  "sourceOfWealthCategories": [
    "SALARY",
    "INVESTMENTS"
  ],
  "sourceOfWealthOtherDescription": "Royalty income from published works",
  "purposeOfAccount": "CONTRACTOR_PAYOUTS",
  "purposeOfAccountOtherDescription": "Household budgeting between spouses",
  "expectedMonthlyTransactionCount": "COUNT_100_TO_500",
  "expectedMonthlyTransactionVolume": "VOLUME_100K_TO_1M",
  "annualIncomeRange": "RANGE_100K_250K",
  "netWorthRange": "RANGE_500K_1M",
  "pepStatus": "NONE"
}

Changes

  • d996ddfb9d2bRevision changes
    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status

  • 5abf2bb56bcbRevision changes
    • warning

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