Document

A Document represents a file uploaded by a user, such as an identification photo, proof of address, or tax record.
Documents are often required as part of the Questionnaire Mechanism, where a question of type document expects a reference (document_id) to a previously uploaded file.

---

Uploading Documents

To upload a document, use one of the following endpoints depending on the entity type:

• POST /persons/{person_id}/documents
• POST /corporates/{corporate_id}/documents

The document must be uploaded as multipart/form-data with the following fields:

Field	Type	Description
category	String	Category of the document (see Document Categories).
orientation	String (optional)	Physical orientation of the document: front, back, or undetermined.
file	Binary	The file itself.

View Example Request

curl -X POST "https://<kyc_domain>/api/v1/persons/8e9b9a45-6212-4a77-bb43-4b8d123a5e42/documents" \
  -H "Authorization: Bearer <token>" \
  -F "category=proofOfAddress" \
  -F "orientation=front" \
  -F "file=@ElectricityBill.pdf"

View Example Response

{
  "id": "c3f67a14-0a4a-4c52-bc69-2905f79dc41f",
  "category": "proofOfAddress",
  "orientation": "front",
  "name": "ElectricityBill.pdf",
  "source": "project/person/8e9b9a45-6212-4a77-bb43-4b8d123a5e42/documentation/c3f67a14-0a4a-4c52-bc69-2905f79dc41f",
  "owner_type": "person",
  "owner_type_id": "8e9b9a45-6212-4a77-bb43-4b8d123a5e42",
  "created_at": "2024-09-03T14:55:26.346500Z"
}

Linking Documents to Questionnaire Response

When a questionnaire contains a question of type document or multiple_documents, the application should:

1. Prompt the user to upload the file using the /documents endpoint.
2. Retrieve the returned document.id from the upload response.
3. Submit that document.id as part of the questionnaire Response

Example document question in a questionnaire:

{
  "label": "Please upload your Proof of Address document.",
  "value": "poaDocument",
  "question_type": "document",
  "position": 3,
  "is_optional": false,
  "id": "0b4e7db0-4ee2-4d74-b7c3-d0500497628c",
  "options": []
}

Example answer for this question in a response:

{
  "question_id": "0b4e7db0-4ee2-4d74-b7c3-d0500497628c",
  "answer_document_id": "c3f67a14-0a4a-4c52-bc69-2905f79dc41f"
}

Document Categories

Valid values for the category field are:

Category	Description
vid	Video identification (if applicable).
selfie	User selfie photo.
identification	General ID document.
residencePermit	Residence permit or visa.
averment	Declaration or attestation.
extract	Official company extract.
report	Compliance or verification report.
proofOfFunds	Document providing the source of funds.
proofOfAddress	Proof of address (e.g., utility bill, bank statement).
proofOfIdentity	Proof of identity (e.g., passport, ID card).
results	Analytical or verification results.
undetermined	Used if no clear category applies.