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:
  1. PREFILL
  2. 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"
}

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 stored in Azure Blob Storage 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

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 Azure Blob 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
↑ ↓ to navigate • Enter to select • Esc to close