> ## Documentation Index
> Fetch the complete documentation index at: https://v2.docs.conduit.financial/llms.txt
> Use this file to discover all available pages before exploring further.

# CUSTOMER_NOT_ONBOARDED

> The operation requires a customer who has completed onboarding

## 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`.

```json theme={null}
{
  "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:

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
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:

```json theme={null}
{
  "type": "application.approved",
  "data": {
    "id": "app_xyz789",
    "status": "approved",
    "customerId": "cus_abc123"
  }
}
```

<Note>
  Do not poll for application status. Configure a webhook endpoint and Conduit will notify you when the review is complete.
</Note>

**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

## Related endpoints

* [GET /v2/customers/:id](/api-reference/customers/get-a-customer-by-id) -- retrieve customer details
* [GET /v2/applications](/api-reference/applications/list-all-applications) -- list applications for a customer
* [GET /v2/onboarding/requirements](/api-reference/customer-onboarding/discover-onboarding-requirements-for-a-country) -- check onboarding requirements
* [POST /v2/onboarding](/api-reference/customer-onboarding/submit-a-customer-onboarding-application) -- submit an onboarding application