v1.0

Klemo API Reference

Extract structured data from invoices, receipts, and tables using the Klemo API. Upload files or send URLs — get JSON back in under 3 seconds.

API Status: Operational

Base URL:https://klemo.in/api/v1

Authentication

All API requests require an API key sent in the x-api-key header. Get your key from the Klemo dashboard.

Header

http

x-api-key: klemo_sk_xxxxxxxxxxxxxxxxxxxx

Invoice Extraction

1 credit

Receipt Extraction

1 credit

Table Extraction

2 credits

⚠️ Keep your API key secret. Never expose it in client-side code or public repositories.

Extract Invoice

POST/api/v1/extract

Upload an invoice image or PDF to extract structured data including vendor, line items, totals, dates, and more.

Request

Parameter	Type	Description
`file`required	File	Invoice image (PNG, JPG, WebP) or PDF. Max 10MB.

cURL Example

bash

curl -X POST https://klemo.in/api/v1/extract \
  -H "x-api-key: klemo_sk_xxxx" \
  -F "file=@invoice.pdf"

JavaScript (fetch)

javascript

const form = new FormData();
form.append("file", fileInput.files[0]);

const res = await fetch("https://klemo.in/api/v1/extract", {
  method: "POST",
  headers: { "x-api-key": "klemo_sk_xxxx" },
  body: form,
});

const { data } = await res.json();
console.log(data.vendor, data.total, data.items);

Python

python

import requests

res = requests.post(
    "https://klemo.in/api/v1/extract",
    headers={"x-api-key": "klemo_sk_xxxx"},
    files={"file": open("invoice.pdf", "rb")},
)

data = res.json()["data"]
print(f"{data['vendor']} — ${data['total']}")

Response

200 OK

json

{
  "success": true,
  "data": {
    "id": "uuid-extraction-id",
    "vendor": "Acme Corp",
    "invoice_number": "INV-2024-001",
    "invoice_date": "2024-03-15",
    "due_date": "2024-04-15",
    "currency": "USD",
    "subtotal": 850.00,
    "discount": null,
    "tax": 68.00,
    "total": 918.00,
    "items": [
      {
        "description": "Web Development Services",
        "quantity": 10,
        "unit_price": 85.00,
        "total": 850.00
      }
    ],
    "payment_status": "unpaid",
    "confidence": 0.97,
    "category": "services",
    "processing_time_ms": 1823
  }
}

Response Headers

Parameter	Type	Description
`X-Processing-Time`	string	Time taken to process (e.g. '1823ms')
`X-Credits-Remaining`	number	Credits remaining after this request
`X-Credits-Limit`	number	Your plan's monthly credit limit
`X-RateLimit-Remaining`	number	Rate limit requests remaining
`X-Plan`	string	Your current plan ID

Extract Receipt

POST/api/v1/extract/receipt

Upload a receipt image to extract store info, items, totals, payment method, and more.

Request

Parameter	Type	Description
`file`required	File	Receipt image (PNG, JPG, WebP) or PDF. Max 10MB.

cURL Example

bash

curl -X POST https://klemo.in/api/v1/extract/receipt \
  -H "x-api-key: klemo_sk_xxxx" \
  -F "file=@receipt.jpg"

Response

200 OK

json

{
  "success": true,
  "extraction_type": "receipt",
  "credits_used": 1,
  "data": {
    "id": "uuid-extraction-id",
    "store_name": "Whole Foods Market",
    "store_address": "123 Main St, Austin TX",
    "store_phone": "(512) 555-0123",
    "receipt_number": "R-78234",
    "date": "2024-03-15",
    "time": "14:23",
    "currency": "USD",
    "items": [
      { "name": "Organic Bananas", "quantity": 1, "price": 1.99 },
      { "name": "Almond Milk", "quantity": 2, "price": 7.98 }
    ],
    "subtotal": 9.97,
    "tax": 0.82,
    "tax_rate": "8.25%",
    "tip": 0,
    "total": 10.79,
    "payment_method": "credit_card",
    "card_last_four": "4242",
    "category": "groceries",
    "confidence": 0.95,
    "processing_time_ms": 2104
  }
}

Extract Table

POST/api/v1/extract/table

Upload an image containing tabular data to extract structured rows, columns, and headers. Costs 2 credits per extraction.

Request

Parameter	Type	Description
`file`required	File	Image with table data (PNG, JPG, WebP) or PDF. Max 10MB.

cURL Example

bash

curl -X POST https://klemo.in/api/v1/extract/table \
  -H "x-api-key: klemo_sk_xxxx" \
  -F "file=@spreadsheet.png"

Response

200 OK

json

{
  "success": true,
  "extraction_type": "table",
  "credits_used": 2,
  "data": {
    "id": "uuid-extraction-id",
    "title": "Q1 Revenue by Region",
    "headers": ["Region", "Q1 2024", "Q1 2023", "Growth"],
    "rows": [
      ["North America", "$2.4M", "$1.9M", "+26%"],
      ["Europe", "$1.8M", "$1.5M", "+20%"],
      ["Asia Pacific", "$1.2M", "$0.9M", "+33%"]
    ],
    "total_rows": 3,
    "total_columns": 4,
    "data_types": {
      "Region": "string",
      "Q1 2024": "currency",
      "Growth": "percentage"
    },
    "summary": "Revenue table showing Q1 performance across regions",
    "confidence": 0.94,
    "processing_time_ms": 2450
  }
}

Extract from URL

POST/api/v1/extract/url

Send a URL pointing to a document image or PDF — Klemo will download and extract it. Supports invoice, receipt, and table types.

Request Body (JSON)

Parameter	Type	Description
`url`required	string	HTTP/HTTPS URL to the document image or PDF
`type`	string	Extraction type: "invoice" (default), "receipt", or "table"

cURL Example

bash

curl -X POST https://klemo.in/api/v1/extract/url \
  -H "x-api-key: klemo_sk_xxxx" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/invoice.pdf", "type": "invoice"}'

JavaScript

javascript

const res = await fetch("https://klemo.in/api/v1/extract/url", {
  method: "POST",
  headers: {
    "x-api-key": "klemo_sk_xxxx",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    url: "https://example.com/invoice.pdf",
    type: "invoice",
  }),
});

const { data } = await res.json();

Batch Extract

POST/api/v1/batch

Upload multiple invoice files in a single request. Processes all files in parallel and returns results for each. Requires Starter plan or higher.

Request

Parameter	Type	Description
`files`required	File[]	Multiple invoice files (PNG, JPG, WebP, PDF). Max 10MB each.

ℹ️ Plan limits apply. Max batch size depends on your plan. Each successful extraction costs 1 credit.

cURL Example

bash

curl -X POST https://klemo.in/api/v1/batch \
  -H "x-api-key: klemo_sk_xxxx" \
  -F "files=@invoice1.pdf" \
  -F "files=@invoice2.pdf" \
  -F "files=@invoice3.jpg"

Response

200 OK

json

{
  "success": true,
  "data": {
    "total": 3,
    "completed": 2,
    "failed": 1,
    "processing_time_ms": 4520,
    "results": [
      {
        "index": 0,
        "success": true,
        "data": {
          "vendor": "Acme Corp",
          "invoice_number": "INV-001",
          "total": 918.00,
          "confidence": 0.97
        }
      },
      {
        "index": 1,
        "success": true,
        "data": { "vendor": "Globex Inc", "total": 1250.00 }
      },
      {
        "index": 2,
        "success": false,
        "error": { "code": "EXTRACTION_FAILED", "message": "Failed to extract." }
      }
    ]
  }
}

Async Extract

POST/api/v1/extract/async

Submit a file for background processing. Returns a job ID immediately — poll GET /api/v1/extractions/:id or listen to webhooks for completion.

Request

Parameter	Type	Description
`file`required	File	Image (PNG, JPG, WebP) or PDF. Max 10MB.
`type`	string	"invoice" (default), "receipt", or "table"
`webhook_url`	string	Optional URL to receive a POST when extraction completes

cURL Example

bash

curl -X POST https://klemo.in/api/v1/extract/async \
  -H "x-api-key: klemo_sk_xxxx" \
  -F "file=@invoice.pdf" \
  -F "type=invoice" \
  -F "webhook_url=https://your-app.com/webhook"

Response (immediate)

202 Accepted

json

{
  "success": true,
  "data": {
    "id": "uuid-extraction-id",
    "status": "processing",
    "extraction_type": "invoice",
    "message": "Extraction is processing. Poll GET /api/v1/extractions/:id for results.",
    "poll_url": "/api/v1/extractions/uuid-extraction-id"
  }
}

💡 Tip: Use webhooks instead of polling for real-time notifications when extraction completes.

List Extractions

GET/api/v1/extractions

Retrieve your past extractions with pagination and filtering. Useful for building dashboards or audit trails.

Query Parameters

Parameter	Type	Description
`limit`	number	Results per page (default: 20, max: 100)
`offset`	number	Pagination offset (default: 0)
`status`	string	Filter by status: "completed", "failed", "processing"
`type`	string	Filter by type: "invoice", "receipt", "table"
`from`	string	Start date filter (YYYY-MM-DD)
`to`	string	End date filter (YYYY-MM-DD)
`vendor`	string	Partial vendor name match
`min_confidence`	number	Minimum confidence score (0-1)

cURL Example

bash

curl "https://klemo.in/api/v1/extractions?limit=10&type=invoice&from=2024-03-01" \
  -H "x-api-key: klemo_sk_xxxx"

Response

200 OK

json

{
  "success": true,
  "data": [
    {
      "id": "uuid",
      "extraction_type": "invoice",
      "vendor": "Acme Corp",
      "invoice_number": "INV-001",
      "total": 918.00,
      "confidence": 0.97,
      "status": "completed",
      "processing_time_ms": 1823,
      "created_at": "2024-03-15T10:30:00Z"
    }
  ],
  "pagination": {
    "total": 47,
    "limit": 10,
    "offset": 0,
    "has_more": true
  }
}

Get Extraction

GET/api/v1/extractions/:id

Retrieve a single extraction by its ID. Useful for polling async extraction results or fetching full details.

Path Parameters

Parameter	Type	Description
`id`required	string	Extraction UUID

cURL Example

bash

curl https://klemo.in/api/v1/extractions/uuid-extraction-id \
  -H "x-api-key: klemo_sk_xxxx"

Response

200 OK

json

{
  "success": true,
  "data": {
    "id": "uuid-extraction-id",
    "extraction_type": "invoice",
    "vendor": "Acme Corp",
    "invoice_number": "INV-2024-001",
    "invoice_date": "2024-03-15",
    "due_date": "2024-04-15",
    "currency": "USD",
    "subtotal": 850.00,
    "tax": 68.00,
    "total": 918.00,
    "items": [...],
    "confidence": 0.97,
    "category": "services",
    "status": "completed",
    "source": "api",
    "file_name": "invoice.pdf",
    "file_size": 245890,
    "processing_time_ms": 1823,
    "created_at": "2024-03-15T10:30:00Z"
  }
}

Delete Extraction

DELETE/api/v1/extractions/:id

Permanently delete an extraction by ID. Requires 'full' scope on your API key. This action cannot be undone.

Path Parameters

Parameter	Type	Description
`id`required	string	Extraction UUID to delete

cURL Example

bash

curl -X DELETE https://klemo.in/api/v1/extractions/uuid-extraction-id \
  -H "x-api-key: klemo_sk_xxxx"

Response

200 OK

json

{
  "success": true,
  "message": "Extraction deleted."
}

⚠️ Destructive action. Deleted extractions cannot be recovered. Credits are not refunded.

Usage & Credits

GET/api/v1/usage

Check your current credit balance, plan details, rate limits, and extraction breakdown for the current billing period.

cURL Example

bash

curl https://klemo.in/api/v1/usage \
  -H "x-api-key: klemo_sk_xxxx"

Response

200 OK

json

{
  "success": true,
  "data": {
    "plan": {
      "id": "free",
      "name": "Free",
      "credits_per_month": 300,
      "rate_limit_per_minute": 10,
      "rate_limit_per_day": 100
    },
    "usage": {
      "period": "2024-03",
      "credits_used": 42,
      "credits_remaining": 258,
      "credits_limit": 300,
      "usage_percentage": 14
    },
    "breakdown": {
      "invoice": 30,
      "receipt": 8,
      "table": 2
    },
    "subscription": {
      "status": "active",
      "current_period_start": "2024-03-01",
      "current_period_end": "2024-03-31"
    }
  }
}

Integrations (Zapier / Make)

Connect Klemo to Zapier, Make, or any automation platform. Use the polling endpoint for triggers, or REST hooks for real-time events.

Zapier Polling Trigger

GET/api/v1/integrations/zapier

Returns the latest extractions as a flat array. Zapier polls this periodically to detect new extractions.

cURL Example

bash

curl https://klemo.in/api/v1/integrations/zapier \
  -H "x-api-key: klemo_sk_xxxx"

REST Hook Subscribe

POST/api/v1/integrations/hooks

Parameter	Type	Description
`target_url`required	string	URL to receive webhook POSTs when events fire
`event`required	string	Event to subscribe to (e.g. "extraction.completed")

json

// POST /api/v1/integrations/hooks
{
  "target_url": "https://hooks.zapier.com/xxx",
  "event": "extraction.completed"
}

// Response
{
  "success": true,
  "hook_id": "uuid-hook-id"
}

REST Hook Unsubscribe

DELETE/api/v1/integrations/hooks

Parameter	Type	Description
`hook_id`required	string	Hook ID returned from subscribe

Error Handling

All errors return a consistent JSON structure with an error code, message, and HTTP status. Use the error code for programmatic handling.

Error Response Format

json

{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_CREDITS",
    "message": "You have 0 credits remaining. Upgrade your plan.",
    "status": 402
  }
}

Error Codes

HTTP	Code	Description
401	`MISSING_API_KEY`	No x-api-key header provided
401	`INVALID_API_KEY`	API key not found or invalid
401	`REVOKED_API_KEY`	API key has been revoked
402	`INSUFFICIENT_CREDITS`	No credits remaining this period
403	`SCOPE_DENIED`	API key lacks required scope
400	`MISSING_FILE`	No file provided in request
400	`INVALID_FILE_TYPE`	Unsupported file format
400	`FILE_TOO_LARGE`	File exceeds 10MB limit
400	`INVALID_URL`	Invalid or unreachable URL
408	`URL_TIMEOUT`	URL download timed out (30s)
429	`RATE_LIMITED`	Too many requests, slow down
500	`EXTRACTION_FAILED`	AI extraction failed, retry

Ready to start extracting?

Get Your API Key