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 the hosted flow, they provide business details, control persons and documents directly in the Conduit form.
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 they complete liveness to proceed with review.
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 livenessLinks with a verificationUrl per 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 verificationUrl from livenessLinks to 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.