---
title: "Add an individual customer from a reusable KYC share token"
method: POST
path: "/customers/share"
tags: ["Customers"]
---

# Add an individual customer from a reusable KYC share token

`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

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`.

## Request body

- CustomerShareCreateRequest: Enhanced-due-diligence (EDD) fields available as optional patchable attributes on an individual customer. Referenced via `allOf` from `IndividualCustomerFields`, so these appear as top-level optional fields on the customer resource itself; there is no separate EDD resource. The specific set required for a given customer is driven by the KYC provider's per-jurisdiction / per-flow / per-volume-tier rules (surfaced through `MISSING_FIELD` errors on `POST /verifications`).
  - `platformCustomerId` string: 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
  - `region` string: 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.
  - `currencies` string[]: 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.
  - `email` string, email: Email address for the customer. **Required in regions that verify the email address before identity verification** (e.g. the EU); optional otherwise.
  - `phoneNumber` string: 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.
  - `umaAddress` string: 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.
  - `endUserTermsConsent` EndUserTermsConsent: Deprecated; use `agreementConsents` instead, which records acceptance of each agreement separately. Reported only for a customer whose acceptance predates that field, and always as the `LIGHTSPARK_END_USER_TERMS` agreement.
    - `acceptedAt` string, date-time, required: Date and time when the customer accepted the End User Terms.
    - `ipAddress` string, required: IP address of the device the customer used when accepting the terms.
    - `termsVersion` string, required: Version identifier of the accepted Grid End User Terms.
    - `acceptanceMethod` 'CHECKBOX' | 'CLICK_TO_ACCEPT', required: Method the customer used to affirmatively accept an agreement.
  - `agreementConsents` AgreementConsentRequest[]: Evidence that the customer accepted Grid agreements, at most one entry per type. Include every agreement the platform requires for the customer's accounts: the Lightspark End User Terms on unregulated platforms, and the Lead accountholder agreement for the customer type when the platform requires it.
    - `type` 'LIGHTSPARK_END_USER_TERMS' | 'LIGHTSPARK_E_SIGN_CONSENT' | 'LIGHTSPARK_PRIVACY_POLICY' | 'LEAD_E_SIGN_CONSENT' | 'LEAD_ACCOUNTHOLDER_CONSUMER_AGREEMENT' | 'LEAD_ACCOUNTHOLDER_COMMERCIAL_AGREEMENT' | 'LEAD_PRIVACY_POLICY' | 'LEAD_CARDHOLDER_CONSUMER_AGREEMENT' | 'LEAD_CARDHOLDER_COMMERCIAL_AGREEMENT', required: Identifies which Grid agreement a consent record or document refers to. Values are stable identifiers: a document's hosted URL or version may change, but its type does not. Accepting one agreement never implies acceptance of another, even when two agreements share a hosted page. The cardholder and accountholder agreements differ by customer kind: an `INDIVIDUAL` customer accepts the `_CONSUMER_` variant, and a `BUSINESS` customer accepts the `_COMMERCIAL_` one.
    - `acceptedAt` string, date-time, required: Date and time when the customer accepted this agreement. Must include a timezone offset and must not be in the future.
    - `ipAddress` string, required: IP address of the device the customer used when accepting this agreement.
    - `termsVersion` string, required: Version identifier of the accepted agreement, as returned for this type by the agreement documents endpoint. A version is scoped to its type; a version valid for one agreement is not valid for another.
    - `acceptanceMethod` 'CHECKBOX' | 'CLICK_TO_ACCEPT', required: Method the customer used to affirmatively accept an agreement.
  - `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.
  - `fullName` string: Individual's full name
  - `birthDate` string, date: Date of birth in ISO 8601 format (YYYY-MM-DD)
  - `nationality` string: Country code (ISO 3166-1 alpha-2)
  - `address` Address
    - `line1` string, required: Street address line 1
    - `line2` string: Street address line 2
    - `city` string: City
    - `state` string: State/Province/Region
    - `postalCode` string, required: Postal/ZIP code
    - `country` string, required: Country code (ISO 3166-1 alpha-2)
  - `idType` 'SSN' | 'ITIN' | 'EIN' | 'NON_US_TAX_ID': Type of tax identification
  - `identifier` string: 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.
  - `countryOfIssuance` string: 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.
  - `sourceOfFundsCategories` IndividualSourceOfFundsCategory[]: Structured source-of-funds categories (FLOW of funds for this account).
  - `sourceOfFundsOtherDescription` string: Free-form description of the customer's source of funds. Required when `sourceOfFundsCategories` includes `OTHER`; otherwise omitted.
  - `sourceOfWealthCategories` SourceOfWealthCategory[]: Structured source-of-wealth categories (STOCK — origin of accumulated wealth).
  - `sourceOfWealthOtherDescription` string: 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
  - `purposeOfAccountOtherDescription` string: 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.
  - `shareToken` KycShareToken, required: A single-use reusable KYC share token from a partner that already verified this person.
    - `provider` 'SUMSUB', required: The KYC provider that will perform identity verification for the customer. Grid selects the provider based on the customer's region and platform configuration; the value is informational for platforms that want to integrate directly with the provider's SDK.
    - `token` string, required: The share token generated by the partner for Lightspark.

## Response `201`

Customer created successfully

- IndividualCustomer: Enhanced-due-diligence (EDD) fields available as optional patchable attributes on an individual customer. Referenced via `allOf` from `IndividualCustomerFields`, so these appear as top-level optional fields on the customer resource itself; there is no separate EDD resource. The specific set required for a given customer is driven by the KYC provider's per-jurisdiction / per-flow / per-volume-tier rules (surfaced through `MISSING_FIELD` errors on `POST /verifications`).
  - `id` string: System-generated unique identifier
  - `platformCustomerId` string, required: Platform-specific customer identifier
  - `customerType` 'INDIVIDUAL', required: Whether the customer is an individual or a business entity
  - `endUserTermsConsent` EndUserTermsConsent: Deprecated; use `agreementConsents` instead, which records acceptance of each agreement separately. Reported only for a customer whose acceptance predates that field, and always as the `LIGHTSPARK_END_USER_TERMS` agreement.
    - `acceptedAt` string, date-time, required: Date and time when the customer accepted the End User Terms.
    - `ipAddress` string, required: IP address of the device the customer used when accepting the terms.
    - `termsVersion` string, required: Version identifier of the accepted Grid End User Terms.
    - `acceptanceMethod` 'CHECKBOX' | 'CLICK_TO_ACCEPT', required: Method the customer used to affirmatively accept an agreement.
  - `agreementConsents` AgreementConsent[]: The customer's recorded agreement acceptances, one entry per accepted type holding that type's most recent acceptance. Omitted when the customer has not accepted any agreement yet.
    - `type` 'LIGHTSPARK_END_USER_TERMS' | 'LIGHTSPARK_E_SIGN_CONSENT' | 'LIGHTSPARK_PRIVACY_POLICY' | 'LEAD_E_SIGN_CONSENT' | 'LEAD_ACCOUNTHOLDER_CONSUMER_AGREEMENT' | 'LEAD_ACCOUNTHOLDER_COMMERCIAL_AGREEMENT' | 'LEAD_PRIVACY_POLICY' | 'LEAD_CARDHOLDER_CONSUMER_AGREEMENT' | 'LEAD_CARDHOLDER_COMMERCIAL_AGREEMENT', required: Identifies which Grid agreement a consent record or document refers to. Values are stable identifiers: a document's hosted URL or version may change, but its type does not. Accepting one agreement never implies acceptance of another, even when two agreements share a hosted page. The cardholder and accountholder agreements differ by customer kind: an `INDIVIDUAL` customer accepts the `_CONSUMER_` variant, and a `BUSINESS` customer accepts the `_COMMERCIAL_` one.
    - `acceptedAt` string, date-time, required: Date and time when the customer accepted this agreement. Must include a timezone offset and must not be in the future.
    - `ipAddress` string, required: IP address of the device the customer used when accepting this agreement.
    - `termsVersion` string, required: Version identifier of the accepted agreement, as returned for this type by the agreement documents endpoint. A version is scoped to its type; a version valid for one agreement is not valid for another.
    - `acceptanceMethod` 'CHECKBOX' | 'CLICK_TO_ACCEPT', required: Method the customer used to affirmatively accept an agreement.
  - `region` string: Country code (ISO 3166-1 alpha-2) representing the customer's regional identity and regulatory jurisdiction.
  - `currencies` string[]: List of currency codes enabled for this customer.
  - `email` string, email: Email address for the customer.
  - `phoneNumber` string: Phone number for the customer in strict E.164 format.
  - `umaAddress` string, required: Full UMA address (always present in responses, even if system-generated). This is an optional identifier to route payments to the customer.
  - `createdAt` string, date-time: Creation timestamp
  - `updatedAt` string, date-time: Last update timestamp
  - `isDeleted` boolean: Whether the customer is marked as deleted
  - `contactVerification` ContactVerification: Email and/or phone verification state for the customer. This object is **only present when the customer's regulatory jurisdiction requires contact verification** (e.g. EU customers). For customers who have no such requirement, this object is omitted entirely — no action is needed. Each channel is reported independently: only the channels the customer's provider actually requires are present. A provider may require both email and phone, just one of them, or — when the object is absent — neither. Every channel that **is** present must reach `VERIFIED` before the customer can begin KYC. Drive each present channel with `POST /customers/{customerId}/verify-email` and/or `POST /customers/{customerId}/verify-phone` (and their `/confirm` sub-routes).
    - `email` 'PENDING' | 'VERIFIED': Status of an individual contact-verification channel (email or phone). `PENDING` means verification is required but not yet completed; `VERIFIED` means the channel has been confirmed.
    - `phone` 'PENDING' | 'VERIFIED': Status of an individual contact-verification channel (email or phone). `PENDING` means verification is required but not yet completed; `VERIFIED` means the channel has been confirmed.
  - `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.
  - `fullName` string: Individual's full name
  - `birthDate` string, date: Date of birth in ISO 8601 format (YYYY-MM-DD)
  - `nationality` string: Country code (ISO 3166-1 alpha-2)
  - `address` Address
    - `line1` string, required: Street address line 1
    - `line2` string: Street address line 2
    - `city` string: City
    - `state` string: State/Province/Region
    - `postalCode` string, required: Postal/ZIP code
    - `country` string, required: Country code (ISO 3166-1 alpha-2)
  - `idType` 'SSN' | 'ITIN' | 'EIN' | 'NON_US_TAX_ID': Type of tax identification
  - `identifier` string: 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.
  - `countryOfIssuance` string: 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.
  - `sourceOfFundsCategories` IndividualSourceOfFundsCategory[]: Structured source-of-funds categories (FLOW of funds for this account).
  - `sourceOfFundsOtherDescription` string: Free-form description of the customer's source of funds. Required when `sourceOfFundsCategories` includes `OTHER`; otherwise omitted.
  - `sourceOfWealthCategories` SourceOfWealthCategory[]: Structured source-of-wealth categories (STOCK — origin of accumulated wealth).
  - `sourceOfWealthOtherDescription` string: 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
  - `purposeOfAccountOtherDescription` string: 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.

## Other responses

- `400`: Bad request. `INVALID_INPUT` when the provider rejects the share token or the platform does not run Grid's individual KYC. `ACCOUNTHOLDER_AGREEMENT_NOT_ACCEPTED` when the platform requires an accountholder agreement and `agreementConsents` does not include it.
- `401`: Unauthorized
- `403`: Forbidden. `END_USER_TERMS_NOT_ACCEPTED` when the platform requires the End User Terms and the request does not accept them.
- `405`: Method not allowed. Returned (as JSON, not HTML) when the request uses an HTTP method that is not supported on this path.
- `409`: Conflict. `UMA_ADDRESS_EXISTS` when the requested UMA address is already taken; `CONFLICT` when `platformCustomerId` collides with an existing active customer on the same platform.
- `500`: Internal service error

## Changes

> 115 revisions in range; 2 not diffed.

- **2026-10-28** `d996ddfb9d2b`: 5 info
  - added the optional property `details/missingFields` to the response with the `400` status
  - added the optional property `details/permission` to the response with the `403` status
  - added the optional property `details/policyDenialReason` to the response with the `403` status
  - added the optional property `details/refusalReason` to the response with the `400` status
  - …1 more
- **2026-10-28** `5abf2bb56bcb`: 1 warning
  - added the new `CORRIDOR_UNDER_MAINTENANCE` enum value to the `code` response property for the response status `403`
- **2026-10-26** `f11f1e76bdd7`: 1 warning
  - added the new `PURCHASE_CARD_LIMIT_REACHED` enum value to the `code` response property for the response status `409`
- **2026-10-26** `0a6dad5815c7`: 1 warning
  - added the new `INVOICE_ALREADY_USED` enum value to the `code` response property for the response status `409`
- **2026-10-24** `715332dcb111`: 1 warning
  - added the new `EXACT_AMOUNT_UNAVAILABLE` enum value to the `code` response property for the response status `400`

[Operation history](https://skmtc.dev/lightsparkdev/apis/grid-api/changes/customers/share/post.md)

---

[API](https://skmtc.dev/lightsparkdev/apis/grid-api.md) - [All operations](https://skmtc.dev/lightsparkdev/apis/grid-api/llms.txt) - [OpenAPI document](https://skmtc.dev/lightsparkdev/apis/grid-api/revisions/7a1db46ec552?raw)