Questionnaire Filling

Overview

The Questionnaire Filling endpoint intelligently fills questionnaire questions using data from source documents. It takes the questionnaire structure extracted via the Questionnaire Generation API and automatically finds relevant answers from your documents, mapping them to the appropriate questions and returning filled data with source citations and page numbers.

Use this endpoint to:

Automatically fill questionnaires using data from source documents
Extract and map answers intelligently to questions
Get multiple possible answers for each question with source citations
Automate questionnaire completion workflows
Build intelligent document processing pipelines

Endpoint Details

Method: POST
Endpoint: /api/agent/questionnaire/fill
Base URL: https://api.k-v.ai
Authentication: Access Key (Required)

Request Specification

Headers

Header	Type	Required	Description
access-key	string	Yes	Your unique access-key generated from the platform UI
Content-Type	string	Yes	Must be application/json

Request Body

{
    "source_doc_process_ids": [
        "3b5337f9edb4a828ed580b75f9cc1952"
    ],
    "model_data": {
        "model_name": "gpt-5.1",
        "api_key": ""
    },
    "unfilled_questionnaire_data": [
        {
            "question": "What is the name of the agreement entered into between ABC Software Corporation and Widget Corporation?",
            "type": "factual",
            "options": null,
            "example": "Settlement Agreement and Release",
            "user_value": {
                "source": null,
                "possible_value": null
            }
        },
        {
            "question": "Does the Plaintiff's release in this Agreement cover past, present, or future claims related to the faxed advertisement?",
            "type": "mcq",
            "options": [
                "Only past claims",
                "Only present claims",
                "Only future claims",
                "Past, present, and future claims"
            ],
            "example": "Past, present, and future claims",
            "user_value": {
                "source": null,
                "possible_value": null
            }
        }
    ]
}

Body Fields

Field	Type	Required	Description
source_doc_process_ids	array	Yes	Array of source document IDs containing answers to fill the questionnaire (obtained from Upload or List Documents APIs)
model_data	object	Yes	AI model configuration
model_data.model_name	string	Yes	AI model to use for questionnaire filling (see supported models below)
model_data.api_key	string	No	Your own LLM API key (leave empty to use platform's default keys)
unfilled_questionnaire_data	array	Yes	Questionnaire structure from Questionnaire Generation API response

Supported AI Models

Model Name	Provider
gpt-5.1	OpenAI
gpt-5-mini	OpenAI
claude-sonnet-4-5-20250929	Anthropic
gemini/gemini-2.5-flash-lite	Google
gemini/gemini-2.5-pro	Google
gemini/gemini-3-pro-preview	Google
mistral/mistral-small-latest	Mistral AI
mistral/mistral-medium-latest	Mistral AI
llama3.1-70b	Meta

Using Your Own LLM API Keys

Platform Keys (Default)

{
    "model_data": {
        "model_name": "gpt-5.1",
        "api_key": ""
    }
}

Your Own Keys

{
    "model_data": {
        "model_name": "gpt-5.1",
        "api_key": "sk-your-openai-api-key-here"
    }
}

Response Specification

Success Response (200 OK)

{
    "data": [
        {
            "question": "What is the name of the agreement entered into between ABC Software Corporation and Widget Corporation?",
            "type": "factual",
            "options": null,
            "example": "Settlement Agreement and Release",
            "user_value": {
                "source": "Settlement Agreement Tweaked.pdf",
                "possible_value": "SETTLEMENT AGREEMENT AND RELEASE",
                "page_numbers": ["1-3"],
                "doc_hash": ["3b5337f9edb4a828ed580b75f9cc1952"]
            },
            "possible_answers": [
                {
                    "source": "Settlement Agreement Tweaked.pdf",
                    "possible_value": "SETTLEMENT AGREEMENT AND RELEASE",
                    "page_numbers": ["1-3"],
                    "doc_hash": ["3b5337f9edb4a828ed580b75f9cc1952"]
                }
            ]
        },
        {
            "question": "Does the Plaintiff's release in this Agreement cover past, present, or future claims related to the faxed advertisement?",
            "type": "mcq",
            "options": [
                "Only past claims",
                "Only present claims",
                "Only future claims",
                "Past, present, and future claims"
            ],
            "example": "Past, present, and future claims",
            "user_value": {
                "source": "Settlement Agreement Tweaked.pdf",
                "possible_value": "Past, present, and future claims",
                "page_numbers": ["1-3"],
                "doc_hash": ["3b5337f9edb4a828ed580b75f9cc1952"]
            },
            "possible_answers": [
                {
                    "source": "Settlement Agreement Tweaked.pdf",
                    "possible_value": "Past, present, and future claims",
                    "page_numbers": ["1-3"],
                    "doc_hash": ["3b5337f9edb4a828ed580b75f9cc1952"]
                }
            ]
        }
    ],
    "message": "Questionnaire filled successfully"
}

Response Fields

Field	Type	Description
data	array	Array of filled question objects
data[].question	string	Question text
data[].type	string	Question type
data[].options	array/null	Available options for MCQ questions
data[].example	string	Example answer from generation
data[].user_value	object	Primary selected answer for this question
data[].user_value.source	string	Source document filename where answer was found
data[].user_value.possible_value	string	Extracted answer selected as primary
data[].user_value.page_numbers	array	Page numbers where answer was found
data[].user_value.doc_hash	array	Document process IDs where answer was found
data[].possible_answers	array	All possible answers found for this question across source documents
data[].possible_answers[].source	string	Source document filename
data[].possible_answers[].possible_value	string	Alternative extracted answer
data[].possible_answers[].page_numbers	array	Page numbers for this answer
data[].possible_answers[].doc_hash	array	Document process IDs
message	string	Human-readable response message

Error Responses

401 Unauthorized

{
    "data": {},
    "message": "Invalid or missing access key"
}

Cause: Missing or invalid access-key header.

422 Unprocessable Entity - Invalid Model Name

{
    "detail": [
        {
            "type": "literal_error",
            "loc": [
                "body",
                "model_data",
                "model_name"
            ],
            "msg": "Input should be 'gpt-5-chat-latest', 'gpt-5.1', 'gpt-5-mini', 'claude-sonnet-4-5-20250929', 'gemini/gemini-2.5-flash-lite', 'mistral/mistral-small-latest', 'mistral/mistral-medium-latest', 'gemini/gemini-2.5-pro', 'gemini/gemini-3-pro-preview' or 'llama3.1-70b'",
            "input": "",
            "ctx": {
                "expected": "'gpt-5-chat-latest', 'gpt-5.1', 'gpt-5-mini', 'claude-sonnet-4-5-20250929', 'gemini/gemini-2.5-flash-lite', 'mistral/mistral-small-latest', 'mistral/mistral-medium-latest', 'gemini/gemini-2.5-pro', 'gemini/gemini-3-pro-preview' or 'llama3.1-70b'"
            }
        }
    ]
}

Cause: Invalid or unsupported model_name in model_data. See supported models list above.

400 Bad Request - Invalid Document IDs

{
    "data": {},
    "message": "Invalid docs selected"
}

Causes:

Missing or invalid doc_process_ids.

500 Internal Server Error - Invalid LLM API Key

{
    "data": {},
    "message": "litellm.AuthenticationError: AuthenticationError: OpenAIException - Incorrect API key provided: tyrdfuih**uhf7. You can find your API key at https://platform.openai.com/account/api-keys."
}

Cause: The api_key provided in model_data is invalid or expired. Verify your LLM provider API key.

500 Internal Server Error - General Error

{
    "data": {},
    "message": "Something went wrong"
}

Causes:

LLM service temporarily unavailable
Server-side processing error

Code Snippets

curl --location 'https://api.k-v.ai/api/agent/questionnaire/fill' \
--header 'access-key: YOUR_ACCESS_KEY' \
--header 'Content-Type: application/json' \
--data '{
    "source_doc_process_ids": [
        "3b5337f9edb4a828ed580b75f9cc1952"
    ],
    "model_data": {
        "model_name": "gpt-5.1",
        "api_key": ""
    },
    "unfilled_questionnaire_data": [
        {
            "question": "What is the name of the agreement?",
            "type": "factual",
            "options": null,
            "example": "Settlement Agreement",
            "user_value": {
                "source": null,
                "possible_value": null
            }
        }
    ]
}'

import requests
import json

url = "https://api.k-v.ai/api/agent/questionnaire/fill"

payload = json.dumps({
    "source_doc_process_ids": [
        "3b5337f9edb4a828ed580b75f9cc1952"
    ],
    "model_data": {
        "model_name": "gpt-5.1",
        "api_key": ""
    },
    "unfilled_questionnaire_data": [
        {
            "question": "What is the name of the agreement?",
            "type": "factual",
            "options": None,
            "example": "Settlement Agreement",
            "user_value": {
                "source": None,
                "possible_value": None
            }
        }
    ]
})

headers = {
    'access-key': 'YOUR_ACCESS_KEY',
    'Content-Type': 'application/json'
}

response = requests.post(url, headers=headers, data=payload)

print(response.text)

const axios = require('axios');

let data = JSON.stringify({
    "source_doc_process_ids": [
        "3b5337f9edb4a828ed580b75f9cc1952"
    ],
    "model_data": {
        "model_name": "gpt-5.1",
        "api_key": ""
    },
    "unfilled_questionnaire_data": [
        {
            "question": "What is the name of the agreement?",
            "type": "factual",
            "options": null,
            "example": "Settlement Agreement",
            "user_value": {
                "source": null,
                "possible_value": null
            }
        }
    ]
});

let config = {
    method: 'post',
    maxBodyLength: Infinity,
    url: 'https://api.k-v.ai/api/agent/questionnaire/fill',
    headers: { 
        'access-key': 'YOUR_ACCESS_KEY',
        'Content-Type': 'application/json'
    },
    data: data
};

axios.request(config)
.then((response) => {
    console.log(JSON.stringify(response.data, null, 2));
})
.catch((error) => {
    console.log(error);
});

Important Notes

Questionnaire Structure Required: Use the exact questionnaire structure from Questionnaire Generation API
Source Documents: All source documents must have status: "processed"
Multiple Sources: Provide multiple source document IDs for better answer coverage
Alternative Answers: Review possible_answers array for alternative options
Source Citations: Each answer includes source document, page numbers, and doc_hash for traceability
Question Matching: AI intelligently finds relevant answers for each question

Next Steps

After filling a questionnaire:

Review Answers: Check user_value for AI-selected primary answers
Consider Alternatives: Review possible_answers for other options
Verify Sources: Use source citations and page numbers to validate extracted answers
Export Data: Convert filled questionnaire to your desired format
Manual Review: Always review AI-extracted answers before final submission

Need Help? Contact support at support@k-v.ai

Questionnaire Filling

On this page