Document

A Document represents a file uploaded by a user, such as an identity document, 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
• POST /individuals/{individual_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	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=poa" \
  -F "orientation=front" \
  -F "file=@ElectricityBill.pdf"

View Example Response

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

---

Listing Documents

Retrieves a paginated list of documents for a specific entity.

Endpoints:

• GET /persons/{person_id}/documents
• GET /corporates/{corporate_id}/documents
• GET /individuals/{individual_id}/documents

---

Getting a Document

Retrieves metadata for a specific document.

Endpoints:

• GET /persons/{person_id}/documents/{document_id}
• GET /corporates/{corporate_id}/documents/{document_id}
• GET /individuals/{individual_id}/documents/{document_id}

---

Downloading Documents

To download a document, you must first obtain a temporary signed URL.

Endpoints:

• GET /persons/{person_id}/documents/{document_id}/download_link
• GET /corporates/{corporate_id}/documents/{document_id}/download_link
• GET /individuals/{individual_id}/documents/{document_id}/download_link

Example Response

{
  "url": "https://storage.googleapis.com/kyc-bucket/project/person/.../c3f67a14?GoogleAccessId=...",
  "expires_in": 3600
}

---

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

Category must match the question

The uploaded document's category must be equal to the question's value. A response referencing a document whose category does not match is rejected with a 422 error ("Category 'X' of provided document ID ... does not match question's category 'Y'."). For example, the KYB Onboarding document questions each require a document of the matching corporate category (organizational_chart, commercial_register_extract, ...).

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
id_document	Proof of identity (e.g., passport, ID card).
residence_permit	Residence permit or visa.
poa	Proof of address (e.g., utility bill, bank statement).
selfie	User selfie photo.
source_of_funds	Document providing the source of funds.
retail_edd	Enhanced Due Diligence for retail clients.
corporate_edd	Enhanced Due Diligence for corporate clients.
article_of_association	Articles of Association of a company.
commercial_register_extract	Official company register extract.
financial_statement	Company financial statements.
transparency_register_extract	Extract from the transparency register.
organizational_chart	Chart showing the organizational structure.
proof_of_capability	Document proving professional capability or license.
rfi_document	Document provided in response to a Request for Information.
pep_questionnaire	Politically Exposed Person questionnaire.
carf_self_declaration	Crypto-Asset Reporting Framework self-declaration.
contract	Signed business contract or agreement.
power_of_attorney	Document granting power of attorney.
cv	Curriculum Vitae of key personnel.
bank_statement	Bank statement.
transaction_history	Record of financial transactions.
kyt_report	Know Your Transaction report.
tx_monitoring_report	Transaction monitoring report.
sar	Suspicious Activity Report.
onboarding_report	Compliance report from the onboarding process.
cdd_report	Customer Due Diligence report.
periodic_review	Periodic review document.
termination_notice	Notice of account or relationship termination.
aml_policy	Anti-Money Laundering policy document.
proof_of_license	Proof of regulatory or business license.
other_corporate_document	Miscellaneous corporate document.
other_retail_document	Miscellaneous retail document.
generic	General or unclassified document.
trading_history	Record of trading activities.
fourthline_cdd_report	Customer Due Diligence report from Fourthline.
undetermined	Used if no clear category applies.