Upload and replace documents
With API onboarding, you upload the customer's documents to the application before you submit it. You upload each file in its own request, and you replace a document by uploading a new file of the same kind.
Upload a document
Call Upload an application document once for each file. The request body is multipart/form-data, not JSON.
| Field | Required | Meaning |
|---|---|---|
kind | Yes | The kind of document: see Document kinds. |
subType | For identity only | The type of identity document: see Identity documents. |
side | For a two-sided identity document only | front or back: see Identity documents. |
country | Yes | The country that issued the document, as an ISO 3166-1 alpha-2 code. |
file | Yes | The file: JPEG, PNG or PDF, up to 4 MiB. A selfie must be JPEG or PNG. |
For example, the front of an identity card issued in Poland. curl --form sends the body as multipart/form-data; do not set the Content-Type header yourself:
curl 'https://api.sandbox.nodu.fi/v1/customers/<customer-id>/applications/<application-id>/documents' \
--header 'Authorization: Bearer <your-api-key>' \
--form kind=identity \
--form subType=id_card \
--form side=front \
--form country=PL \
--form file=@id-card-front.jpg
Upload the back of the card with a second request, with side=back.
- You can upload while the application has
status=draftorstatus=resubmission_required. - An upload adds the document to the application. It does not submit the application.
- Nodu returns the document with its
idandstatus. Retrieve an application lists every document of the application indocuments.
Whether you can use API onboarding depends on your integration agreement with Nodu. If the agreement does not include API onboarding, Nodu refuses the upload with rule=reliance_application_not_permitted.
Which documents an application needs
The documents that an application needs depend on the Nodu entity you integrate with and on your integration agreement with Nodu. Nodu supplies the list to you as a separate requirements document. The tables below show what the API accepts, not what your application needs.
- Upload at least the documents that your requirements document lists. You can add other kinds that meet a purpose of the application, as in the examples.
- If your requirements document lists no documents, upload none.
Two API responses give the exact answer:
- When you upload. Nodu can refuse a kind that the application does not accept, with
validation_failed. The entry inerrorsforkindthen lists, in itsmessage, the kinds that the application accepts. - When you submit. If a document is missing, Submit an application for evaluation returns
validation_failed. Each entry inerrorsnames a kind asdocuments.<kind>. For a business, themessagealso names the purpose that the document would serve. Entries that name the same purpose are alternatives: upload one of these kinds, not all of them.
Document kinds
The API accepts one set of kinds for an individual and another set for a business. Nodu refuses a kind that does not match the customer's type.
Documents for an individual
kind | Document |
|---|---|
identity | Identity document |
proof_of_residence | Proof of residence |
selfie | Selfie |
proof_of_residence and selfie are one file each. Do not send subType or side with them.
Identity documents
An identity document needs a subType. Some types have two sides: upload each side in its own request, with side=front or side=back.
subType | Document | Files | side |
|---|---|---|---|
passport | Passport | One file | Do not send |
id_card | Identity card | Two files: the front and the back | front and back |
drivers | Driver's license | Two files: the front and the back | front and back |
residence_permit | Residence permit | Two files: the front and the back | front and back |
- Upload both sides of a two-sided document before you submit. With one side only, Submit an application for evaluation returns
validation_failed. - Nodu refuses an upload that has no
subType, apassportwith aside, and a two-sided document without aside. The status is422and the codevalidation_failed.
Documents for a business
kind | Document | Verification purposes |
|---|---|---|
incorporation_articles | Articles of incorporation | company_details |
incorporation_cert | Certificate of incorporation | legal_presence |
state_registry | State registry extract | legal_presence, ownership_structure |
shareholder_registry | Shareholder registry | ownership_structure |
directors_registry | Directors registry | control_structure |
power_of_attorney | Power of attorney | representatives_authorization |
proof_of_address | Proof of address | company_proof_of_address |
ubo_declaration | Signed UBO declaration | ubo_declaration |
aml_policy | AML policy | aml_policy |
ownership_chart | Ownership structure chart | ownership_chart |
A UBO is an ultimate beneficial owner of the company.
- Upload the company's documents only. Nodu receives the documents of the company's directors, owners and other associates separately: see Associates of a business.
- Each company document is one file. Do not send
subTypeorside. - A company document can serve more than one verification purpose. For example, a
state_registryextract can show both the company's legal presence and its ownership structure. - In the response,
satisfieslists the purposes that the document serves for this application. It does not mean that Nodu approved the document. - Nodu uses an
aml_policyonly when the questionnaire hasisRegulated=true. Nodu uses anownership_chartonly whenubosDirectOwnership=false.
Two example document sets for a business
Different sets of documents can meet the same requirements. In these examples, the requirements ask for five purposes: company_details, legal_presence, ownership_structure, control_structure and company_proof_of_address. The requirements of your customers come from Nodu: see Which documents an application needs.
| Purpose | Set 1: four documents | Set 2: five documents |
|---|---|---|
company_details | incorporation_articles | incorporation_articles |
legal_presence | state_registry | incorporation_cert |
ownership_structure | The same state_registry file | shareholder_registry |
control_structure | directors_registry | directors_registry |
company_proof_of_address | proof_of_address | proof_of_address |
Both sets meet all five purposes. Include additional relevant evidence when your agreed requirements call for it.
Document statuses
status | Meaning |
|---|---|
uploaded | The document is on the application. Nodu has not reviewed it. |
processing | Nodu is reviewing the document. |
approved | Nodu accepted the document. |
rejected | Nodu rejected the document. rejection.message on the document says what to correct. Replace the document. |
Replace a document
To replace a document, upload a new file of the same kind:
- For a two-sided identity document, the new file replaces the side that you name in
side. - An application holds one identity document. An upload with another
subTypereplaces the identity document that you uploaded before. - For every other kind, the new file replaces the earlier document of that kind.
After Nodu rejects a document, upload its replacement. Then submit the application again: see Resubmission and rejection.
Next steps
- Onboard a customer through the API: where the documents fit in API onboarding.
- Associates of a business: how Nodu receives information about the people and companies connected to a business.
- Resubmission and rejection: replace the documents that Nodu rejected.
- Errors and rule codes: how to read a
validation_failedresponse. - Test onboarding in the sandbox: produce each review outcome in the test environment.