---
title: "Upload and replace documents"
description: "How to upload, check and replace the documents of an application, and which document kinds the API accepts for individuals and for businesses."
url: "/guides/customers/api-onboarding/adding-documents/"
index: "/llms.txt"
---

# Upload and replace documents

With [API onboarding](/guides/customers/api-onboarding/create-a-customer-with-a-full-application/index.md), 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](/api/tag/customers/post-v1-customers-customerid-applications-applicationid-documents.md) 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](#document-kinds). |
| `subType` | For `identity` only | The type of identity document: see [Identity documents](#identity-documents). |
| `side` | For a two-sided identity document only | `front` or `back`: see [Identity documents](#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:

```bash
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=draft` or `status=resubmission_required`.
- An upload adds the document to the application. It does not submit the application.
- Nodu returns the document with its `id` and `status`. [Retrieve an application](/api/tag/customers/get-v1-customers-customerid-applications-applicationid.md) lists every document of the application in `documents`.

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](#two-example-document-sets-for-a-business).
- 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 in `errors` for `kind` then lists, in its `message`, the kinds that the application accepts.
- **When you submit.** If a document is missing, [Submit an application for evaluation](/api/tag/customers/post-v1-customers-customerid-applications-applicationid-submit.md) returns `validation_failed`. Each entry in `errors` names a kind as `documents.<kind>`. For a business, the `message` also 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](/api/tag/customers/post-v1-customers-customerid-applications-applicationid-submit.md) returns `validation_failed`.
- Nodu refuses an upload that has no `subType`, a `passport` with a `side`, and a two-sided document without a `side`. The status is `422` and the code `validation_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](/guides/customers/api-onboarding/associates-of-a-business/index.md).
- Each company document is one file. Do not send `subType` or `side`.
- A company document can serve more than one verification purpose. For example, a `state_registry` extract can show both the company's legal presence and its ownership structure.
- In the response, `satisfies` lists the purposes that the document serves for this application. It does not mean that Nodu approved the document.
- Nodu uses an `aml_policy` only when the questionnaire has `isRegulated=true`. Nodu uses an `ownership_chart` only when `ubosDirectOwnership=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](#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 `subType` replaces 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](/guides/customers/resubmission-and-rejection/index.md#api-onboarding).

## Next steps

- [Onboard a customer through the API](/guides/customers/api-onboarding/create-a-customer-with-a-full-application/index.md): where the documents fit in API onboarding.
- [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): replace the documents that Nodu rejected.
- [Errors and rule codes](/guides/api-basics/errors-and-rule-codes/index.md): how to read a `validation_failed` response.
- [Test onboarding in the sandbox](/guides/sandbox/test-onboarding/index.md): produce each review outcome in the test environment.
