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.
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.
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.
2. Create the customer with an application
Call Create a customer 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.
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.
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. 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: see Upload and replace documents. 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. 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.errorsnames each field, and each missing document asdocuments.<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. Check status before submitting again.
5. Track the outcome
Follow the review with the customer events and Retrieve a customer. Receive and verify webhooks 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.
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. The approval of the application does not replace this check. Then check the customer's payment channels.
Next steps
- Upload and replace documents: upload the documents of an application.
- Associates of a business: how Nodu receives information about the people and companies connected to a business.
- Resubmission and rejection: correct an application.
- Test onboarding in the sandbox: produce each review outcome in the test environment.