Endpoints for Know Your Customer (KYC) and Know Your Business (KYB) verification, including managing beneficial owners and triggering verification for customers.
openapi: 3.1.0
info:
title: Grid Agent Management KYC/KYB Verifications API
description: 'API for managing global payments on the open Money Grid. Built by Lightspark. See the full documentation at https://docs.lightspark.com/.
'
version: '2025-10-13'
contact:
name: Lightspark Support
email: support@lightspark.com
license:
name: Proprietary
url: https://lightspark.com/terms
servers:
- url: https://api.lightspark.com/grid/2025-10-13
description: Production server
security:
- BasicAuth: []
- AgentAuth: []
tags:
- name: KYC/KYB Verifications
description: Endpoints for Know Your Customer (KYC) and Know Your Business (KYB) verification, including managing beneficial owners and triggering verification for customers.
paths:
/customers/{customerId}/kyc-link:
parameters:
- name: customerId
in: path
description: The Grid customer ID to generate a KYC link for.
required: true
schema:
type: string
post:
summary: Generate a hosted KYC link for an existing customer
description: 'Generate a single-use hosted URL the customer can complete to verify their identity, and (where supported) a provider-specific `token` for embedding the verification flow directly via the provider''s SDK.
The customer must already exist — create them with `POST /customers` first. Calling this endpoint does not change the customer''s `kycStatus`; the customer remains `PENDING` until they complete (or fail) the hosted flow.
Each call returns a fresh link. Previously-issued links are not invalidated, but they remain single-use and will expire on their own. For request-level retry safety, include an `Idempotency-Key` header.
'
operationId: createCustomerKycLink
tags:
- KYC/KYB Verifications
security:
- BasicAuth: []
parameters:
- name: Idempotency-Key
in: header
required: false
description: 'A unique identifier for the request. If the same key is sent multiple times, the server will return the same response as the first request.
'
schema:
type: string
example: <uuid>
requestBody:
required: false
content:
application/json:
schema:
$ref: '#/components/schemas/KycLinkCreateRequest'
responses:
'201':
description: KYC link generated
content:
application/json:
schema:
$ref: '#/components/schemas/KycLinkResponse'
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/Error400'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/Error401'
'404':
description: Customer not found
content:
application/json:
schema:
$ref: '#/components/schemas/Error404'
'409':
description: The customer's payment provider requires contact verification and the customer's email and phone are not both `VERIFIED` yet. Complete contact verification (see `verify-email` and `verify-phone`) before generating a KYC link.
content:
application/json:
schema:
$ref: '#/components/schemas/Error409'
'500':
description: Internal service error
content:
application/json:
schema:
$ref: '#/components/schemas/Error500'
/beneficial-owners:
post:
summary: Create a beneficial owner
description: 'Add a beneficial owner, director, or company officer to a business customer. The beneficial owner will go through KYC verification automatically.
'
operationId: createBeneficialOwner
tags:
- KYC/KYB Verifications
security:
- BasicAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/BeneficialOwnerCreateRequest'
responses:
'201':
description: Beneficial owner created successfully
content:
application/json:
schema:
$ref: '#/components/schemas/BeneficialOwner'
'400':
description: Bad request - Invalid parameters
content:
application/json:
schema:
$ref: '#/components/schemas/Error400'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/Error401'
'404':
description: Customer not found
content:
application/json:
schema:
$ref: '#/components/schemas/Error404'
'500':
description: Internal service error
content:
application/json:
schema:
$ref: '#/components/schemas/Error500'
get:
summary: List beneficial owners
description: 'Retrieve a list of beneficial owners for a business customer.
'
operationId: listBeneficialOwners
tags:
- KYC/KYB Verifications
security:
- BasicAuth: []
parameters:
- name: customerId
in: query
description: The business customer ID
required: true
schema:
type: string
- name: limit
in: query
description: Maximum number of results to return (default 20, max 100)
required: false
schema:
type: integer
minimum: 1
maximum: 100
default: 20
- name: cursor
in: query
description: Cursor for pagination (returned from previous request)
required: false
schema:
type: string
responses:
'200':
description: Successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/BeneficialOwnerListResponse'
'400':
description: Bad request - Invalid parameters
content:
application/json:
schema:
$ref: '#/components/schemas/Error400'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/Error401'
'500':
description: Internal service error
content:
application/json:
schema:
$ref: '#/components/schemas/Error500'
/beneficial-owners/{beneficialOwnerId}:
get:
summary: Get a beneficial owner
description: Retrieve details of a specific beneficial owner by ID.
operationId: getBeneficialOwner
tags:
- KYC/KYB Verifications
security:
- BasicAuth: []
parameters:
- name: beneficialOwnerId
in: path
description: Beneficial owner ID
required: true
schema:
type: string
responses:
'200':
description: Successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/BeneficialOwner'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/Error401'
'404':
description: Beneficial owner not found
content:
application/json:
schema:
$ref: '#/components/schemas/Error404'
'500':
description: Internal service error
content:
application/json:
schema:
$ref: '#/components/schemas/Error500'
patch:
summary: Update a beneficial owner
description: Update details of a specific beneficial owner. Only provided fields are updated.
operationId: updateBeneficialOwner
tags:
- KYC/KYB Verifications
security:
- BasicAuth: []
parameters:
- name: beneficialOwnerId
in: path
description: Beneficial owner ID
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/BeneficialOwnerUpdateRequest'
responses:
'200':
description: Beneficial owner updated successfully
content:
application/json:
schema:
$ref: '#/components/schemas/BeneficialOwner'
'400':
description: Bad request - Invalid parameters
content:
application/json:
schema:
$ref: '#/components/schemas/Error400'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/Error401'
'404':
description: Beneficial owner not found
content:
application/json:
schema:
$ref: '#/components/schemas/Error404'
'500':
description: Internal service error
content:
application/json:
schema:
$ref: '#/components/schemas/Error500'
/verifications:
post:
summary: Submit customer for verification
description: "Trigger KYC (individual) or KYB (business) verification for a customer.\nThe response indicates whether all required information has been provided.\nIf data is missing, the `errors` array describes exactly what needs to be\nsupplied before verification can proceed.\n\nCall this endpoint again after resolving errors to re-submit.\n\n### What to collect for KYB\n\nBefore submitting a `BUSINESS` customer, collect the following via\n`POST /customers`, `POST /beneficial-owners`, and `POST /documents`:\n\n**Business identifying information**\n- Entity full legal name\n- Doing Business As (DBA) name, if applicable\n- Physical address — principal place of business\n- Countries of operation\n- Identification number — U.S. taxpayer identification number, or, for a\n foreign business without one, alternative government-issued documentation\n certifying the existence of the business\n\n**Ownership and control structure** — collected for **one control person**\n(an individual with significant responsibility to control, manage, or\ndirect the legal entity) **and all beneficial owners** (every individual\nwho owns 25% or more, directly or indirectly). For each, provide:\n- Full name\n- Date of birth\n- Address\n- Identification number:\n - U.S. persons — SSN or ITIN\n - Non-U.S. persons — one or more of: ITIN, passport (with country of\n issuance), alien identification card, or another government-issued\n photo ID evidencing nationality or residence\n\n**Required documents**\n- Company formation and existence documents (certificate of incorporation,\n articles of association, etc.)\n- Proof of ownership and control structure (organization and ownership\n chart, shareholder agreements, operating agreements, register of members,\n or certification of controlling person and beneficial owners)\n- Proof of address dated within the last 3 months (utility bill, bank\n statement, lease agreement, or official correspondence)\n- Tax ID or equivalent identifying-number documents\n- For non-U.S. beneficial owners — passport plus one additional\n government-issued ID\n"
operationId: createVerification
tags:
- KYC/KYB Verifications
security:
- BasicAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/VerificationRequest'
responses:
'200':
description: 'Verification status returned. Check `verificationStatus` and `errors` to determine next steps.
'
content:
application/json:
schema:
$ref: '#/components/schemas/Verification'
examples:
missingInfo:
summary: Verification blocked by missing data
value:
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_PROOF_OF_ADDRESS_DOCUMENT
acceptedDocumentTypes:
- PROOF_OF_ADDRESS
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'
submitted:
summary: Verification submitted successfully
value:
id: Verification:019542f5-b3e7-1d02-0000-000000000002
customerId: Customer:019542f5-b3e7-1d02-0000-000000000001
verificationStatus: IN_PROGRESS
errors: []
createdAt: '2025-10-03T12:00:00Z'
'400':
description: Bad request - Invalid parameters
content:
application/json:
schema:
$ref: '#/components/schemas/Error400'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/Error401'
'404':
description: Customer not found
content:
application/json:
schema:
$ref: '#/components/schemas/Error404'
'500':
description: Internal service error
content:
application/json:
schema:
$ref: '#/components/schemas/Error500'
get:
summary: List verifications
description: 'Retrieve a list of verifications with optional filtering by customer ID and status.
'
operationId: listVerifications
tags:
- KYC/KYB Verifications
security:
- BasicAuth: []
parameters:
- name: customerId
in: query
description: Filter by customer ID
required: false
schema:
type: string
- name: verificationStatus
in: query
description: Filter by verification status
required: false
schema:
$ref: '#/components/schemas/VerificationStatus'
- name: limit
in: query
description: Maximum number of results to return (default 20, max 100)
required: false
schema:
type: integer
minimum: 1
maximum: 100
default: 20
- name: cursor
in: query
description: Cursor for pagination (returned from previous request)
required: false
schema:
type: string
responses:
'200':
description: Successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/VerificationListResponse'
'400':
description: Bad request - Invalid parameters
content:
application/json:
schema:
$ref: '#/components/schemas/Error400'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/Error401'
'500':
description: Internal service error
content:
application/json:
schema:
$ref: '#/components/schemas/Error500'
/verifications/{verificationId}:
get:
summary: Get a verification
description: Retrieve details of a specific verification by ID.
operationId: getVerification
tags:
- KYC/KYB Verifications
security:
- BasicAuth: []
parameters:
- name: verificationId
in: path
description: Verification ID
required: true
schema:
type: string
responses:
'200':
description: Successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/Verification'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/Error401'
'404':
description: Verification not found
content:
application/json:
schema:
$ref: '#/components/schemas/Error404'
'500':
description: Internal service error
content:
application/json:
schema:
$ref: '#/components/schemas/Error500'
components:
schemas:
BeneficialOwnerPersonalInfo:
type: object
required:
- firstName
- lastName
- birthDate
- nationality
- address
- idType
- identifier
properties:
firstName:
type: string
description: First name of the individual
example: Jane
middleName:
type: string
description: Middle name of the individual
example: Marie
lastName:
type: string
description: Last name of the individual
example: Smith
birthDate:
type: string
format: date
description: Date of birth in ISO 8601 format (YYYY-MM-DD)
example: '1978-06-15'
nationality:
type: string
description: Country of nationality (ISO 3166-1 alpha-2)
example: US
email:
type: string
format: email
description: Email address of the individual
example: jane.smith@acmecorp.com
phoneNumber:
type: string
description: Phone number in E.164 format
example: '+14155550192'
pattern: ^\+[1-9]\d{1,14}$
address:
$ref: '#/components/schemas/Address'
idType:
$ref: '#/components/schemas/IdentificationType'
identifier:
type: string
description: The identification number or value
example: 123-45-6789
countryOfIssuance:
type: string
description: Country that issued the identification (ISO 3166-1 alpha-2)
example: US
Verification:
type: object
required:
- id
- customerId
- verificationStatus
- errors
- createdAt
properties:
id:
type: string
description: Unique identifier for this verification
example: Verification:019542f5-b3e7-1d02-0000-000000000001
customerId:
type: string
description: The ID of the customer being verified
example: Customer:019542f5-b3e7-1d02-0000-000000000001
verificationStatus:
$ref: '#/components/schemas/VerificationStatus'
errors:
type: array
description: List of issues preventing verification from proceeding. Empty when verificationStatus is APPROVED or IN_PROGRESS.
items:
$ref: '#/components/schemas/VerificationError'
createdAt:
type: string
format: date-time
description: When this verification was created
example: '2025-10-03T12:00:00Z'
updatedAt:
type: string
format: date-time
description: When this verification was last updated
example: '2025-10-03T12:00:00Z'
BeneficialOwnerUpdateRequest:
type: object
properties:
roles:
type: array
items:
$ref: '#/components/schemas/BeneficialOwnerRole'
description: Roles of this person within the business
example:
- UBO
- DIRECTOR
ownershipPercentage:
type: integer
description: Percentage of ownership in the business (0-100)
minimum: 0
maximum: 100
example: 51
personalInfo:
$ref: '#/components/schemas/BeneficialOwnerPersonalInfoUpdate'
BeneficialOwnerListResponse:
type: object
required:
- data
- hasMore
properties:
data:
type: array
description: List of beneficial owners matching the filter criteria
items:
$ref: '#/components/schemas/BeneficialOwner'
hasMore:
type: boolean
description: Indicates if more results are available beyond this page
nextCursor:
type: string
description: Cursor to retrieve the next page of results (only present if hasMore is true)
totalCount:
type: integer
description: Total number of results matching the criteria
Address:
type: object
required:
- line1
- postalCode
- country
properties:
line1:
type: string
description: Street address line 1
example: 123 Main Street
line2:
type: string
description: Street address line 2
example: Apt 4B
city:
type: string
description: City
example: San Francisco
state:
type: string
description: State/Province/Region
example: CA
postalCode:
type: string
description: Postal/ZIP code
example: '94105'
country:
type: string
description: Country code (ISO 3166-1 alpha-2)
example: US
BeneficialOwner:
type: object
required:
- id
- customerId
- roles
- ownershipPercentage
- personalInfo
- kycStatus
- createdAt
properties:
id:
type: string
description: Unique identifier for this beneficial owner
example: BeneficialOwner:019542f5-b3e7-1d02-0000-000000000001
customerId:
type: string
description: The ID of the business customer this beneficial owner is associated with
example: Customer:019542f5-b3e7-1d02-0000-000000000001
roles:
type: array
items:
$ref: '#/components/schemas/BeneficialOwnerRole'
description: Roles of this person within the business
example:
- UBO
- DIRECTOR
ownershipPercentage:
type: integer
description: Percentage of ownership in the business (0-100)
minimum: 0
maximum: 100
example: 51
personalInfo:
$ref: '#/components/schemas/BeneficialOwnerPersonalInfo'
kycStatus:
$ref: '#/components/schemas/KycStatus'
createdAt:
type: string
format: date-time
description: When this beneficial owner was created
example: '2025-10-03T12:00:00Z'
updatedAt:
type: string
format: date-time
description: When this beneficial owner was last updated
example: '2025-10-03T12:00:00Z'
KycLinkResponse:
type: object
description: A hosted KYC link that the customer can complete to verify their identity.
required:
- kycUrl
- expiresAt
- provider
properties:
kycUrl:
type: string
description: Hosted URL the customer should be sent to in order to complete verification. The URL is single-use and expires at `expiresAt`. To generate a new link (for example, after the previous one expires or is abandoned), call this endpoint again.
example: https://kyc.lightspark.com/onboard/abc123def456
expiresAt:
type: string
format: date-time
description: Time at which the hosted link expires and can no longer be used.
example: '2027-01-15T14:32:00Z'
provider:
$ref: '#/components/schemas/KycProvider'
token:
type: string
description: Provider-specific token that can be used in place of the hosted URL — for example, to embed the provider's SDK directly in your application. Only returned for providers that support direct SDK integration. Whether to use the hosted URL or the embedded SDK is up to you; both flows result in the same `kycStatus` update on the customer.
example: _act-sbx-jwt-eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Error404:
type: object
required:
- message
- status
- code
properties:
status:
type: integer
enum:
- 404
description: HTTP status code
code:
type: string
description: '| Error Code | Description |
|------------|-------------|
| TRANSACTION_NOT_FOUND | Transaction not found |
| INVITATION_NOT_FOUND | Invitation not found |
| USER_NOT_FOUND | Customer not found |
| QUOTE_NOT_FOUND | Quote not found |
| LOOKUP_REQUEST_NOT_FOUND | Lookup request not found |
| TOKEN_NOT_FOUND | Token not found |
| BULK_UPLOAD_JOB_NOT_FOUND | Bulk upload job not found |
| REFERENCE_NOT_FOUND | Reference not found |
| UMA_NOT_FOUND | The UMA address is well-formed but no receiver exists at the counterparty VASP |
| STABLECOIN_PROVIDER_ACCOUNT_NOT_FOUND | Stablecoin provider account link not found |
'
enum:
- TRANSACTION_NOT_FOUND
- INVITATION_NOT_FOUND
- USER_NOT_FOUND
- QUOTE_NOT_FOUND
- LOOKUP_REQUEST_NOT_FOUND
- TOKEN_NOT_FOUND
- BULK_UPLOAD_JOB_NOT_FOUND
- REFERENCE_NOT_FOUND
- UMA_NOT_FOUND
- STABLECOIN_PROVIDER_ACCOUNT_NOT_FOUND
message:
type: string
description: Error message
details:
type: object
description: Additional error details
additionalProperties: true
VerificationStatus:
type: string
enum:
- RESOLVE_ERRORS
- PENDING_MANUAL_REVIEW
- IN_PROGRESS
- APPROVED
- REJECTED
- READY_FOR_VERIFICATION
description: Current status of the KYC/KYB verification
example: RESOLVE_ERRORS
KycProvider:
type: string
description: 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.
enum:
- SUMSUB
example: SUMSUB
VerificationListResponse:
type: object
required:
- data
- hasMore
properties:
data:
type: array
description: List of verifications matching the filter criteria
items:
$ref: '#/components/schemas/Verification'
hasMore:
type: boolean
description: Indicates if more results are available beyond this page
nextCursor:
type: string
description: Cursor to retrieve the next page of results (only present if hasMore is true)
totalCount:
type: integer
description: Total number of results matching the criteria
BeneficialOwnerPersonalInfoUpdate:
type: object
description: Partial update for beneficial owner personal information. Only provided fields are updated.
properties:
firstName:
type: string
description: First name of the individual
example: Jane
middleName:
type: string
description: Middle name of the individual
example: Marie
lastName:
type: string
description: Last name of the individual
example: Smith
birthDate:
type: string
format: date
description: Date of birth in ISO 8601 format (YYYY-MM-DD)
example: '1978-06-15'
nationality:
type: string
description: Country of nationality (ISO 3166-1 alpha-2)
example: US
email:
type: string
format: email
description: Email address of the individual
example: jane.smith@acmecorp.com
phoneNumber:
type: string
description: Phone number in E.164 format
example: '+14155550192'
pattern: ^\+[1-9]\d{1,14}$
address:
$ref: '#/components/schemas/Address'
idType:
$ref: '#/components/schemas/IdentificationType'
identifier:
type: string
description: The identification number or value
example: 123-45-6789
countryOfIssuance:
type: string
description: Country that issued the identification (ISO 3166-1 alpha-2)
example: US
Error401:
type: object
required:
- message
- status
- code
properties:
status:
type: integer
enum:
- 401
description: HTTP status code
code:
type: string
description: '| Error Code | Description |
|------------|-------------|
| UNAUTHORIZED | Issue with API credentials |
| INVALID_SIGNATURE | Signature header is invalid |
| WALLET_SIGNATURE_MISSING | The `Grid-Wallet-Signature` header is required for this Embedded Wallet action but was not supplied |
| WALLET_SIGNATURE_MALFORMED | The `Grid-Wallet-Signature` header could not be parsed (bad encoding, structure, or fields) |
| WALLET_SIGNATURE_BODY_MISMATCH | The `Grid-Wallet-Signature` was computed over a different request body than the one received |
| WALLET_SIGNATURE_INVALID | The `Grid-Wallet-Signature` failed cryptographic verification against the registered credential |
| REQUEST_ID_MISSING | The `Request-Id` header is required on the signed retry but was not supplied (paired with `Grid-Wallet-Signature`) |
'
enum:
- UNAUTHORIZED
- INVALID_SIGNATURE
- WALLET_SIGNATURE_MISSING
- WALLET_SIGNATURE_MALFORMED
- WALLET_SIGNATURE_BODY_MISMATCH
- WALLET_SIGNATURE_INVALID
- REQUEST_ID_MISSING
message:
type: string
description: Error message
details:
type: object
description: Additional error details
additionalProperties: true
VerificationError:
type: object
required:
- resourceId
- type
- reason
properties:
resourceId:
type: string
description: ID of the resource with the issue (Customer, BeneficialOwner, or Document)
example: Customer:019542f5-b3e7-1d02-0000-000000000001
type:
$ref: '#/components/schemas/VerificationErrorType'
field:
type: string
description: Dot-notation path to the field with the issue. Present when type is MISSING_FIELD or INVALID_FIELD.
example: customer.address.line1
acceptedDocumentTypes:
type: array
items:
$ref: '#/components/schemas/DocumentType'
description: 'Document types that would satisfy this requirement. The integrator can upload any one of the listed types. Present when type is MISSING_LEGAL_PRESENCE_DOCUMENT, MISSING_CONTROL_STRUCTURE_DOCUMENT, MISSING_OWNERSHIP_STRUCTURE_DOCUMENT, MISSING_PROOF_OF_ADDRESS_DOCUMENT, MISSING_IDENTITY_DOCUMENT, INVALID_DOCUME
# --- truncated at 32 KB (46 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/lightspark/refs/heads/main/openapi/lightspark-kyc-kyb-verifications-api-openapi.yml