Skip to main content

​
Pre-requisites

​
Hosted Onboarding

1

Hosted Onboarding (Generate a KYB Link)

Create the customer and request a hosted KYB link in a single call by setting onboardingFlow: kyb_link.Endpoint: POST /customers

​
Request Example

curl --request POST \
  --url https://api.conduit.financial/customers \
  --header "X-API-Key: your_api_key" \
  --header "X-API-Secret: your_api_secret" \
  --header "Content-Type: application/json" \
  --header "Api-Version: 2024-12-01"
  --data '{
  "businessLegalName": "Acme Corporation Inc.",
  "country": "USA",
  "onboardingFlow": "kyb_link"
  }'

​
Response Example

{
  "id": "cus_2ofTA13AD0xBtbEvBl20aEb1hEu",
  "onboardingFlow": "kyb_link",
  "kybLink": "https://example.com/kyb/verify/abc123",
  "kybLinkExpiration": "2024-12-31T23:59:59.000Z",
  "businessLegalName": "Example Business"
}
2

Hosted Onboarding: Share the KYB Link

Share this link with your customer. In this hosted flow your customer will provide their business details, information on control persons, and documents directly to us by filling up the KYB link.
3

Hosted Onboarding: Monitor the Status

Monitor the status of the customer onboarding process via webhooks or the dashboard. Learn more about creating a webhook here.After submission, liveness links are provided per control person; ensure your customer’s control persons’ complete liveness selfie check to proceed with review. and account opening
4

Hosted Onboarding: Renew the KYB Link

If the KYB link expires, you can generate a new one by creating a new customer with the same customerId.

​
Request Example

curl --request POST \
--url https://sandbox-api.conduit.financial/customers/{id}/kyb-link \
--header 'X-API-Key: <api-key>' \
--header 'X-API-Secret: <api-key>'

​
Response Example

{
"message": "KYB verification link created successfully",
"verification_url": "https://example.com/kyb/verify/abc123"
}

​
Direct Onboarding (API-first)

1

Direct Onboarding (API-first): Create a Customer

Create the customer with onboardingFlow: direct and include business information to start the API-first onboarding flow.

​
Request Example

curl --request POST \
  --url https://api.conduit.financial/customers \
  --header "X-API-Key: your_api_key" \
  --header "X-API-Secret: your_api_secret" \
  --header "Content-Type: application/json" \
  --header "Api-Version: 2024-12-01" \
  --data '{
    "businessLegalName": "Acme Corporation Inc.",
    "country": "USA",
    "registeredDate": "2024-01-01",
    "website": "https://acme.com",
    "onboardingFlow": "direct",
    "industry": "Technology",
    "taxIdentificationNumber": "12-3456789",
    "email": "[email protected]",
    "phone": "+1234567890",
    "naicsCode": "541511",
    "registeredAddress": {
      "streetLine1": "456 Office Ave",
      "streetLine2": "Suite 200",
      "city": "New York",
      "state": "NY",
      "postalCode": "10002",
      "country": "USA"
    },
    "operatingAddress": {
      "streetLine1": "456 Office Ave",
      "streetLine2": "Suite 200",
      "city": "New York",
      "state": "NY",
      "postalCode": "10002",
      "country": "USA"
    },
    "businessEntityType": "Corporation",
    "businessEntityId": "BE001",
    "businessDescription": "Provider of industrial widgets and services",
    "isOperating": true,
    "isSubsidiary": false,
    "isFinancialInstitution": false,
    "regulatorName": "SEC",
    "purposeOfAccount": "Operating expenses and payroll"
  }'

​
Response Example

{
  "onboardingFlow": "direct",
  "id": "cus_2ofTA13AD0xBtbEvBl20aEb1hEu",
  "status": "created",
  "businessLegalName": "Acme Corporation Inc."
}
Success! Save this customerId - you’ll need it for subsequent steps
2

Direct Onboarding: Add Control Persons

Register individuals with 25%+ ownership or significant control over the business.

​
Request Example

Endpoint: POST /customers/{customer_id}/control-persons

​
Request Example

curl --request POST \
  --url https://api.conduit.financial/customers/cus_30V7EQpemfcgMctQUjDKf1sQLtA/control-persons \
  --header "X-API-Key: your_api_key" \
  --header "X-API-Secret: your_api_secret" \
  --header "Content-Type: application/json" \
  --header "Api-Version: 2024-12-01" \
  --data '{
    "controlPersons": [
      {
        "firstName": "John",
        "lastName": "Doe",
        "email": "[email protected]",
        "birthDate": "1980-01-15",
        "nationality": "USA",
        "phone": "+1234567890",
        "ownershipPercentage": 100,
        "ssn": "123-45-6789",
        "address": {
          "streetLine1": "123 Main St",
          "city": "New York",
          "state": "NY",
          "postalCode": "10001",
          "country": "USA"
        },
        "roles": [
          {
            "name": "beneficial_owner",
            "startDate": "2024-01-01",
            "current": true
          }
        ],
        "identityInfo": {
          "documentCountry": "USA",
          "documentType": "passport",
          "documentNumber": "123456789",
          "documentIssueDate": "2020-01-01",
          "documentExpiryDate": "2030-01-01"
        }
      }
    ]
  }'

​
Response Example

{
  "success": true,
  "customerId": "cus_30V7EQpemfcgMctQUjDKf1sQLtA",
  "controlPersons": [
    {
      "id": "ctl_2nqjHpNLK6wSNlFyMvZgX8SYeAO",
      "firstName": "John",
      "lastName": "Doe",
      "email": "[email protected]"
    }
  ]
}
Save each controlPersonId - you’ll use them when uploading KYC documents
3

Direct Onboarding: Upload KYB Documents

Upload business verification documents (KYB) for the business entity.Endpoint: POST /customers/onboarding/{customer_id}/documents Use the purpose="kyb" to upload business verification documents (KYB).

​
Request Example

curl --request POST \
  --url https://api.conduit.financial/customers/onboarding/cus_30V7EQpemfcgMctQUjDKf1sQLtA/documents \
  --header "X-API-Key: your_api_key" \
  --header "X-API-Secret: your_api_secret" \
  --header "Api-Version: 2024-12-01" \
  --form 'name="Articles of Incorporation"' \
  --form 'purpose="kyb"' \
  --form 'type="articles_of_incorporation"' \
  --form 'front=@"/path/to/articles.pdf"'

​
Response Example


{
 "id": "doc_2nqjHpNLK6wSNlFyMvZgX8SYeAO",
 "createdAt": "2024-10-26T02:21:03.742Z"
}
4

Direct Onboarding: Upload KYC Documents

Upload identity documents (KYC) for each registered control person.Endpoint: POST /customers/onboarding/{customer_id}/documentsUse the purpose="kyc" to upload identity documents (KYC).Use the controlPersonId to upload identity documents for a specific control person.

​
Request Example

curl --request POST \
  --url https://api.conduit.financial/customers/onboarding/cus_30V7EQpemfcgMctQUjDKf1sQLtA/documents \
  --header "X-API-Key: your_api_key" \
  --header "X-API-Secret: your_api_secret" \
  --header "Api-Version: 2024-12-01" \
  --form 'name="John Doe Passport"' \
  --form 'purpose="kyc"' \
  --form 'type="passport"' \
  --form 'controlPersonId="ctl_2nqjHpNLK6wSNlFyMvZgX8SYeAO"' \
  --form 'front=@"/path/to/passport.jpg"'
5

Direct Onboarding: Submit for Review

Submit onboarding data for compliance review.Endpoint: POST /customers/{customer_id}/submit

​
Request Example

curl --request POST \
  --url https://api.conduit.financial/customers/cus_30V7EQpemfcgMctQUjDKf1sQLtA/submit \
  --header "X-API-Key: your_api_key" \
  --header "X-API-Secret: your_api_secret" \
  --header "Content-Type: application/json" \
  --header "Api-Version: 2024-12-01"

​
Response Example

{
  "success": true,
  "status": "manual_review",
  "livenessLinks": [
    {
      "controlPersonId": "ctl_34yPkFSqTUpwOwe0zoovDKU9Yad",
      "verificationUrl": "https://verify.example.com/?verification_session_id=abc"
    }
  ]
}
Response includes livenessLinkswith a verificationUrlper control person. Save these links. Use them to complete liveness as this is a mandatory step in the onboarding process.
6

Direct Onboarding: Complete Liveness Checks

Use each verificationUrlfrom livenessLinksto prompt the corresponding control person to complete liveness. Once completed, the onboarding review proceeds automatically.
7

Direct Onboarding: Fetch Latest Liveness Link (if needed)

If you didn’t save the link, you can fetch the latest liveness information for a control person.Endpoint: GET /customers/:customer_id/control-persons/:control_person_id/liveness

​
Request Example

curl --request GET \
  --url "https://api.conduit.financial/customers/cus_30V7EQpemfcgMctQUjDKf1sQLtA/control-persons/ctl_2nqjHpNLK6wSNlFyMvZgX8SYeAO/liveness" \
  --header "X-API-Key: your_api_key" \
  --header "X-API-Secret: your_api_secret" \
  --header "Api-Version: 2024-12-01"

​
Response Example

{
  "controlPersonId": "ctl_2nqjHpNLK6wSNlFyMvZgX8SYeAO",
  "verificationUrl": "https://verify.example.com/?verification_session_id=abc",
  "status": "PENDING",
  "expirationDate": "2025-12-31T23:59:59.000Z"
}

​
Summary

Once the customer status is active, they’re verified and ready to:
A Virtual USD Account is provisioned for the customer after onboarding is completed. Learn more: Virtual USD Accounts.

​
What’s next?

​
API Reference

Check our API Reference to learn how to create and manage customers using our API.

​
Support

Reach out to our support team to get help and share your feedback.