Customers:KYB via API
Overview
This API allows clients to submit KYB/KYC data directly via API, bypassing the need for a verification link. This is useful for clients who already have all KYB/KYC data and documents collected in their own systems.The typical workflow is as follows:
- Create a customer using this API and store the returned customerId for future use.
- Add control persons or UBOs (Ultimate Beneficial Owners) associated with the customer.
- Upload KYB documents for the customer. You can find the list of supported KYB documents here.
- Upload KYC documents for each control person or UBO. The list of required KYC documents is provided here.
- Trigger the verification process once all required documents have been uploaded by calling this endpoint.
Monitor the review status via webhooks to receive asynchronous updates on all relevant events.
Coming Soon
This API is currently in QA and is not yet available in production.
Functionality and payloads may change before general release.
Authentication
All requests must include your API credentials:
curl -X POST https://api.conduit.financial/[END_POINT] \
-H "X-API-Key: your_api_key" \
-H "X-API-Secret: your_api_secret" \
-H "Content-Type: application/json"
Step 1: Create Customer
Endpoint: POST /customer/onboarding
Create a new business entity (customer) in the Conduit platform by providing core business information. This will return a unique customer_id, which is used in all subsequent KYB/KYC steps such as:
• Adding control persons / UBOs
• Uploading KYB and KYC documents
• Monitoring verification status
Request Example:
curl --request POST \
--url https://api.conduit.financial/customers/onboarding \
--header "Content-Type: application/json" \
--data '{
"businessLegalName": "Eggz Foundation LTD",
"country": "USA",
"registeredDate": "2024-01-01",
"website": "https://acme.com",
"industry": "Technology",
"taxIdentificationNumber": "123456789",
"businessEntityId": "BE001",
"isFinancialInstitution": true,
"email": "[email protected]",
"phone": "09009988",
"naisCode": "NAIS001",
"registeredAddress": {
"streetLine1": "123 Business St",
"city": "New York",
"state": "NY",
"postalCode": "10001",
"country": "USA"
},
"operatingAddress": {
"streetLine1": "456 Office Ave",
"city": "New York",
"state": "NY",
"postalCode": "10002",
"country": "USA"
}
}
Response:
{
"id": "cus_30V7EQpemfcgMctQUjDKf1sQLtA",
"status": "created"
}
Step 2: Add Control Persons or UBOs
Endpoint: POST /customers/{customer_id}/control-persons
After creating the customer, attach list of UBOs or Control persons that are key individuals related to the customer. Each control person can have a role (e.g., "beneficial_owner", "control_person"), and must be linked to the customer via their customer_id.
Request:
curl --location 'https://staging.dev-api.conduit.financial/customers/cus_abc123/control-persons' \
--header 'x-api-key: your_api_key' \
--header 'x-api-secret: your_api_secret' \
--header 'Api-Version: 2024-12-01' \
--header 'Content-Type: application/json' \
--data-raw '{
"controlPersons": [
{
"firstName": "Jane",
"lastName": "Doe",
"email": "[email protected]",
"birthDate": "2000-01-01T00:00:00.000Z",
"gender": "female",
"nationality": "USA",
"sharesAllocated": 100,
"ownershipPercentage": 100,
"address": {
"streetLine1": "123 Main St",
"city": "New York",
"state": "NY",
"postalCode": "10001",
"country": "USA"
},
"roles": [
{
"name": "beneficial_owner",
}
]
}
]
}'
Response
On success, the API will return the control persons with their Ids, these are will what be used to upload their individual KYC documents in the next steps:
{
"success": true,
"customerId": "cus_30V7EQpemfcgMctQUjDKf1sQLtA",
"controlPersons": [
{
"id": "ctl_31ppx3Ghgf53NcSDwr5xaZWG3l1",
"firstName": "John",
"lastName": "Doe",
"email": "[email protected]",
"birthDate": "2000-01-01T00:00:00.000Z",
"address": {
"streetLine1": "123 Main St",
"streetLine2": "",
"city": "New York",
"state": "NY",
"postalCode": "10001",
"country": "USA"
},
"nationality": "USA",
"gender": "female",
"ownershipPercentage": "100",
"referenceId": "31ppwzPk0V0QBJpl0qpyI9RCQSY",
"sharesAllocated": "100",
"kycStatus": "pending",
"identityInfo": {
"documentCountry": "",
"documentType": "",
"documentNumber": "",
"documentIssueDate": "",
"documentExpiryDate": ""
},
"roles": [
{
"name": "beneficial_owner"
}
]
}
]
}
Step 3 : Upload KYB Documents
Endpoint: /customers/onboarding/:id/documents
Use this endpoint to upload KYB (Know Your Business) documents for a customer or a control person during onboarding.
The API supports uploading:
• The front of a document (required)
• The back of the document (optional), for two-sided documents such as driver’s licenses
Note: If the document only has one side, upload it using the front field only
Sample Request
curl --location 'https://staging.dev-api.conduit.financial/customers/onboarding/cus_XXXXXXXXXXXXXX/documents' \
--header 'x-api-key: YOUR_API_KEY' \
--header 'x-api-secret: YOUR_API_SECRET' \
--header 'Api-Version: 2024-12-01' \
--form 'name="Test Contract"' \
--form 'purpose="kyb"' \
--form 'type="proof_address"' \
--form 'front=@"/path/to/front_image.png"' \
Response
Step 4: Upload KYC Document
Endpoint: /customers/onboarding/:id/documents
Use this same endpoint to upload your control person's KYC documents. The request is the same the only difference is that you are required to provide the controlPersonId of the control persons who document this belongs to .
Request
curl --location 'https://staging.dev-api.conduit.financial/customers/onboarding/cus_2zAq9OUNsBKSkrdmFoPC6Ci6j08/documents' \
--header 'x-api-key: key_2wSS0EECUF24XWkQ3fg7NY74bOg' \
--header 'x-api-secret: tzWdu8kfhznIb8f2BvYrrXtm+ptPocCVQ7v7JVLySSC5giNM31oOv3BJhshE/khCg1QxD+nUuGFTboVtxtxUMQ==' \
--header 'Api-Version: 2024-12-01' \
--form 'name="Test Contract"' \
--form 'purpose="kyc"' \
--form 'type="passport"' \
--form 'back=@"/Users/mac/Downloads/placeholder.png"' \
--form 'front=@"/Users/mac/Downloads/placeholder.png"' \
--form 'controlPersonId="ctl_1234"'
Step 5: Trigger Verification
Endpoint: POST /customers/:customerId/verify
Next Step
Once the customer is created, our system reviews the submitted KYB/KYC data, sends the results asynchronously via the Webhook Events API (see Webhook Documentation for details), and you should handle customer.active |customer.compliance_rejected events to update your records.
Updated about 21 hours ago