Skip to main content

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.

FieldRequiredMeaning
kindYesThe kind of document: see Document kinds.
subTypeFor identity onlyThe type of identity document: see Identity documents.
sideFor a two-sided identity document onlyfront or back: see Identity documents.
countryYesThe country that issued the document, as an ISO 3166-1 alpha-2 code.
fileYesThe 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=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 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.
  • 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 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​

kindDocument
identityIdentity document
proof_of_residenceProof of residence
selfieSelfie

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.

subTypeDocumentFilesside
passportPassportOne fileDo not send
id_cardIdentity cardTwo files: the front and the backfront and back
driversDriver's licenseTwo files: the front and the backfront and back
residence_permitResidence permitTwo files: the front and the backfront 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, 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​

kindDocumentVerification purposes
incorporation_articlesArticles of incorporationcompany_details
incorporation_certCertificate of incorporationlegal_presence
state_registryState registry extractlegal_presence, ownership_structure
shareholder_registryShareholder registryownership_structure
directors_registryDirectors registrycontrol_structure
power_of_attorneyPower of attorneyrepresentatives_authorization
proof_of_addressProof of addresscompany_proof_of_address
ubo_declarationSigned UBO declarationubo_declaration
aml_policyAML policyaml_policy
ownership_chartOwnership structure chartownership_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 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.

PurposeSet 1: four documentsSet 2: five documents
company_detailsincorporation_articlesincorporation_articles
legal_presencestate_registryincorporation_cert
ownership_structureThe same state_registry fileshareholder_registry
control_structuredirectors_registrydirectors_registry
company_proof_of_addressproof_of_addressproof_of_address

Both sets meet all five purposes. Include additional relevant evidence when your agreed requirements call for it.

Document statuses​

statusMeaning
uploadedThe document is on the application. Nodu has not reviewed it.
processingNodu is reviewing the document.
approvedNodu accepted the document.
rejectedNodu 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.

Next steps​