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
}

Download Tenant Document

Generate a short-lived download URL for a file in your tenant library. Fetch download_url directly. The link is valid for 15 minutes and can be used multiple times within that window.

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

Download URL

Returns a time-limited URL valid for 15 minutes and can be used multiple times within that window.

Path Parameters

Parameter	Type	Description
`document_id`	UUID	The document's unique identifier

Response (200 OK)

{
  "download_url": "https://app.kycgenie.com/api/v1/files/dl_A3f8b2c1d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9/",
  "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	Download URL — fetch this directly to retrieve the file (valid 15 min)
`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": "[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
    }
  ]
}

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://app.kycgenie.com/api/v1/files/dl_B7c9d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8/",
  "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

Response (201 Created)

{
  "attachment_id": "abb6336c-7edc-4814-92eb-4a80dc5b17fd",
  "response_id": "f1a2b3c4-d5e6-7890-abcd-ef1234567890",
  "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": null,
    "created_at": "2026-01-30T15:10:22Z",
    "expiry_date": null
  },
  "file_question_id": 42,
  "file_question_type": "Bank Statement",
  "file_question_description": "Please provide your most recent bank statement",
  "file_question_required": true,
  "file_question_multiple": false,
  "is_flagged": null,
  "is_submitted": false,
  "created_at": "2026-01-30T15:10:22Z",
  "updated_at": "2026-01-30T15:10:22Z"
}

Nullable fields: uploaded_by_email is null when the file was uploaded by a respondent via the onboarding link (no authenticated profile). file_question_id and related file_question_* fields are null when the upload was not linked to a specific questionnaire file question.

List Response Documents

Get all documents attached to a response.

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

Response (200 OK)

Returns a paginated envelope with a count and data array of FileAnswer objects.

{
  "count": 1,
  "data": [
    {
      "attachment_id": "abb6336c-7edc-4814-92eb-4a80dc5b17fd",
      "response_id": "f1a2b3c4-d5e6-7890-abcd-ef1234567890",
      "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": null,
        "created_at": "2026-01-30T15:10:22Z",
        "expiry_date": null
      },
      "file_question_id": 42,
      "file_question_type": "Bank Statement",
      "file_question_description": "Please provide your most recent bank statement",
      "file_question_required": true,
      "file_question_multiple": false,
      "is_flagged": null,
      "is_submitted": false,
      "created_at": "2026-01-30T15:10:22Z",
      "updated_at": "2026-01-30T15:10:22Z"
    }
  ]
}

Two UUIDs — here's which to use where

Use attachment_id as the {attachment_id} path parameter in the detail, download, and delete endpoints. The nested document.id is the underlying blob record — useful for deduplication but not used in URLs. The file_question_* fields link the attachment back to its questionnaire question.

Get Response Document

Retrieve the metadata for a single document attachment. Useful when you already have an attachment_id and want to inspect it without fetching the full list.

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

Response (200 OK)

Same shape as a single item from the list endpoint.

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://app.kycgenie.com/api/v1/files/dl_C2e4f6a8b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4/",
  "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 the underlying file, it is permanently deleted from storage.

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

Response (204 No Content)

No response body on success. Returns 404 if the attachment does not exist or has already been deleted.

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