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

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

---

Getting a Document

Retrieves metadata for a specific document.

Endpoints:

• GET /persons/{person_id}/documents/{document_id}
• GET /corporates/{corporate_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

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

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_statemnet	Bank statement (note: contains a typo in the API).
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.
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.