Submit Applicant (KYC/KYB)

Submits KYC (individual) or KYB (business) verification details for a customer against a specific
product. Send either the kyc object or the kyb object - exactly one is required.

Prerequisites: the customer and the product must already exist.

Application status values

Status	Meaning
`Draft`	Details saved, not yet submitted
`Pending`	Awaiting processing
`Submitted`	Submitted for verification
`UnderReview`	Verification in progress
`NeedInformation`	More information or documents required
`Approved`	Applicant verified
`Rejected`	Verification rejected
`Cancelled` / `Failed`	Application cancelled or failed

Required Fields

Field	Type	Description
`kyc`	`object`	Individual applicant - required when the customer type is `individual`
`kyb`	`object`	Business applicant - required when the customer type is `business`

kyc.person

Field	Type	Description	Constraints
`firstName` / `lastName`	`string`	Applicant name	Max: 100
`dateOfBirth`	`string (date)`	`YYYY-MM-DD`	Pattern: `^\d{4}-(0[1-9]\|1[0-2])-(0[1-9]\|[12]\d\|3[01])$`
`gender`	`string`	e.g. `male`, `female`, `other`	-
`email`	`string (email)`	Applicant email	Max: 256
countryIsoTwo	string	Applicant country ISO 2-letter code	Max: 2
`phoneCountryCode`	`string`	Dialling code	Max: 8 - Pattern: `^\+?\d{1,6}$`
`phoneNumber`	`string`	Phone number	Max: 20
`occupation`	`string`	Occupation	Max: 100
`emergencyContactName`	`string`	Emergency contact	Max: 100
`annualSalary`	`number`	Annual salary	0 - 999999999999
`accountPurpose`	`string`	Purpose of the account	Max: 100
`expectedMonthlyVolume`	`number`	Expected monthly volume	0 - 999999999999

kyc.address

Field	Type	Constraints
`addressLine1` / `addressLine2`	`string`	Max: 1024
`town` / `city` / `state`	`string`	Max: 100
`postalCode`	`string`	Max: 16
`addressCountryIsoTwo`	`string`	2-3 letters; must exist in the country master

kyc.documents[] - one unified list. The item's type decides how it is handled:

`type` value	Treated as	Fields used
`PASSPORT`, `NATIONAL_ID`, `ID_CARD`, `DRIVERS_LICENSE`, `RESIDENCE_PERMIT`, `VOTER_ID`	Primary identity document - send only one	`documentNumber`, `issueDate`, `expiryDate`, `frontUrl`, `backUrl`
`SELFIE`, `SIGNATURE`, `BIOMETRIC`, `HANDHELD_ID`, `CARD_HANDHELD_ID`	Single-image biometric capture	`frontUrl`
anything else	Supporting document (proof of address, secondary ID, ...)	`frontUrl`

type is required on every item (max 100); documentNumber max 100; issueDate/expiryDate are
YYYY-MM-DD; frontUrl/backUrl must be absolute URLs (max 2048). type is case-insensitive.

kyc top level (optional)

Field	Type	Description	Constraints
`ipAddress`	`string`	IP address the submission came from	Max: 45
`kycRequirements`	`string`	Which requirement set this submission satisfies (see the product's `kycRequirements`)	Max: 1024

kyb.company

Field	Type	Constraints
`companyName` / `companyType` / `industry`	`string`	Max: 100
`description`	`string`	Max: 1024
`registrationNumber` / `taxId`	`string`	Max: 100
`website`	`string (uri)`	Valid URL
`certificateOfIncorporationUrl` / `shareholderRegistryUrl` / `taxDocumentUrl`	`string (uri)`	Supporting document URLs
`companyAddress`	`object`	`addressType`, `addressLine1`, `addressLine2`, `town`, `city`, `state`, `postalCode`, `countryIsoTwo`
`requiredDocuments[]`	`array`	`documentType` (100), `documentUrl` (2048)

kyb.primaryContact, kyb.representatives[], kyb.directors[], kyb.ubos[]

Field	Type	Description	Constraints
`personDetails.firstName` / `lastName`	`string`	Person name	Max: 100
`personDetails.dateOfBirth`	`string (date)`	`YYYY-MM-DD`	-
`personDetails.gender`	`string`	Gender	-
`personDetails.countryIsoTwo`	`string`	ISO country code	2-3 letters
`personDetails.email`	`string (email)`	Email	Max: 256
`personDetails.phoneCountryCode` / `phoneNumber`	`string`	Phone	Max: 8 / 20
`personDetails.shareholderPercentage`	`string`	Ownership percentage	Max: 8
`documents[]`	`array`	`documentType`, `documentNumber`, `countryIsoTwo`, `documentIssueDate`, `documentExpiryDate`, `frontDocumentUrl`, `backDocumentUrl`	dates `YYYY-MM-DD`, URLs max 2048
`selfieUrl`	`string (uri)`	Liveness selfie	Max: 2048
`address`	`object`	Same shape as `companyAddress`	-
`id` / `recordStatus`	`uuid` / `string`	Only on `representatives`/`directors`/`ubos` - supply `id` to update an existing member	-
`kyb.ipAddress`	`string`	IP address the submission came from	Max: 45

Response Fields (inside data)

Field	Type	Description
`customerId`	`string (uuid)`	Customer the applicant record belongs to
`productId`	`string (uuid)`	Product the applicant record was submitted for
`walletId`	`string (uuid)`	Wallet associated with the card
`applicationStatus`	`string`	See the status table above
`applicationReason`	`string`	Human-readable status detail (empty when there is none)

Supply employeeId when the product is issued for an employee - the details are then verified
against that employee. Omit it when the customer is onboarding themselves.

curl --location '/api/v1/customers/3fa85f64-5717-4562-b3fc-2c963f66afa6/products/b1f3c7a2-6c4e-4d91-9f2a-123456789abc/applicant?employeeId=a3d5c8e2-1234-4abc-9def-0123456789ab' \ --header 'X-API-Key;' \ --header 'X-Signature;' \ --header 'X-Timestamp;' \ --header 'X-Nonce;' \ --header 'X-Body-Hash;' \ --header 'X-Idempotency-Key;' \ --header 'Content-Type: application/json' \ --data-raw '{ "kyc": { "person": { "firstName": "Jane", "lastName": "Doe", "dateOfBirth": "1990-06-15", "gender": "female", "email": "jane.doe@example.com", "countryIsoTwo": "GB", "phoneCountryCode": "+44", "phoneNumber": "7700900000", "occupation": "software_engineer", "emergencyContactName": "John Doe", "annualSalary": 75000, "accountPurpose": "personal_spending", "expectedMonthlyVolume": 5000 }, "address": { "addressLine1": "10 Downing Street", "addressLine2": "Flat 2", "city": "London", "state": "England", "postalCode": "SW1A 2AA", "addressCountryIsoTwo": "GB" }, "documents": [ { "type": "PASSPORT", "documentNumber": "AB1234567", "issueDate": "2020-01-01", "expiryDate": "2030-01-01", "frontUrl": "https://storage.blob.core.windows.net/docs/passport_front.jpg", "backUrl": "https://storage.blob.core.windows.net/docs/passport_back.jpg" }, { "type": "SELFIE", "frontUrl": "https://storage.blob.core.windows.net/docs/selfie.jpg" }, { "type": "PROOF_OF_ADDRESS", "frontUrl": "https://storage.blob.core.windows.net/docs/utility_bill.pdf" } ], "ipAddress": "192.168.1.10", "kycRequirements": "FullName,Comms,FullAddress,IdDocument,Selfie" } }'

{ "data": { "customerId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "productId": "b1f3c7a2-6c4e-4d91-9f2a-123456789abc", "walletId": "3fa85f64-5717-3462-b3fc-2c963f66efa6", "applicationStatus": "UnderReview", "applicationReason": "" }, "requestId": "9f2c4b6e8a1d4f0cb7e35a91d2c46f80", "timestamp": "2026-08-22T10:30:00.123Z" }

Request

Responses