---
title: "Onboard a customer through the API"
description: "Onboard a customer through the API: create the customer with an application, upload documents, submit it for review, and follow the outcome."
url: "/guides/customers/api-onboarding/create-a-customer-with-a-full-application/"
index: "/llms.txt"
---

# Onboard a customer through the API

With API onboarding, you collect the customer's information, questionnaire answers and documents in your own interface, and send them to Nodu as an application. An application is the set of information and documents that Nodu reviews for one customer. Whether you can use API onboarding depends on your integration agreement with Nodu.

> **Respondent onboarding**
>
> Under a respondent agreement with Nodu, you also send your customers' data through this API, with the same steps. Nodu does no onboarding or check of its own: you onboard and check your customers under your own compliance procedures. After you submit the application, Nodu activates the customer. This is not immediate: wait for the `v1.customer.activated` event before you offer transfers. Your requirements document lists the data, and your agreement sets out the details.

```mermaid
sequenceDiagram
    participant You as Your system
    participant Nodu
    Note over You: 1. Collect the customer's information<br/>and acceptance of the terms
    You->>Nodu: 2. Create the customer with an application<br/>POST /v1/customers
    Nodu-->>You: Customer id and application id
    opt Documents required
        You->>Nodu: 3. Upload the required documents<br/>POST /v1/customers/{customerId}/<br/>applications/{applicationId}/documents
    end
    You->>Nodu: 4. Submit for review<br/>POST /v1/customers/{customerId}/<br/>applications/{applicationId}/submit
    Nodu-->>You: Current application status
    Nodu-->>You: 5. Webhook events for the customer
    You->>Nodu: Read the decision and correction details<br/>GET /v1/customers/{customerId}/<br/>applications/{applicationId}
    Note over You,Nodu: If Nodu asks for corrections, follow the resubmission steps.<br/>A final rejection ends this application.
    Nodu-->>You: 6. v1.customer.activated
    You->>Nodu: Confirm readiness<br/>GET /v1/customers/{customerId}
    Note over You,Nodu: Successful journey, with the terms<br/>accepted in your interface.
```

## Before you start

The fields, questionnaire answers and documents that an application needs depend on the Nodu entity you integrate with and on your integration agreement with Nodu. Nodu supplies the exact fields, conditions and document requirements separately. The steps below show what the requests can carry, not what your application needs. The responses of the create and submit requests name what is missing.

## 1. Obtain acceptance of the terms

Present Nodu's Terms of Service in your own interface, through the process agreed with Nodu. Record the time at which the customer accepts them. In step 2, you send this time as `tosAcceptance.acceptedAt`: an RFC 3339 timestamp with a time zone offset, not in the future. Nodu then creates the customer with `tosAcceptanceStatus=accepted`.

Nodu uses `tosAcceptance` only when the request also contains `application`. Whether you can record the customer's acceptance yourself depends on your integration agreement with Nodu. If the agreement does not permit this, Nodu refuses the request with `rule=tos_pre_acceptance_not_permitted`.

Alternatively, create the customer first. Then redirect the customer to Nodu's terms page: see [Hosted onboarding](/guides/customers/hosted-onboarding/index.md#2-obtain-acceptance-of-the-terms).

## 2. Create the customer with an application

Call [Create a customer](/api/tag/customers/post-v1-customers.md) with the customer's details and an `application` object containing the required applicant data and questionnaire answers. In `clientReferenceId`, send your own identifier for the customer, such as the id of the customer's record in your system.

The requests below are examples. They also record the customer's acceptance of the terms from step 1 in `tosAcceptance`. The fields and answers that your application needs depend on your integration agreement with Nodu and on the Nodu entity you integrate with.

### An individual

Send `type=individual`, `firstName`, `lastName` and `email`. Put the applicant data in `application.individual`: personal details such as `dateOfBirth` and `nationality`, contact details, the postal `address`, and a `questionnaire` about the customer's income, occupation and intended use of Nodu.

```bash
curl https://api.sandbox.nodu.fi/v1/customers \
  --header 'Authorization: Bearer <your-api-key>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <new-uuid>' \
  --data '{
    "type": "individual",
    "firstName": "John",
    "lastName": "Smith",
    "email": "john.smith@example.com",
    "clientReferenceId": "client_reference_id_123",
    "application": {
      "individual": {
        "middleName": "Adam",
        "dateOfBirth": "1990-05-15",
        "countryOfBirth": "PL",
        "nationality": "PL",
        "taxResidenceCountry": "PL",
        "contactEmail": "john.personal@example.com",
        "phone": "+48123456789",
        "address": {
          "country": "PL",
          "city": "Warszawa",
          "state": "mazowieckie",
          "addressLine1": "ul. Marszalkowska 1",
          "addressLine2": "apt. 5",
          "postalCode": "00-001"
        },
        "questionnaire": {
          "services": "both",
          "cryptoPurpose": "Personal investment and remittances to family abroad.",
          "thirdPartyDeclaration": "Acting solely on own behalf.",
          "incomeCountry": "PL",
          "incomeType": "salary",
          "monthlySalary": "1000-5000",
          "plannedMonthlyTurnover": "500-1000",
          "plannedMonthlyTxCount": "10-25",
          "txValueRange": "50-2000",
          "largestTxValue": "5000",
          "sourceOfIncome": "salary",
          "jobTitle": "Software Engineer",
          "industry": "13.1",
          "isPep": false,
          "isSanctioned": false,
          "financialCrime": false
        }
      }
    },
    "tosAcceptance": {
      "acceptedAt": "2026-04-14T12:34:56+00:00"
    }
  }'
```

### A business

Send `type=business` and `companyName`. Here `firstName`, `lastName` and `email` identify the person who represents the company. Put the applicant data in `application.business`: company details such as `registrationNumber` and `incorporatedOn`, contact details, the registered `address`, and a `questionnaire` about the company's activity, ownership and intended use of Nodu.

```bash
curl https://api.sandbox.nodu.fi/v1/customers \
  --header 'Authorization: Bearer <your-api-key>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <new-uuid>' \
  --data '{
    "type": "business",
    "companyName": "ACME Corporation",
    "firstName": "Jane",
    "lastName": "Doe",
    "email": "jane.doe@example.com",
    "clientReferenceId": "client_reference_id_456",
    "application": {
      "business": {
        "registrationNumber": "KRS0000123456",
        "alternativeNames": "ACME",
        "incorporatedOn": "2020-01-15",
        "taxId": "PL1234567890",
        "website": "https://acme.example.com",
        "companyEmail": "compliance@acme.com",
        "phone": "+48111222333",
        "address": {
          "country": "PL",
          "city": "Warszawa",
          "state": "mazowieckie",
          "addressLine1": "ul. Marszalkowska 1",
          "addressLine2": "apt. 5",
          "postalCode": "00-001"
        },
        "questionnaire": {
          "industry": "17.1",
          "businessActivity": "Buying and selling stablecoins against fiat for corporate clients.",
          "businessModel": "Revenue from spread on exchange transactions and a monthly platform fee.",
          "actualAddress": "10 King Street, London, EC2V 8EA, United Kingdom",
          "operationDuration": "3 years",
          "employeeCount": "11-50",
          "countriesOfOperation": "United Kingdom, Germany, Poland",
          "noduServices": "both",
          "noduServicesPurpose": "Settling cross-border supplier invoices in stablecoin.",
          "thirdPartyDeclaration": "The company acts on its own behalf only.",
          "totalTurnover12m": "500K-1M",
          "plannedTurnover12m": "500K-1M",
          "plannedMonthlyTxValue": "50K-100K",
          "plannedMonthlyTxCount": "50-150",
          "txValueRange": "1000-50000",
          "largestTxValue": "250000",
          "bothFundsSource": "Trading revenue held partly in fiat and partly in stablecoin.",
          "ubosDirectOwnership": true,
          "isRegulated": true,
          "licenseType": "EMI license (FCA)",
          "regulatedCountry": [
            "GB",
            "DE"
          ],
          "pepStatus": false
        }
      }
    },
    "tosAcceptance": {
      "acceptedAt": "2026-04-14T12:34:56+00:00"
    }
  }'
```

Both questionnaires have an `industry` field: see [Industry codes](/guides/customers/reference/industry-codes/index.md). Some answers make other answers necessary. Follow the exact fields and conditions supplied for your integration.

### The response

Nodu creates the customer and a draft application. The application stays a draft until you submit it in step 4. Store the customer `id`, and the application `id` from `activeApplication.id`. `activeApplication` becomes `null` when the application is `approved` or `rejected`.

Nodu checks the applicant data in this request. If a field is missing or a value is not valid, Nodu refuses the request with `validation_failed` and creates no customer. Each entry in `errors` names a field, for example `application.individual.nationality`. Correct the fields. Then send the request again.

## 3. Upload the required documents

Upload each required document with [Upload an application document](/api/tag/customers/post-v1-customers-customerid-applications-applicationid-documents.md): see [Upload and replace documents](/guides/customers/api-onboarding/adding-documents/index.md). An upload does not submit the application. If your application needs no documents, continue to step 4.

## 4. Submit for review

When the application is complete, call [Submit an application for evaluation](/api/tag/customers/post-v1-customers-customerid-applications-applicationid-submit.md). Read the `status` in the response. A successful submission means that Nodu accepted the application for review, not that Nodu approved the customer.

- `validation_failed`: information or a document is missing or not valid. `errors` names each field, and each missing document as `documents.<kind>`. Correct them. Then submit again.
- `business_rule_violation`: the operation is not allowed for this application or for your integration. The same request will fail again.

If a submit request times out, call [Retrieve an application](/api/tag/customers/get-v1-customers-customerid-applications-applicationid.md). Check `status` before submitting again.

## 5. Track the outcome

Follow the review with the customer events and [Retrieve a customer](/api/tag/customers/get-v1-customers-customerid.md). [Receive and verify webhooks](/guides/api-basics/webhooks/index.md) explains how you receive the events.

You can show a pending message while the application is under review. When Nodu asks for corrections (`v1.customer.verification_resubmission_required`) or issues a final rejection (`v1.customer.verification_permanently_rejected`), follow [Resubmission and rejection](/guides/customers/resubmission-and-rejection/index.md#api-onboarding).

## 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). The approval of the application does not replace this check. Then check the customer's [payment channels](/guides/transfers/payment-channels/index.md).

## Next steps

- [Upload and replace documents](/guides/customers/api-onboarding/adding-documents/index.md): upload the documents of an application.
- [Associates of a business](/guides/customers/api-onboarding/associates-of-a-business/index.md): how Nodu receives information about the people and companies connected to a business.
- [Resubmission and rejection](/guides/customers/resubmission-and-rejection/index.md): correct an application.
- [Test onboarding in the sandbox](/guides/sandbox/test-onboarding/index.md): produce each review outcome in the test environment.
