---
title: "How onboarding works, and customer statuses"
description: "What a Nodu customer is, the two steps of onboarding, and what each customer, verification and application status means."
url: "/guides/customers/how-onboarding-works/"
index: "/llms.txt"
---

# How onboarding works, and customer statuses

A customer is the person or business that you onboard and move money for. Create the customer, obtain terms acceptance and complete verification using your [onboarding model](/guides/customers/onboarding-models/index.md). Use the status tables below to follow progress and decide when the customer can transact.

## Customers

You create a customer with [Create a customer](/api/tag/customers/post-v1-customers.md). Nodu returns the customer's `id`. Every later call for that customer uses this `id`: the terms, verification, payment channels, external accounts and transfers. Store the `id` with your own record of the customer.

A customer has one of two types:

- `individual`: a person.
- `business`: a company. You send the company name, and the name and email of the person who represents the company.

Create one customer for each person or company. A customer who returns to your platform continues with the same `id`.

## The two steps of onboarding

Onboarding starts when you create the customer. The new customer has `status=pending`. Then come two steps:

1. **Accept the Terms of Service.** The customer accepts Nodu's Terms of Service.
2. **Complete customer verification.** With hosted onboarding, the customer provides their information and documents on Nodu's verification page. With API onboarding, you provide all the required information and documents in an application, and submit it for verification. Nodu reviews them and decides.

If some information or documents need to be submitted again, Nodu can ask for them. The customer, or you with API onboarding, then corrects them and submits again: see [Resubmission and rejection](/guides/customers/resubmission-and-rejection/index.md). After Nodu's final decision, verification is `approved` and the customer becomes `active`, or verification is `permanently_rejected`.

Onboarding is complete when the customer has `status=active`. Nodu sends the `v1.customer.activated` event when the customer's `status` becomes `active`. Check the customer's `status` before you offer transfers. Only an `active` customer can transact. For a customer with another status, Nodu refuses new quotes, transfers and external accounts with `rule=customer_not_active`.

[Onboarding models](/guides/customers/onboarding-models/index.md) compares the ways in which Nodu receives the customer's information.

## Statuses

[Retrieve a customer](/api/tag/customers/get-v1-customers-customerid.md) returns three status fields. An application has a status of its own.

### Customer status

The `status` field says whether the customer can transact.


| `status` | Meaning | What you do |
|---|---|---|
| `pending` | Onboarding is not complete. | Read `tosAcceptanceStatus` and `verificationStatus` to see which part is not complete. Do not offer transfers. |
| `active` | The customer can transact. | Offer transfers. First check the customer's [payment channels](/guides/transfers/payment-channels/index.md). |
| `suspended` | Nodu has suspended the customer. The customer cannot transact. | Stop offering new transfers. See [Suspended and blocked customers](/guides/customers/resubmission-and-rejection/index.md#suspended-and-blocked-customers). |
| `blocked` | Nodu has blocked the customer. The customer cannot transact. | Stop offering new transfers. See [Suspended and blocked customers](/guides/customers/resubmission-and-rejection/index.md#suspended-and-blocked-customers). |

### Terms acceptance status


| `tosAcceptanceStatus` | Meaning | What you do |
|---|---|---|
| `pending` | The customer has not accepted Nodu's Terms of Service. | Obtain the acceptance in the way your onboarding model describes. |
| `accepted` | The customer has accepted the terms. | Nothing. |

### Verification status


| `verificationStatus` | Meaning | What you do |
|---|---|---|
| `pending_input` | Nodu is waiting for the customer's information and documents. | With hosted onboarding, redirect the customer to Nodu's verification page. With API onboarding, complete the application and submit it. |
| `under_review` | The information is submitted. Nodu is reviewing it. | Show the customer that the review is pending. Wait for the outcome. |
| `awaiting_associates` | The business has submitted its application. Nodu reviews it once its associates have completed their verification. | With hosted onboarding, redirect the customer to Nodu's verification page: it lists the associates who still have to verify and lets the customer send them their links. With API onboarding, follow [Associates of a business](/guides/customers/api-onboarding/associates-of-a-business/index.md). |
| `resubmission_required` | Nodu needs more information or a corrected document. | Follow [Resubmission and rejection](/guides/customers/resubmission-and-rejection/index.md). |
| `permanently_rejected` | Nodu has rejected the verification. The decision is final. | Show the outcome to the customer. Stop onboarding this customer. |
| `approved` | Nodu has approved the verification. | Nothing for verification. Check that `status=active` before you offer transfers. |

A business can move from `under_review` to `awaiting_associates` a few seconds after it submits, and back to `under_review` once its associates have completed their verification.

### Application status

An application is the set of information and documents that Nodu reviews for one customer. The customer object names the current application in `activeApplication`, with its `id` and `status`. [Retrieve an application](/api/tag/customers/get-v1-customers-customerid-applications-applicationid.md) returns the application itself.


| `status` | Meaning | What you do |
|---|---|---|
| `draft` | The application exists and is not submitted. | With API onboarding, complete the application and submit it. |
| `submitted` | Nodu has accepted the application. For a business, the review starts once its associates have completed their verification. | Wait for the outcome. You cannot change the application now. |
| `under_review` | Nodu is reviewing the application. | Wait for the outcome. You cannot change the application now. |
| `approved` | The review passed. | Check that the customer has `status=active`. |
| `rejected` | The review failed. The decision is final. | Show the outcome to the customer. You cannot correct this application or submit it again. |
| `resubmission_required` | Nodu needs corrections. | Read `rejection` in the application. Then follow [Resubmission and rejection](/guides/customers/resubmission-and-rejection/index.md). |

Not every application passes through every status. The customer has `activeApplication=null` when no application is in progress, for example after the application is `approved` or `rejected`. Store the application `id` if you want to read the application later.

## Follow status changes

Nodu sends a webhook event when a status changes: `v1.customer.tos_accepted`, `v1.customer.verification_under_review`, `v1.customer.verification_awaiting_associates`, `v1.customer.verification_approved`, `v1.customer.verification_resubmission_required`, `v1.customer.verification_permanently_rejected`, `v1.customer.activated`, `v1.customer.suspended` and `v1.customer.blocked`. [Receive and verify webhooks](/guides/api-basics/webhooks/index.md#event-types) describes each event.

An event is a notification, not the current state. The event contains the customer data from the time of the change. Events can arrive more than once and out of order. When an event conflicts with your stored information or the customer returns to your platform, call [Retrieve a customer](/api/tag/customers/get-v1-customers-customerid.md). Use the statuses in that response.

Submission and approval are separate steps. Submitting an application does not mean Nodu has approved it. After approval, check that the customer has `status=active`.

## Next steps

- [Onboarding models](/guides/customers/onboarding-models/index.md): choose how Nodu receives the customer's information.
- [Hosted onboarding](/guides/customers/hosted-onboarding/index.md): the steps when the customer uses Nodu's pages.
- [Onboard a customer through the API](/guides/customers/api-onboarding/create-a-customer-with-a-full-application/index.md): the steps when you collect the data yourself.
- [Test onboarding in the sandbox](/guides/sandbox/test-onboarding/index.md): produce each verification outcome in the test environment.
