Skip to main content

​
What happened

You attempted an operation that requires the customer to have completed the onboarding process, but the customer is not fully onboarded. This returns HTTP 422 with error code CUSTOMER_NOT_ONBOARDED. 
{
  "type": "CUSTOMER_NOT_ONBOARDED",
  "title": "Customer Not Onboarded",
  "status": 422,
  "detail": "Customer cus_abc123 has not completed onboarding.",
  "resolution": "Complete the customer onboarding process before attempting this operation. See the onboarding guide for the required steps.",
  "docs": "/errors#customer-not-onboarded",
  "instance": "/v2/customers/cus_abc123/features",
  "correlationId": "corr_xyz789",
  "timestamp": "2026-01-15T09:30:00.000Z"
}

​
Common causes

  • Onboarding not started — no application has been submitted for this customer
  • Application still in review — the customer’s application has been submitted but has not been approved yet
  • Application rejected — the customer’s application was reviewed and rejected

​
Recovery

1. Check the customer’s current state Retrieve the customer to see their onboarding status: 
curl -X GET https://api.conduit.financial/v2/customers/cus_abc123 \
  -H "x-api-key: YOUR_API_KEY"
2. Check existing applications See if the customer has any applications and their current status: 
curl -X GET https://api.conduit.financial/v2/applications?customerId=cus_abc123 \
  -H "x-api-key: YOUR_API_KEY"
3. If no application exists, start the onboarding flow First, discover the required fields and documents. country is required (ISO-3166 alpha-3) and drives which rules fire: 
curl -X GET 'https://api.conduit.financial/v2/onboarding/requirements?country=USA' \
  -H "x-api-key: YOUR_API_KEY"
Then upload any required documents and submit the onboarding application with all required fields. 4. If the application is in review, wait for the webhook Applications are reviewed automatically. Listen for the application.approved or application.rejected webhook events: 
{
  "type": "application.approved",
  "data": {
    "id": "app_xyz789",
    "status": "APPROVED",
    "customerId": "cus_abc123"
  }
}
Do not poll for application status. Configure a webhook endpoint and Conduit will notify you when the review is complete.
5. If the application was rejected Check the application details for the rejection reason. You may need to resubmit with corrected information or additional documents.

​
Prevention

  • Complete the onboarding flow before performing operations that require a business profile — wallet creation, quotes, and transactions all require an onboarded customer
  • Listen for webhook events — use application.approved to trigger downstream operations automatically, rather than attempting operations and handling this error
  • Track onboarding state in your system — maintain a local record of which customers have completed onboarding so you can prevent premature API calls