Skip to main content
POST
/
onboarding
Submit a customer onboarding application
curl --request POST \
  --url https://api.conduit.financial/v2/onboarding \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "businessInfo": {},
  "registeredAddress": {},
  "operatingAddress": {},
  "companyClassification": {},
  "businessActivity": {},
  "compliance": {},
  "regulatoryHistory": {},
  "ownership": {},
  "relatedCompany": {},
  "certification": {},
  "documentIds": [
    "doc_2xKjF9mQb7vN4hL1pR3w8t"
  ],
  "clientReferenceId": "ext_customer_8421"
}
'
{
  "id": "<string>",
  "status": "pending",
  "createdAt": "2026-01-15T09:30:00.000Z",
  "updatedAt": "2026-01-15T09:30:00.000Z",
  "type": "CUSTOMER_ONBOARDING",
  "clientReferenceId": "ext-12345",
  "submittedAt": "2026-01-15T09:30:00.000Z",
  "failureMessage": "<string>",
  "customerId": "<string>"
}

Authorizations

​
x-api-key
string
header
required

Headers

​
Idempotency-Key
string
required

Caller-generated unique key that lets the server safely replay this request. The cached response is returned for 5 minutes on any retry with the same key from the same API principal. Required on every state-changing money-moving or resource-creating POST.

Required string length: 1 - 128
Pattern: ^[A-Za-z0-9_.:-]{1,128}$

Body

application/json
​
businessInfo
object

Business-level data (e.g. taxId, legalName, tradeName). Inner shape resolved from GET /v2/onboarding/requirements.

​
registeredAddress
object

Registered business address. Inner shape (e.g. street1, city, state, zipCode, country) resolved from requirements; country accepts ISO 3166-1 alpha-2 or alpha-3.

​
operatingAddress
object

Operating address when different from registeredAddress. Same inner shape and country rules.

​
companyClassification
object

Legal-structure and industry classification (e.g. legalStructure, coreIndustry). Inner shape resolved from requirements.

​
businessActivity
object

Operating-activity descriptors (e.g. countries of activity, expected volumes). Inner shape resolved from requirements.

​
compliance
object

Compliance-attestation fields. Inner shape resolved from requirements.

​
regulatoryHistory
object

Regulatory and adverse-action history. Inner shape resolved from requirements.

​
ownership
object

Beneficial-owner and controlling-person disclosure under ownership.persons[]. Inner shape resolved from individualRequirements[]; each person carries roles[], scalar identity fields, and documentIds[]. referenceId is server-owned (minted and preserved by Conduit); any client-supplied value is ignored.

​
relatedCompany
object

Related-company disclosure for affiliated entities. Inner shape resolved from requirements.

​
certification
object

Legal certifications the customer must affirm (e.g. termsAndConditions: true). Inner shape resolved from requirements; mustEqual: true markers in discovery indicate exact-value gates.

​
documentIds
string[]

Customer-level document IDs from POST /v2/documents to attach to this onboarding. Per-person documents go on ownership.persons[i].documentIds[].

Minimum string length: 1
Example:
["doc_2xKjF9mQb7vN4hL1pR3w8t"]
​
clientReferenceId
string

Optional integrator-supplied identifier echoed back on the application record for cross-system correlation.

Pattern: ^[A-Za-z0-9_\-:.]{1,255}$
Example:

"ext_customer_8421"

Response

The submitted onboarding application

​
id
string
required

Unique application identifier

Pattern: ^app_[0-9A-Za-z]{22}$
​
status
enum<string>
required

Current lifecycle status of the application

Available options:
pending,
processing,
approved,
rejected,
cancelled
Example:

"pending"

​
createdAt
string<date-time>
required

Timestamp when the application was created

Example:

"2026-01-15T09:30:00.000Z"

​
updatedAt
string<date-time>
required

Timestamp when the application was last modified

Example:

"2026-01-15T09:30:00.000Z"

​
type
enum<string>
required
Available options:
CUSTOMER_ONBOARDING
​
clientReferenceId
string

Client-provided identifier for cross-referencing. Omitted when the client did not supply one.

Pattern: ^[A-Za-z0-9_\-:.]{1,255}$
Example:

"ext-12345"

​
submittedAt
string<date-time>

Timestamp when the application was submitted for review. Omitted while still in progress.

Example:

"2026-01-15T09:30:00.000Z"

​
failureCode
enum<string>

Machine-readable failure code on rejected applications. Omitted on non-rejected applications.

Available options:
REJECTED_BY_OPS,
COMPLIANCE_DENIED
​
failureMessage
string

Customer-facing failure message accompanying failureCode. Omitted on non-rejected applications.

​
customerId
string

Customer this onboarding application produced. Omitted while the application is still being reviewed; present after approval persists the customer row.

Pattern: ^cus_[0-9A-Za-z]{22}$