Skip to main content

​
Pre-requisites

  • Active Conduit account with API access
  • API credentials (API Key and Secret)
  • You have reviewed our Customers Core Concepts

​
Hosted Onboarding

1

Hosted Onboarding (Generate a KYB Link)

Create a hosted KYB link for your customer to complete onboarding in the browser. This single call creates the customer (if needed) and returns the 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",
  }'

​
Response Example

{
  "id": "cus_2ofTA13AD0xBtbEvBl20aEb1hEu",
  "kybLink": "https://example.com/kyb/verify/abc123",
  "kybLinkExpiration": "2024-12-31T23:59:59.000Z",
  "businessLegalName": "Example Business"
}
Share this link with your customer. In the hosted flow, they provide business details, control persons and documents directly in the Conduit form.

​
Direct Onboarding (API-first)

1

Direct Onboarding (API-first): Create a Customer

Create a customer record to start the API-first onboarding flow.

​
Request Example

curl --request POST \
  --url https://api.conduit.financial/customers/onboarding \
  --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",
    "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

{
  "id": "cus_30V7EQpemfcgMctQUjDKf1sQLtA",
  "status": "created"
}
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

{
    "id": "cus_33NCzXLTQKphS1IyOG9GXinSqgW",
    "type": "business",
    "businessLegalName": "Leonard ACT Test 8",
    "businessTradeName": "Leonard ACT Test 8",
    "industry": "Technology",
    "email": "Elton_Weissnat45@example.org",
    "phone": "09009988",
    "website": "https://acme.com",
    "registeredDate": "2024-01-01",
    "registeredAddress": {
        "city": "New York",
        "state": "NY",
        "country": "USA",
        "postalCode": "10002",
        "streetLine1": "456 Office Ave",
        "streetLine2": "456 Office Ave"
    },
    "operatingAddress": {
        "city": "New York",
        "state": "NY",
        "country": "USA",
        "postalCode": "10002",
        "streetLine1": "456 Office Ave",
        "streetLine2": "456 Office Ave"
    },
    "kybLink": null,
    "kybLinkExpiration": null,
    "kybLinkGeneratedAt": null,
    "kybCompletedAt": null,
    "isOperating": true,
    "purposeOfAccount": null,
    "taxClassification": null,
    "anticipatedMonthlyVolume": {
        "ach": {
            "incoming": 100000,
            "outgoing": 80000
        },
        "wire": {
            "incoming": 50000,
            "outgoing": 30000
        },
        "check": {
            "incoming": 10000,
            "outgoing": 5000
        }
    },
    "expectedAverageDailyBalance": "250000",
    "fundingSources": null,
    "regulatorName": "SEC",
    "hasAdvisor": true,
    "status": "in_compliance_review",
    "organizationId": "client_2wSRw4TK502rQd4uDek220ritKV",
    "tags": null,
    "kybData": null,
    "industryData": null,
    "businessDescription": "Provider of industrial widgets and services",
    "llcTaxedAs": null,
    "businessEntityType": "Corporation",
    "entityType": null,
    "taxIdentificationNumber": "1234440",
    "businessEntityId": "BE001",
    "isSubsidiary": false,
    "kybSetupBy": "client",
    "createdAt": "2025-09-29T12:20:04.268Z",
    "updatedAt": "2025-09-29T12:20:04.335Z",
    "deletedAt": null,
    "isFinancialInstitution": true,
    "eddFormId": null,
    "identifications": [
        {
            "id": "33NCzUXybWYo21Ra7gDWolFmUzr",
            "identificationType": "TIN",
            "identificationNumber": "1234440"
        }
    ],
    "documents": [],
    "controlPersons": [
        {
            "id": "ctl_33ND2DxJ1ssfvEq746oyOpGhKWW",
            "firstName": "John",
            "lastName": "Doe2",
            "middleName": "Michael",
            "email": "Gene.Hansen@hotmail.com",
            "roles": [
                {
                    "name": "beneficial_owner",
                    "current": true
                }
            ],
            "sharesAllocated": 100,
            "ownershipPercentage": 100,
            "address": {
                "city": "New York",
                "state": "NY",
                "country": "USA",
                "postalCode": "10001",
                "streetLine1": "123 Main St",
                "streetLine2": "Suite 100"
            },
            "referenceId": "33ND2BaHMttsqeFdPOD33A10U3Z",
            "birthDate": "2000-01-01T00:00:00.000+00:00",
            "phone": "+1234567890",
            "immigrationStatus": "citizen",
            "taxResidencyCountry": "USA",
            "title": "CEO",
            "regulatoryAffiliations": [
                {
                    "regulatoryAffiliation": "FINRA"
                }
            ],
            "numberType": "ssn",
            "role": null,
            "isEntity": false,
            "nationality": "USA",
            "gender": "male",
            "kycStatus": "pending",
            "identityInfo": {
                "documentType": "passport",
                "documentNumber": "1234567890",
                "documentCountry": "USA",
                "documentIssueDate": "2021-01-01",
                "documentExpiryDate": "2025-01-01"
            }
        }
    ],
    "paymentMethods": []
}

​
🎉 You’re done!

Once the customer status is active, they’re verified and ready to:

​
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.
⌘I