Form Filling

Overview

The Form Filling endpoint intelligently fills form fields using data from uploaded documents. It takes the form structure extracted via the Form Generation API and automatically maps relevant information from your documents to the appropriate form fields, returning filled data with source citations.

Use this endpoint to:

Automatically fill forms using data from documents
Extract and map information intelligently to form fields
Get multiple possible values for each field with source citations
Automate form completion workflows
Build intelligent document processing pipelines

Endpoint Details

Method: POST
Endpoint: /api/agent/form/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": [
        "bca03f7db29b5f22c293f6cff2bf378a"
    ],
    "model_data": {
        "model_name": "gpt-5.1",
        "api_key": ""
    },
    "unfilled_form_data": [
        {
            "label": "Given Name",
            "type": "text",
            "example": null,
            "options": null,
            "user_value": {
                "source": null,
                "possible_value": null
            }
        },
        {
            "label": "Driving License",
            "type": "select",
            "example": null,
            "options": ["Yes", "No"],
            "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 data to fill the form (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 form 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_form_data	array	Yes	Form structure from Form 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": [
        {
            "label": "Given Name",
            "type": "text",
            "example": null,
            "options": null,
            "user_value": {
                "source": "john_smith_story.pdf",
                "possible_value": "John",
                "doc_hash": [
                    "bca03f7db29b5f22c293f6cff2bf378a"
                ]
            },
            "possible_values": [
                {
                    "source": "john_smith_story.pdf",
                    "possible_value": "John",
                    "doc_hash": [
                        "bca03f7db29b5f22c293f6cff2bf378a"
                    ]
                }
            ]
        },
        {
            "label": "House nr",
            "type": "text",
            "example": null,
            "options": null,
            "user_value": {
                "source": "john_smith_story.pdf",
                "possible_value": "45B",
                "doc_hash": [
                    "bca03f7db29b5f22c293f6cff2bf378a"
                ]
            },
            "possible_values": [
                {
                    "source": "john_smith_story.pdf",
                    "possible_value": "45B",
                    "doc_hash": [
                        "bca03f7db29b5f22c293f6cff2bf378a"
                    ]
                },
                {
                    "source": "john_smith_story.pdf",
                    "possible_value": "123",
                    "doc_hash": [
                        "bca03f7db29b5f22c293f6cff2bf378a"
                    ]
                }
            ]
        }
    ],
    "message": "Form filled successfully"
}

Response Fields

Field	Type	Description
data	array	Array of filled form field objects
data[].label	string	Field label from the form
data[].type	string	Field type
data[].example	string/null	Example value (if available)
data[].options	array/null	Available options for select/multiselect fields
data[].user_value	object	Primary selected value for this field
data[].user_value.source	string	Source document filename where value was found
data[].user_value.possible_value	string	Extracted value selected as primary
data[].user_value.doc_hash	array	Document process IDs where value was found
data[].possible_values	array	All possible values found for this field across source documents
data[].possible_values[].source	string	Source document filename
data[].possible_values[].possible_value	string	Alternative extracted value
data[].possible_values[].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/form/fill' \
--header 'access-key: YOUR_ACCESS_KEY' \
--header 'Content-Type: application/json' \
--data '{
    "source_doc_process_ids": [
        "bca03f7db29b5f22c293f6cff2bf378a"
    ],
    "model_data": {
        "model_name": "gpt-5.1",
        "api_key": ""
    },
    "unfilled_form_data": [
        {
            "label": "Given Name",
            "type": "text",
            "example": null,
            "options": null,
            "user_value": {
                "source": null,
                "possible_value": null
            }
        }
    ]
}'

import requests
import json

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

payload = json.dumps({
    "source_doc_process_ids": [
        "bca03f7db29b5f22c293f6cff2bf378a"
    ],
    "model_data": {
        "model_name": "gpt-5.1",
        "api_key": ""
    },
    "unfilled_form_data": [
        {
            "label": "Given Name",
            "type": "text",
            "example": None,
            "options": None,
            "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": [
        "bca03f7db29b5f22c293f6cff2bf378a"
    ],
    "model_data": {
        "model_name": "gpt-5.1",
        "api_key": ""
    },
    "unfilled_form_data": [
        {
            "label": "Given Name",
            "type": "text",
            "example": null,
            "options": null,
            "user_value": {
                "source": null,
                "possible_value": null
            }
        }
    ]
});

let config = {
    method: 'post',
    maxBodyLength: Infinity,
    url: 'https://api.k-v.ai/api/agent/form/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

Form Structure Required: Use the exact form_template structure from Form Generation API
Source Documents: All source documents must have status: "processed"
Multiple Sources: Provide multiple source document IDs for better data coverage
Alternative Values: Review possible_values array for alternative options
Source Citations: Each value includes source document and doc_hash for traceability
Field Matching: AI intelligently maps source data to appropriate form fields

Next Steps

After filling a form:

Review Values: Check user_value for AI-selected primary values
Consider Alternatives: Review possible_values for other options
Verify Sources: Use source citations to validate extracted data
Export Data: Convert filled form to your desired format
Manual Review: Always review AI-extracted data before submission

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

Form Filling

On this page