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.

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

   • If you do not have a Koncile account, create one !

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.

If you have struggle grasping the different extraction concepts that are Folder, Template, Field and Instruction, please read this quick explanation of those concepts here Understanding Koncile's Structure

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