Getting Started

Welcome to the Koncile API. This guide will walk you through the complete setup process, from generating your API key to extracting data from your first document.

Prerequisites

• A Koncile account with API access

• Admin access to generate API keys (if you're part of a multi-user company)

---

Understanding Koncile's Structure

Before diving into the API, it's important to understand how Koncile organizes document extraction.

The Hierarchy

Company
└── Folders
    └── Templates
        ├── Fields
        └── Instructions

Concept	Purpose	Example
Folder	Organizes templates by document category	"Supplier Invoices", "Purchase Orders", "Receipts"
Template	Defines extraction rules for a specific document type	"Acme Corp Invoice", "Standard PO Template"
Field	A specific piece of data to extract, can be General or Line	"Invoice Number", "Total Amount", "Supplier Name"
Instruction	Custom guidance for the AI extractor that is applied to General or Line fields	Always skip the first page of the document

How It Works

When you upload a document:

1. Koncile identifies which template to use (either specified by you or auto-detected)

2. The AI reads the document and extracts values for each field defined in the template

3. Results are returned with extracted values and confidence scores

Field & Instruction Types Explained

Koncile supports two types of fields:

Type	When to Use	Examples
General fields	Data that appears once per document	Invoice number, invoice date, supplier name, total amount
Line fields	Data that repeats for each line item	Product name, quantity, unit price, line total

For example, on an invoice:

• The invoice number appears once → General field

• Each product line has its own name, quantity, and price → Line fields

An instruction that has a type General field only concerns the General fields. Same logic for the Line fields

Field Formats

Each field has a format that helps the AI understand what type of data to extract:

Format	Description	Use Case
text	Free-form text	Names, descriptions, addresses
number	Numeric values	Amounts, quantities, percentages
date	Date values	Invoice dates, due dates
boolean	True/false	Checkboxes, yes/no fields
multiple_choice	Selection from predefined options	Payment terms, document status
unit	Unit of measurement	kg, liters, pieces
empty	Placeholder	If you want the field to appear in your ouput data but don't need to extract values

---

Step 1: Generate Your API Key

API keys are generated from within the Koncile web application.

1. Log into your Koncile account at app.koncile.ai

2. Navigate to Settings > API

3. Click Generate API Key

4. Copy and securely store your API key

Important: The API key is only shown once. Store it securely (e.g., in environment variables or a secrets manager). If you lose it, you'll need to generate a new one.

Note: Only company administrators can generate API keys. If you don't see the API settings, contact your company admin.

---

Step 2: Verify Your API Key

Before proceeding, verify that your API key is working:

cURL

curl -X POST "https://api.koncile.ai/v1/check_api_key" \
  -H "Authorization: Bearer YOUR_API_KEY"

Python

Expected response:

{"success": true}

If you receive an error, double-check that:

• Your API key is correct and complete

• The Authorization header uses the format Bearer YOUR_API_KEY

• Your API key hasn't been revoked

---

Step 3: Create Your Extraction Setup

Now let's create a complete extraction setup. We'll create a folder, template, fields, and instructions.

3.1 Create a Folder

Folders help you organize templates by document type or business purpose.

cURL

curl -X POST "https://api.koncile.ai/v1/create_folder" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Supplier Invoices",
    "desc": "Invoices received from suppliers"
  }'

Python

Response:

{
    "id": 1,
    "name": "Supplier Invoices",
    "desc": "Invoices received from suppliers",
    "templates": []
}

Save the id value - you'll need it to create templates.

3.2 Create a Template

Templates define what data to extract from documents. Each template belongs to a folder.

cURL

curl -X POST "https://api.koncile.ai/v1/create_template" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Standard Invoice",
    "desc": "Template for standard supplier invoices",
    "type": "invoice",
    "folder_id": 1
  }'

Python

3.3 Create Fields

Fields define what data points to extract. Let's create both general fields and line fields.

General Fields (extracted once per document):

cURL

# Create Invoice Number field
curl -X POST "https://api.koncile.ai/v1/create_field" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Invoice Number",
    "type": "General fields",
    "format": "text",
    "template_id": 1,
    "desc": "The unique identifier for this invoice"
  }'

# Create Invoice Date field
curl -X POST "https://api.koncile.ai/v1/create_field" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Invoice Date",
    "type": "General fields",
    "format": "date",
    "template_id": 1,
    "desc": "The date the invoice was issued"
  }'

# Repeat for other fields...

Python

Line Fields (extracted for each line item):

Python

line_fields = [
    {
        "name": "Product Description",
        "type": "Line fields",
        "format": "text",
        "template_id": template_id,
        "desc": "Description of the product or service"
    },
    {
        "name": "Quantity",
        "type": "Line fields",
        "format": "number",
        "template_id": template_id,
        "desc": "Number of units"
    },
    {
        "name": "Unit Price",
        "type": "Line fields",
        "format": "number",
        "template_id": template_id,
        "desc": "Price per unit"
    },
    {
        "name": "Line Total",
        "type": "Line fields",
        "format": "number",
        "template_id": template_id,
        "desc": "Total amount for this line (quantity × unit price)"
    }
]

for field in line_fields:
    response = requests.post(
        "https://api.koncile.ai/v1/create_field",
        headers={
            "Authorization": "Bearer YOUR_API_KEY",
            "Content-Type": "application/json"
        },
        json=field
    )
    result = response.json()
    print(f"Created field '{field['name']}' with ID: {result['id']}")

Tip: The desc field is important - it helps the AI understand exactly what to extract, especially for ambiguous fields.

3.4 Create Instructions (Optional)

Instructions or context are pieces of information you provide to the tool to help it extract data from your documents more accurately. They're especially useful for:

• Excluding some information (specific pages of a document, total lines at the end of a table)

• Giving additional context to the AI

Python

instructions = [
    {
        "content": "",
        "type": "General fields",
        "template_id": template_id
    },
    {
        "content": "For currency amounts, extract only the numeric value without currency symbols or thousand separators.",
        "type": "General fields",
        "template_id": template_id
    },
    {
        "content": "If a line item description spans multiple lines, combine them into a single text entry.",
        "type": "Line fields",
        "template_id": template_id
    }
]

for instruction in instructions:
    response = requests.post(
        "https://api.koncile.ai/v1/create_instruction",
        headers={
            "Authorization": "Bearer YOUR_API_KEY",
            "Content-Type": "application/json"
        },
        json=instruction
    )
    result = response.json()
    print(f"Created instruction with ID: {result['id']}")

---

Step 4: Upload a Document

Now that your extraction setup is complete, you can upload documents.

cURL

curl -X POST "https://api.koncile.ai/v1/upload_file/?folder_id=1&template_id=1" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "[email protected]"

Python

Node.js

Response:

{
    "task_ids": ["EOBdOSUX4Uv57YWsLYc4JQ"]
}

Note: The trailing slash in /upload_file/ is required.

Auto-classification: If you omit folder_id and template_id, Koncile will automatically classify the document and select the best matching template.

---

Step 5: Retrieve Extraction Results

Extraction happens asynchronously. Poll the task status until it completes:

Python

import time

def wait_for_extraction(task_id, api_key, timeout=300):
    url = "https://api.koncile.ai/v1/fetch_tasks_results"
    headers = {"Authorization": f"Bearer {api_key}"}
    start_time = time.time()

    while time.time() - start_time < timeout:
        response = requests.get(url, headers=headers, params={"task_id": task_id})
        result = response.json()

        print(f"Status: {result['status']}")

        if result["status"] == "DONE":
            return result
        elif result["status"] == "FAILED":
            raise Exception(f"Extraction failed: {result['status_message']}")

        time.sleep(2)

    raise TimeoutError("Extraction timed out")

# Wait for results
result = wait_for_extraction(task_id, "YOUR_API_KEY")

# Display extracted data
print(f"\nDocument ID: {result['document_id']}")
print(f"Document Name: {result['document_name']}")

print("\n--- General Fields ---")
for field_name, data in result["General_fields"].items():
    print(f"{field_name}: {data['value']} (confidence: {data['confidence_score']:.2f})")

print("\n--- Line Items ---")
line_fields = result["Line_fields"]
if line_fields:
    num_lines = len(list(line_fields.values())[0])
    for i in range(num_lines):
        print(f"\nLine {i + 1}:")
        for field_name, values in line_fields.items():
            print(f"  {field_name}: {values[i]['value']}")

Example response when complete:

{
    "status": "DONE",
    "status_message": "Extraction completed successfully",
    "child_task_ids": Null, // For Smart-Splitting functionality (Beta) 
    "task_id": "EOBdOSUX4Uv57YWsLYc4JQ",
    "document_id": 12345,
    "document_name": "invoice.pdf",
    "General_fields": {
        "Invoice Number": {
            "value": "INV-2024-0042",
            "confidence_score": 0.98
        },
        "Invoice Date": {
            "value": "2024-01-15",
            "confidence_score": 0.95
        },
        "Supplier Name": {
            "value": "Acme Corporation",
            "confidence_score": 0.97
        },
        "Total Amount": {
            "value": "1250.00",
            "confidence_score": 0.96
        }
    },
    "Line_fields": {
        "Product Description": [
            {"value": "Widget Pro X100", "confidence_score": 0.94},
            {"value": "Service Package - Premium", "confidence_score": 0.92}
        ],
        "Quantity": [
            {"value": "10", "confidence_score": 0.99},
            {"value": "1", "confidence_score": 0.98}
        ],
        "Unit Price": [
            {"value": "75.00", "confidence_score": 0.95},
            {"value": "500.00", "confidence_score": 0.96}
        ],
        "Line Total": [
            {"value": "750.00", "confidence_score": 0.97},
            {"value": "500.00", "confidence_score": 0.97}
        ]
    }
}

---

Complete Example Script

Here's a complete Python script that performs all the steps above:

import requests
import time

API_KEY = "YOUR_API_KEY"
BASE_URL = "https://api.koncile.ai/v1"

def api_request(method, endpoint, **kwargs):
    headers = {"Authorization": f"Bearer {API_KEY}"}
    if "json" in kwargs:
        headers["Content-Type"] = "application/json"

    response = requests.request(
        method,
        f"{BASE_URL}/{endpoint}",
        headers=headers,
        **kwargs
    )
    response.raise_for_status()
    return response.json()

# Step 1: Create folder
folder = api_request("POST", "create_folder", json={
    "name": "Supplier Invoices",
    "desc": "Invoices from suppliers"
})
folder_id = folder["id"]
print(f"Created folder: {folder_id}")

# Step 2: Create template
template = api_request("POST", "create_template", json={
    "name": "Standard Invoice",
    "type": "invoice",
    "folder_id": folder_id
})
template_id = template["id"]
print(f"Created template: {template_id}")

# Step 3: Create fields
fields = [
    {"name": "Invoice Number", "type": "General fields", "format": "text"},
    {"name": "Invoice Date", "type": "General fields", "format": "date"},
    {"name": "Total Amount", "type": "General fields", "format": "number"},
    {"name": "Product", "type": "Line fields", "format": "text"},
    {"name": "Quantity", "type": "Line fields", "format": "number"},
    {"name": "Price", "type": "Line fields", "format": "number"},
]

for field in fields:
    result = api_request("POST", "create_field", json={**field, "template_id": template_id})
    print(f"Created field: {field['name']}")

# Step 4: Create instruction
api_request("POST", "create_instruction", json={
    "content": "Extract dates in YYYY-MM-DD format",
    "type": "General fields",
    "template_id": template_id
})
print("Created instruction")

# Step 5: Upload document
with open("invoice.pdf", "rb") as f:
    response = requests.post(
        f"{BASE_URL}/upload_file/",
        headers={"Authorization": f"Bearer {API_KEY}"},
        files={"files": f},
        params={"folder_id": folder_id, "template_id": template_id}
    )
task_id = response.json()["task_ids"][0]
print(f"Uploaded document, task ID: {task_id}")

# Step 6: Wait for results
while True:
    result = api_request("GET", "fetch_tasks_results", params={"task_id": task_id})

    if result["status"] == "DONE":
        print("\nExtraction complete!")
        print(f"Document ID: {result['document_id']}")
        for name, data in result["General_fields"].items():
            print(f"{name}: {data['value']}")
        break
    elif result["status"] == "FAILED":
        print(f"Failed: {result['status_message']}")
        break

    print(f"Status: {result['status']}...")
    time.sleep(2)

---

Next Steps

Now that you understand the basics, explore these topics:

• File Uploading - Batch uploads, metadata, and file constraints

• Task Retrieval - Detailed response format and polling strategies

• Document Management - List, download, and delete documents

• Folders, Templates, Fields & Instructions - Complete API reference

• API Status Codes - Error handling and troubleshooting

• SDK Libraries - Python and Node.js SDKs for easier integration