---
title: "Hosted onboarding"
description: "Onboard a customer on Nodu's pages: create the customer, redirect to the terms page and the verification page, and follow the outcome."
url: "/guides/customers/hosted-onboarding/"
index: "/llms.txt"
---

# Hosted onboarding

With hosted onboarding, the customer accepts Nodu's Terms of Service and completes verification on pages that Nodu hosts. Your platform creates the customer, sends the customer to those pages, and follows the outcome. [Onboarding models](/guides/customers/onboarding-models/index.md) compares hosted onboarding with onboarding in your own interface.

```mermaid
sequenceDiagram
    participant Customer
    participant You as Your system
    participant Nodu
    You->>Nodu: 1. Create the customer<br/>POST /v1/customers
    Nodu-->>You: The customer's id
    You->>Nodu: 2. Get the terms page with redirectUrl<br/>GET /v1/customers/{customerId}/<br/>tos-acceptance-link
    You->>Customer: Redirect to the terms page
    Customer->>Nodu: Accept the terms
    Nodu-->>Customer: Redirect back to redirectUrl
    You->>Nodu: 3. Get the verification page with redirectUrl<br/>GET /v1/customers/{customerId}/<br/>verification-link
    You->>Customer: Redirect to the verification page
    Customer->>Nodu: Provide information and documents
    Nodu-->>You: 4. Webhook events for the customer
    You->>Nodu: Read the current status<br/>GET /v1/customers/{customerId}
    Note over Customer,Nodu: 5. If Nodu needs more information, repeat step 3<br/>for the same customer and follow the new outcome.
    Nodu-->>You: 6. v1.customer.activated
    Note over Customer,Nodu: Successful journey only.
```

## 1. Create the customer

Call [Create a customer](/api/tag/customers/post-v1-customers.md) with the basic details only. In `clientReferenceId`, send your own identifier for the customer, such as the id of the customer's record in your system.

A suggestion for your interface: explain the service and the verification to the customer before you create the customer.

### An individual

Set `type=individual`. Also send the customer's `firstName`, `lastName` and `email`.

### A business

Set `type=business`, and send the company's name in `companyName`. Also send `firstName`, `lastName` and `email`: here they identify the person who represents the company.

### The response

Store the returned `id` with your own record of the customer. The customer starts with `status=pending`. A customer who returns later continues with the same `id`: do not create a second customer for the same person or company.

## 2. Obtain acceptance of the terms

Call [Retrieve a link to ToS acceptance page for a customer](/api/tag/customers/get-v1-customers-customerid-tos-acceptance-link.md) with a `redirectUrl` that points back to your platform. Send the customer to the returned `link` with a full-page redirect. Use the `link` unchanged. The customer accepts the terms. Nodu then redirects the customer to your `redirectUrl`.

Confirm the acceptance from the `v1.customer.tos_accepted` event or from the customer's `tosAcceptanceStatus`.

## 3. Redirect to Nodu's verification page

Call [Retrieve a link to verification page for a customer](/api/tag/customers/get-v1-customers-customerid-verification-link.md) with your `redirectUrl`. Redirect the customer to the returned `link`. Before the terms are accepted, Nodu refuses this request with `rule=customer_not_accepted_tos`.

On the page, the customer provides the information and the documents that Nodu asks for. The page guides the customer through every requirement. For a business, the page also collects information about the company's beneficial owners.

Request a new link each time you send the customer to verification.

## 4. Show progress while the review is pending

If Nodu approves verification or issues a final rejection while the customer is still on the page, the page redirects the customer to your `redirectUrl`. Customers often leave earlier, for example while the review is pending. So treat a return to your platform as navigation only: it does not tell you the outcome. While Nodu reviews the customer's information, you can show that the review is pending. Let the customer return later.

Follow the review with the customer events and [Retrieve a customer](/api/tag/customers/get-v1-customers-customerid.md). When the customer has submitted everything, Nodu sends `v1.customer.verification_under_review`.

For a business whose associates still have to verify, Nodu then sends `v1.customer.verification_awaiting_associates`. Send the customer to the verification page again: it lists the associates who still have to verify and lets the customer send them their links. Nodu reviews the business once its associates have completed their verification, and sends `v1.customer.verification_under_review` again.

Follow the [webhook handling guidance](/guides/api-basics/webhooks/index.md#handle-duplicates-and-order). Call [Retrieve a customer](/api/tag/customers/get-v1-customers-customerid.md) whenever an event conflicts with your stored information or the customer returns to your platform.

## 5. Handle a request for more information

When Nodu sends `v1.customer.verification_resubmission_required`, send the customer to the verification page again: see [Resubmission and rejection](/guides/customers/resubmission-and-rejection/index.md#hosted-onboarding). The same page says what you do after a final rejection.

## 6. Confirm readiness

Nodu sends `v1.customer.activated` when the customer's `status` becomes `active`. Check the customer's current `status` with [Retrieve a customer](/api/tag/customers/get-v1-customers-customerid.md). Offer transfers only to customers with `status=active`.

Then check the customer's payment channels. A payment channel is a currency and rail on which a customer can pay in or be paid out. Whether some payment channels activate after approval depends on your integration agreement with Nodu. See [Payment channels](/guides/transfers/payment-channels/index.md).

## Next steps

- [Resubmission and rejection](/guides/customers/resubmission-and-rejection/index.md): what you do when Nodu requests more information, issues a final rejection, or suspends or blocks a customer.
- [How onboarding works, and customer statuses](/guides/customers/how-onboarding-works/index.md): the meaning of every status and what you do.
- [Payment channels](/guides/transfers/payment-channels/index.md): prepare an `active` customer for transfers.
- [Test onboarding in the sandbox](/guides/sandbox/test-onboarding/index.md): produce approval, a request for more information and a final rejection in the test environment.
