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": "[email protected]",
  "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": "[email protected]",
      "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": "[email protected]",
      "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": "[email protected]",
  "created_at": "2026-01-30T14:23:45Z",
  "expiry_date": null
}

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": "[email protected]",
  "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": "[email protected]",
      "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": "[email protected]",
      "created_at": "2026-01-28T11:45:18Z",
      "expiry_date": null
    }
  ]
}

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.

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 to Azure Blob Storage"
}

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