Documents API Reference

Upload, manage, and organize documents in your tenant's library or attach them to specific entities.

Document Types
  • Tenant Documents - Stored in your organization's private library, accessible for autofill operations
  • Entity Documents - Attached to specific entities (companies/individuals) for organization
  • Response Documents - Uploaded as answers to specific DDQ questions

Tenant Documents

Manage documents in your organization's private library. These can be used for autofill in questionnaires that you may need to respond to, or as reference materials.

Upload Tenant Document

Upload a document to your tenant's private library.

POST /api/v1/documents/upload/

Request Body (multipart/form-data)

Field Type Required Description
file file Yes The file to upload (max 10MB)
document_type string Yes Document type (e.g., "Financial Statement", "Policy Document")
classification string No One of: tenant_private (default), entity_private, shared, confidential
Allowed File Types

PDF, DOC, DOCX, XLS, XLSX, PPT, PPTX, TXT, CSV, JPG, JPEG, PNG

Response (201 Created)

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "financial_statement_2024.pdf",
  "size": 2457600,
  "content_type": "application/pdf",
  "document_type_name": "Financial Statement",
  "classification": "tenant_private",
  "uploaded_by_email": "api.user@example.com",
  "created_at": "2026-01-30T14:23:45Z",
  "expiry_date": null
}

List Tenant Documents

Get all documents in your tenant's library.

GET /api/v1/documents/

Query Parameters

Parameter Type Required Description
document_type string No Filter by document type
limit integer No Number of results (default: 100, max: 1000)

Response (200 OK)

{
  "count": 3,
  "documents": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "financial_statement_2024.pdf",
      "size": 2457600,
      "content_type": "application/pdf",
      "document_type_name": "Financial Statement",
      "classification": "tenant_private",
      "uploaded_by_email": "api.user@example.com",
      "created_at": "2026-01-30T14:23:45Z",
      "expiry_date": null
    },
    {
      "id": "660e9511-f39c-52e5-b827-557766551111",
      "name": "annual_report_2023.pdf",
      "size": 3145728,
      "content_type": "application/pdf",
      "document_type_name": "Financial Statement",
      "classification": "tenant_private",
      "uploaded_by_email": "john.doe@example.com",
      "created_at": "2026-01-15T09:12:33Z",
      "expiry_date": null
    }
  ]
}

Get Tenant Document Details

Retrieve details of a specific document in your library.

GET /api/v1/documents/{document_id}/

Path Parameters

Parameter Type Description
document_id UUID The document's unique identifier

Response (200 OK)

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "financial_statement_2024.pdf",
  "size": 2457600,
  "content_type": "application/pdf",
  "document_type_name": "Financial Statement",
  "classification": "tenant_private",
  "uploaded_by_email": "api.user@example.com",
  "created_at": "2026-01-30T14:23:45Z",
  "expiry_date": null
}

Download Tenant Document

Generate a short-lived pre-signed URL to download a file from your tenant library. Fetch download_url directly — no additional authentication is required.

GET /api/v1/documents/{document_id}/download/
Pre-signed URL

Returns a time-limited URL valid for 15 minutesIt grants read-only access to a single file. The URL can be passed directly to a browser, curl, or any HTTP client to retrieve the file bytes.

Path Parameters

Parameter Type Description
document_id UUID The document's unique identifier

Response (200 OK)

{
  "download_url": "https://kycgstorage.blob.core.windows.net/tenant-.../financial_statement_2024.pdf?sv=2024-11-04&se=2026-02-20T15%3A30%3A00Z&sr=b&sp=r&sig=...",
  "expires_at": "2026-02-20T15:30:00+00:00",
  "filename": "financial_statement_2024.pdf",
  "content_type": "application/pdf",
  "size": 2457600
}

Response Fields

Field Type Description
download_url string Pre-signed URL — fetch this directly to retrieve the file
expires_at datetime ISO 8601 UTC timestamp when the URL expires (15 minutes from request)
filename string Original filename
content_type string MIME type of the file
size integer File size in bytes

Delete Tenant Document

Delete a document from your tenant's library.

DELETE /api/v1/documents/{document_id}/
Important

Documents referenced in responses cannot be deleted. Remove response references first.

Response (204 No Content)

No response body. HTTP status 204 indicates successful deletion.

Error Response (400 Bad Request)

{
  "error": "Cannot delete document",
  "detail": "This document is referenced in one or more responses. Please remove those references first."
}

Entity Documents

Attach documents to specific entities (companies or individuals) for better organization. Entity documents are stored in entity-specific folders within your tenant's storage.

Upload Entity Document

Upload a document and attach it to a specific entity.

POST /api/v1/entities/{entity_id}/documents/upload/

Path Parameters

Parameter Type Description
entity_id UUID The entity's unique identifier

Request Body (multipart/form-data)

Field Type Required Description
file file Yes The file to upload (max 10MB)
document_type string Yes Document type (e.g., "Certificate of Incorporation", "Board Resolution")
classification string No Default: tenant_private

Response (201 Created)

{
  "id": "770f0622-g49d-63f6-c938-668877662222",
  "name": "certificate_of_incorporation.pdf",
  "size": 1048576,
  "content_type": "application/pdf",
  "document_type_name": "Certificate of Incorporation",
  "classification": "tenant_private",
  "uploaded_by_email": "api.user@example.com",
  "created_at": "2026-01-30T15:10:22Z",
  "expiry_date": null
}

List Entity Documents

Get all documents attached to a specific entity.

GET /api/v1/entities/{entity_id}/documents/

Query Parameters

Parameter Type Required Description
document_type string No Filter by document type
limit integer No Number of results (default: 100, max: 1000)

Response (200 OK)

{
  "count": 2,
  "entity_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "entity_name": "Acme Corporation Ltd",
  "documents": [
    {
      "id": "770f0622-g49d-63f6-c938-668877662222",
      "name": "certificate_of_incorporation.pdf",
      "size": 1048576,
      "content_type": "application/pdf",
      "document_type_name": "Certificate of Incorporation",
      "classification": "tenant_private",
      "uploaded_by_email": "api.user@example.com",
      "created_at": "2026-01-30T15:10:22Z",
      "expiry_date": null
    },
    {
      "id": "880g1733-h50e-74g7-d049-779988773333",
      "name": "board_resolution.pdf",
      "size": 524288,
      "content_type": "application/pdf",
      "document_type_name": "Board Resolution",
      "classification": "tenant_private",
      "uploaded_by_email": "jane.smith@example.com",
      "created_at": "2026-01-28T11:45:18Z",
      "expiry_date": null
    }
  ]
}

Download Entity Document

Generate a short-lived pre-signed URL to download a document attached to a specific entity.

GET /api/v1/entities/{entity_id}/documents/{document_id}/download/

Path Parameters

Parameter Type Description
entity_id UUID The entity's unique identifier
document_id UUID The document's unique identifier

Response (200 OK)

{
  "download_url": "https://kycgstorage.blob.core.windows.net/tenant-.../certificate_of_incorporation.pdf?sv=2024-11-04&se=2026-02-20T15%3A30%3A00Z&sr=b&sp=r&sig=...",
  "expires_at": "2026-02-20T15:30:00+00:00",
  "filename": "certificate_of_incorporation.pdf",
  "content_type": "application/pdf",
  "size": 1048576
}

Delete Entity Document

Delete a document from an entity's folder.

DELETE /api/v1/entities/{entity_id}/documents/{document_id}/

Path Parameters

Parameter Type Description
entity_id UUID The entity's unique identifier
document_id UUID The document's unique identifier

Response (204 No Content)

No response body. HTTP status 204 indicates successful deletion.

Response Documents

Upload, list, download, and delete documents attached to a specific response as file question answers.

Upload Response Document

Upload a file and attach it to a response, optionally linking it to a specific file question.

POST /api/v1/responses/{response_id}/documents/upload/

Request Body (multipart/form-data)

Field Type Required Description
file file Yes The file to upload (max 10 MB)
document_type string Yes Document type label (e.g., Bank Statement)
classification string No Defaults to entity_private
file_question_id integer No Links upload to a specific file question in the questionnaire

List Response Documents

Get all documents attached to a response.

GET /api/v1/responses/{response_id}/documents/

Response (200 OK)

[
  {
    "attachment_id": "abb6336c-7edc-4814-92eb-4a80dc5b17fd",
    "document": {
      "id": "880g1733-h50e-74g7-d049-779988773333",
      "name": "bank_statement_jan_2026.pdf",
      "size": 524288,
      "content_type": "application/pdf",
      "document_type_name": "Bank Statement",
      "classification": "entity_private",
      "uploaded_by_email": "api.user@example.com",
      "created_at": "2026-01-30T15:10:22Z",
      "expiry_date": null
    },
    "file_question_type": "Bank Statement",
    "is_flagged": false,
    "is_submitted": false,
    "created_at": "2026-01-30T15:10:22Z"
  }
]
Two UUIDs — here's which to use where

Each item has two identifiers. Use attachment_id directly as the {attachment_id} path parameter in download and delete URLs. The nested document.id is the underlying file object — useful for deduplication but not used in URLs.

Download Response Document

Generate a short-lived pre-signed URL to download a document attached to a response.

GET /api/v1/responses/{response_id}/documents/{attachment_id}/download/

Path Parameters

Parameter Type Description
response_id UUID The response's unique identifier
attachment_id UUID The attachment_id from the list endpoint (not document.id)

Response (200 OK)

{
  "download_url": "https://kycgstorage.blob.core.windows.net/tenant-.../bank_statement_jan_2026.pdf?sv=2024-11-04&se=2026-02-20T15%3A30%3A00Z&sr=b&sp=r&sig=...",
  "expires_at": "2026-02-20T15:30:00+00:00",
  "attachment_id": "abb6336c-7edc-4814-92eb-4a80dc5b17fd",
  "filename": "bank_statement_jan_2026.pdf",
  "content_type": "application/pdf",
  "size": 524288
}

Delete Response Document

Remove a document from a response. If no other responses reference it, the file is permanently deleted from storage.

DELETE /api/v1/responses/{response_id}/documents/{attachment_id}/

Response (204 No Content)

No response body on success.

Document Classification Guide

Choose the appropriate classification level for your documents:

Classification Use Case Access Level
tenant_private Internal company documents, policies, templates Accessible only by your tenant users
entity_private Documents specific to an entity (respondent uploads) Entity-specific, used in response workflows
shared Documents shared with counterparties Can be shared in assessment reports
confidential Highly sensitive documents requiring extra protection Restricted access, audit logged

Error Handling

Common Error Responses

400 Bad Request - Invalid File Type

{
  "file": [
    "File type not allowed. Allowed types: .pdf, .doc, .docx, .xls, .xlsx, .txt, .ppt, .pptx, .txt, .csv, .jpg, .jpeg, .png"
  ]
}

400 Bad Request - File Too Large

{
  "file": [
    "File size exceeds maximum allowed size of 10MB"
  ]
}

404 Not Found - Entity Not Found

{
  "detail": "Not found."
}

500 Internal Server Error - Upload Failed

{
  "error": "File upload failed",
  "detail": "Failed to upload file to storage. Please try again later."
}

Best Practices

Upload Strategy
  • Batch Uploads - For multiple documents, upload sequentially with proper error handling
  • Naming Convention - Use descriptive filenames that indicate document purpose and date
  • Document Types - Create consistent document types across your organization
  • File Size - Compress large PDFs before upload to stay under 10MB limit
↑ ↓ to navigate • Enter to select • Esc to close