Responses API

Responses represent filled-out DDQ questionnaires. They're the core workflow object in KYC Genie, linking a questionnaire template to a specific entity being assessed.

Response Object

The response object contains all metadata about a filled questionnaire.

Attributes

Field	Type	Description
`id`	uuid	Unique identifier
`response_name`	string	Display name for the response
`questionnaire`	object	Nested questionnaire template object (id, name, type)
`subject_entity`	object	Nested entity being assessed (id, name, type)
`status`	string	Current workflow status (see Status Values below)
`is_test_data`	boolean	Whether created with test API key (for data segregation)
`sent_by`	string	Identifier of the user who sent the response
`responded_by`	object	Profile object of user who submitted the response (null until submitted)
`reviewed_by`	object	Profile object of analyst who reviewed the response (null until reviewed)
`manager_reviewer`	object	Profile object of manager who performed final review (null until manager review)
`created_at`	datetime	Creation timestamp
`submitted_at`	datetime	Timestamp of submission (null if not submitted)
`reviewed_at`	datetime	Timestamp of analyst review (null if not reviewed)
`manager_reviewed_at`	datetime	Timestamp of manager review (null if not manager reviewed)
`updated_at`	datetime	Last update timestamp
`answers`	array	Array of answer objects (only in detail view)

Status Values

Responses follow a state machine with specific allowed transitions:

Status	Description
`PREFILL`	You're filling the form before sending to entity (no email sent)
`DRAFT`	Form sent to entity for completion (email sent on creation)
`SUBMITTED`	Entity has submitted the completed form for your review
`UNDER_REVIEW`	Your team is currently reviewing the submission
`CHANGES_REQUESTED`	Your team requested changes (returns to DRAFT status)
`REVIEWED`	Initial review complete, awaiting final approval
`APPROVED`	Final approval granted
`REJECTED`	Response rejected
`RESUBMITTED`	Entity resubmitted after changes were requested

Create Response

Creates a new DDQ response for an entity. The response can only be created in DRAFT or PREFILL status.

POST /api/v1/responses/

Request Body

Parameter	Type	Required	Description
`questionnaire_id`	integer	Yes	ID of the DDQ template to use
`entity`	object	Yes	Entity information (see Entity Object below)
`response_name`	string	No	Custom name for this response (auto-generated if not provided)
`status`	string	No	Initial status (default: `PREFILL`). Allowed values: `PREFILL` `DRAFT`

Note: The entity object specifies which company or individual the response is for. For complete details on entity fields and requirements, see the Entities API Reference.

Status Validation

The API enforces that new responses can only be created with status DRAFT or PREFILL. Any other status value will result in a 400 validation error. Other statuses are set through workflow transitions.

DRAFT Status Requires Email

Creating a response with status: "DRAFT" requires entity.email to be provided. The email triggers an automatic signup link for the entity to access the form. The API will return a 400 Bad Request error if DRAFT status is used without an email. Ensure that any new or existing entity has a valid email address before setting status to DRAFT.

API Response

Returns the created Response object with status 201 Created.

Response (201 Created)

{
  "id": "d67177bf-6871-45bf-85f2-95a1e52ccc64",
  "response_name": "Acme Corp - DDQ - Template",
  "questionnaire": {
    "id": 55,
    "name": "DDQ - Template",
    "questionnaire_type": "ddq"
  },
  "subject_entity": {
    "id": "1b83f447-4a1e-4589-8a12-b8767e3c5426",
    "name": "Acme Corp",
    "entity_type": "company"
  },
  "status": "PREFILL",
  "created_at": "2026-01-14T12:41:56.456529Z",
  "submitted_at": null,
  "reviewed_at": null,
  "manager_reviewed_at": null,
  "updated_at": "2026-01-14T12:41:56.456555Z"
}

List Responses

Retrieves a paginated list of all responses in your tenant. Results are ordered by creation date (newest first).

GET /api/v1/responses/

Query Parameters

Parameter	Type	Description
`status`	string	Filter by status: `DRAFT`, `PREFILL`, `SUBMITTED`, etc.
`page`	integer	Page number (default: 1)
`page_size`	integer	Results per page (default: 50, max: 100)

API Response

Returns a paginated list of Response objects.

{
  "count": 42,
  "next": "https://api.kycgenie.com/api/v1/responses/?page=2",
  "previous": null,
  "results": [
    {
      "id": "770g0611-g40d-63f6-c938-668877662222",
      "response_name": "Acme Corp - Vendor Security Assessment",
      "questionnaire_name": "Vendor Security Assessment",
      "entity_name": "Acme Corp",
      "status": "SUBMITTED",
      "created_at": "2026-01-21T10:30:00Z",
      "submitted_at": "2026-01-21T14:23:45Z"
    },
    {
      "id": "880h1722-h51e-74g7-d049-779988773333",
      "response_name": "Beta Inc - Financial Due Diligence",
      "questionnaire_name": "Financial Due Diligence",
      "entity_name": "Beta Inc",
      "status": "DRAFT",
      "created_at": "2026-01-20T09:15:00Z",
      "submitted_at": null
    }
  ]
}

Get Response

Retrieves a specific response by ID, including all answers and associated data.

GET /api/v1/responses/{id}/

Path Parameters

Parameter	Type	Description
`id`	uuid	The unique identifier of the response

API Response

Returns the full Response object.

{
  "id": "770g0611-g40d-63f6-c938-668877662222",
  "response_name": "Acme Corp - Vendor Security Assessment",
  "questionnaire": {
    "id": 17,
    "name": "Vendor Security Assessment",
    "questionnaire_type": "ddq"
  },
  "subject_entity": {
    "id": "660f9500-f39c-52e5-b827-557766551111",
    "name": "Acme Corp",
    "entity_type": "company"
  },
  "status": "SUBMITTED",
  "is_test_data": false,
  "created_at": "2026-01-21T10:30:00Z",
  "submitted_at": "2026-01-21T14:23:45Z",
  "reviewed_at": "2026-01-21T15:30:22Z",
  "manager_reviewed_at": null,
  "updated_at": "2026-01-21T15:30:22Z"
}

Get Response Answers

Retrieve all submitted answers for a response with complete question metadata, comments, and flag information. This endpoint returns text answers only - for file uploads, use the GET /documents/ endpoint.

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

Use Cases

Export submitted answers for reporting and analysis
Review completed DDQ responses in custom UI
Audit trail of submitted data
Fetch answers for comparison or validation

Path Parameters

Parameter	Type	Description
`response_id`	uuid	The unique identifier of the response

Answer Object Fields

Field	Type	Description
`id`	uuid	Unique answer identifier
`question_id`	integer	ID of the question being answered
`question_text`	string	Full text of the question
`question_number`	integer	Question number within questionnaire
`question_type`	string	Type: `text`, `text_and_date`, `structured`
`section`	string	Section name (e.g., "Company Information")
`sub_section`	string	Sub-section name (if applicable)
`required`	boolean	Whether the question is required
`answer_text`	string	The text answer provided
`date_answer`	date	Date answer (YYYY-MM-DD) if question type supports it
`is_flagged`	boolean	Whether answer has been flagged by AI or reviewer
`comments`	array	Array of comment objects on this answer
`num_of_comments`	integer	Total count of all comments
`created_at`	datetime	When answer was first created
`updated_at`	datetime	When answer was last modified

API Response

Returns an array of Answer objects ordered by question number.

[
  {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "question_id": 123,
    "question_text": "What is your company's legal name?",
    "question_number": 1,
    "question_type": "text",
    "section": "Company Information",
    "sub_section": "Basic Details",
    "required": true,
    "answer_text": "Acme Corporation Ltd",
    "date_answer": null,
    "is_flagged": false,
    "comments": [],
    "num_of_comments": 0,
    "num_of_genie_comments": 0,
    "num_of_external_comments": 0,
    "created_at": "2026-02-15T10:30:00Z",
    "updated_at": "2026-02-15T10:30:00Z"
  },
  {
    "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "question_id": 124,
    "question_text": "When was the company incorporated?",
    "question_number": 2,
    "question_type": "text_and_date",
    "section": "Company Information",
    "sub_section": "Basic Details",
    "required": true,
    "answer_text": "Incorporated in Delaware",
    "date_answer": "2010-03-15",
    "is_flagged": true,
    "comments": [
      {
        "id": "c3d4e5f6-a789-0123-cdef-123456789012",
        "text": "Please provide certificate of incorporation",
        "comment_type": "reviewer",
        "profile_name": "John Reviewer",
        "profile_email": "john@example.com",
        "created_at": "2026-02-16T14:20:00Z",
        "updated_at": "2026-02-16T14:20:00Z",
        "is_edited": false,
        "edited_at": null
      }
    ],
    "num_of_comments": 1,
    "num_of_genie_comments": 0,
    "num_of_external_comments": 1,
    "created_at": "2026-02-15T10:31:00Z",
    "updated_at": "2026-02-15T10:31:00Z"
  }
]

Save Answers

Saves answers and files to a response without submitting. This endpoint allows you to save draft progress and upload files without triggering validation or autoflag.

PUT /api/v1/responses/{id}/save/

Request Body (multipart/form-data)

Parameter	Type	Required	Description
`answers`	string (JSON)	No	JSON string of answer array: `[{"question_id": 123, "answer_text": "..."}]`
`{file_question_id}`	file	No	Files keyed by file question ID (e.g., `123: passport.pdf`)

Answer Object Format

Field	Type	Description
`question_id`	integer	ID of the question being answered
`answer_text`	string	The text answer
`date_answer`	date	Optional: Date answer (YYYY-MM-DD)

API Response

Returns success confirmation with saved answer counts and file upload details.

{
  "success": true,
  "message": "Response progress saved",
  "response_id": "770g0611-g40d-63f6-c938-668877662222",
  "status": "DRAFT",
  "answers_saved": 5,
  "files_uploaded": 2,
  "uploaded_files": [
    {
      "file_question_id": "123e4567-e89b-12d3-a456-426614174000",
      "filename": "passport.pdf",
      "document_type": "Passport"
    },
    {
      "file_question_id": "987f6543-e21b-12d3-a456-426614174111",
      "filename": "bank_statement.pdf",
      "document_type": "Bank Statement"
    }
  ]
}

Submit Response

Submits a response for review. This transitions the response from DRAFT to SUBMITTED status and triggers the autoflag function. Note: All answers and files must be saved before calling this endpoint.

POST /api/v1/responses/{id}/submit/

Validation Required

All required questions must have answers before submission. The API will return a 400 error with details about missing answers if validation fails.

API Response

Returns the updated Response with status: "SUBMITTED".

{
  "success": true,
  "message": "Response submitted successfully",
  "response_id": "770g0611-g40d-63f6-c938-668877662222",
  "status": "SUBMITTED",
  "submitted_at": "2026-01-21T14:23:45Z",
  "autoflag_task_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Save and Submit Response

Saves answers/files and submits response in one atomic operation. This is a convenience endpoint that combines the /save/ and /submit/ workflows.

PUT /api/v1/responses/{id}/save-and-submit/

Use Cases

Client has all answers and files ready to submit
Single-step submission from a form
Reducing API calls from 2 to 1

Request Body (multipart/form-data)

Parameter	Type	Required	Description
`answers`	string (JSON)	Optional	JSON array of answer objects: `[{"question_id": 123, "answer_text": "..."}]`
`{file_question_id}`	file	Optional	File upload keyed by file_question_id (e.g., `"67": file.pdf`)

API Response

{
  "success": true,
  "message": "Response saved and submitted successfully",
  "response_id": "770g0611-g40d-63f6-c938-668877662222",
  "status": "SUBMITTED",
  "answers_saved": 3,
  "files_uploaded": 2,
  "uploaded_files": [
    {
      "file_question_id": "67",
      "filename": "security_policy.pdf",
      "size": 245760
    },
    {
      "file_question_id": "68",
      "filename": "iso27001_certificate.pdf",
      "size": 189440
    }
  ],
  "submitted_at": "2026-01-21T14:23:45Z",
  "autoflag_task_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Error Responses

Status Code	Description
`400`	Validation failed - incomplete response or invalid data
`403`	Response cannot be modified (wrong status)

Delete Response

Permanently deletes a response. This action cannot be undone.

DELETE /api/v1/responses/{id}/

Permanent Action

Deleting a response removes all associated answers and file uploads. Consider archiving instead if you need to maintain records.

API Response

Returns 204 No Content on success.

Autofill Response

Trigger AI-powered autofill for an entire response using documents linked to the subject entity. This is an asynchronous operation that returns immediately with a task ID for tracking.

POST /api/v1/responses/{response_id}/autofill/

Requirements

Response status must be PREFILL or DRAFT
Subject entity must have at least one document uploaded
Consumes AI autofill credits from your plan

Behavior

Asynchronous: Returns task_id immediately, processing happens in background
Overwrites: Replaces existing answers (same as web UI behavior)
Webhook: Sends response.autofill_completed event when finished

Response (202 Accepted)

{
  "task_id": "abc123-def456-789ghi",
  "response_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "DRAFT",
  "message": "Autofill task started successfully"
}

Webhook Payload

When autofill completes, you'll receive:

{
  "event": "response.autofill_completed",
  "timestamp": "2026-01-28T13:21:55.853932+00:00",
  "data": {
    "response_id": "d67177bf-6871-45bf-85f2-95a1e52ccc64",
    "response_name": "Acme Corp - DDQ - Template",
    "questionnaire_id": "14",
    "questionnaire_name": "DDQ - Template",
    "entity_id": "1b83f447-4a1e-4589-8a12-b8767e3c5426",
    "entity_name": "Acme Corp",
    "status": "PREFILL",
    "created_at": "2026-01-28T12:41:56.456529+00:00",
    "submitted_at": null,
    "answers_saved": 83,
    "total_questions": 83
  }
}

Check/Validate Answers

Trigger AI-powered validation for all answers in a response. The AI checks for completeness, accuracy, consistency, and identifies potential issues. Results are saved and displayed in the response review interface.

POST /api/v1/responses/{response_id}/check-answers/

Requirements

Response status must be PREFILL, DRAFT, REJECTED, or CHANGES_REQUESTED
Consumes AI checking credits from your plan

Permissions

PREFILL status: Only sender tenant can check answers
Other statuses: Only subject entity can check answers

Behavior

Asynchronous: Returns task_id immediately, processing happens in background
Non-destructive: Adds validation results without modifying answers
Webhook: Sends response.check_answers_completed event when finished
AI Analysis: Checks each answer for quality, completeness, and consistency

Response (202 Accepted)

{
  "task_id": "xyz789-abc123-def456",
  "response_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "DRAFT",
  "message": "Check answers task started successfully"
}

Webhook Payload

When checking completes, you'll receive:

{
  "event": "response.check_answers_completed",
  "timestamp": "2026-01-28T13:25:44.525514+00:00",
  "data": {
    "response_id": "d67177bf-6871-45bf-85f2-95a1e52ccc64",
    "response_name": "Acme Corp - DDQ - Template",
    "questionnaire_id": "14",
    "questionnaire_name": "DDQ - Template",
    "entity_id": "1b83f447-4a1e-4589-8a12-b8767e3c5426",
    "entity_name": "Acme Corp",
    "status": "PREFILL",
    "created_at": "2026-01-28T12:41:56.456529+00:00",
    "submitted_at": null,
    "answers_checked": 85
  }
}

Generate Assessment Report

Generate a comprehensive AI-powered risk assessment report in DOCX format. The report includes entity details, screening results, answer analysis, and risk scoring based on all available data.

POST /api/v1/responses/{response_id}/assessment/generate/

Requirements

Response must be SUBMITTED, UNDER_REVIEW, REVIEWED, APPROVED, or RESUBMITTED
Subject entity must exist
Consumes AI assessment report credits from your plan

Behavior

Asynchronous: Returns task_id immediately, report generation happens in background
Storage: DOCX file linked to entity
AI Analysis: Comprehensive risk assessment using all response data
Includes: Entity details, screening results, flagged answers, risk sections, compliance summary

Response (202 Accepted)

{
  "status": "pending",
  "message": "Assessment report generation initiated",
  "task_id": "abc123-def456-789ghi",
  "response_id": "550e8400-e29b-41d4-a716-446655440000"
}

Error Responses

400: Response not submitted yet
404: Response or subject entity not found
500: Failed to queue assessment task

Response Documents

Upload, list, download, and delete documents attached to a response as file question answers. Use these endpoints to programmatically fulfil file question requirements in a DDQ.

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 the upload to a specific file question in the questionnaire

List Response Documents

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

Use attachment_id directly as the {attachment_id} path parameter in download and delete URLs. The nested document.id is the underlying file object — the same physical file could theoretically be attached to multiple responses, but attachment_id is unique per attachment.

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/

Pre-signed URL

Returns a time-limited SAS URL valid for 15 minutes. No additional auth header is needed to fetch the file — pass download_url directly to your HTTP client or browser.

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

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

Response (204 No Content)

No response body on success.

Download Assessment Report

Download the most recently generated assessment report for a response as a DOCX file.

GET /api/v1/responses/{response_id}/assessment/download/

Requirements

Assessment report must have been generated first using the generate endpoint
Report must exist in storage

Response (200 OK)

Returns DOCX file as binary download with headers:

Content-Type: application/vnd.openxmlformats-officedocument.wordprocessingml.document
Content-Disposition: attachment; filename="assessment_report_{response_id}.docx"

Error Responses

404: No assessment report found - generate one first using POST endpoint
500: Failed to download report from storage