Taggun API Reference

The Taggun API is a REST API that turns receipts and invoices into structured data — scan documents, evaluate promotion rules, and detect fraud signals through one authenticated interface. It has four endpoint families, matching the categories on the left:

• Verbose Receipt & Invoice Extraction — send a document, get the broader extraction schema back: line items, detailed merchant fields, metadata, and feature envelopes.
• Simple Receipt & Invoice Extraction — the same inputs returning the compact core fields: totals, tax, date, and merchant.
• Receipt Validation (Beta) — validate receipts against rules supplied inline with each request.
• Campaign Validation — validate receipts against a stored campaign's rules, with full campaign lifecycle management.

Supporting them all, Data Enrichment lets you upload reference data that fine-tunes your results — product codes normalised to an expected set, product categories for receipt- and product-level categorisation, and known merchants that resolve a name and location to an exact match with a confidence level.

Relevant Guides

• Quick Start — sign up, get your API key, and make your first scan in a few minutes.
• Your First 30 Days — a structured evaluation path from first scan to production decision.
• Understanding Your Results — how to read extraction responses, field by field.

Design Principles

• Synchronous by design — every result arrives in the HTTP response to your request. No webhooks, callbacks, or job polling.
• Documents in, structure out — send a file upload, a public URL, or base64-encoded content; the response shape is the same for each input method.
• Two response depths — every extraction input has a simple and a verbose form, so you integrate the compact core fields or the full extraction schema.
• One header to authenticate — a single API key in the apikey header. No OAuth flows, token refresh, or signing.

Prerequisites

1. Create a Taggun account — sign up at taggun.io. Your API key is emailed on sign-up.
2. Retrieve your API key — it is also available any time in your account dashboard.
3. Choose an endpoint family — evaluating extraction quality? Start with Upload File (verbose). Building receipt-based promotions? There are two routes: create a stored campaign and run every receipt against it (Campaign Validation), or pass the effective rules in with each request — more flexible, at a higher integration cost (Receipt Validation).

Make Your First Request

Scan your first receipt with the language of your choice — replace YOUR_API_KEY and point file at a receipt image or PDF:

curl --request POST \
     --url https://api.taggun.io/api/receipt/v1/simple/file \
     --header 'accept: application/json' \
     --header 'apikey: YOUR_API_KEY' \
     --form '[email protected]'

import requests

url = "https://api.taggun.io/api/receipt/v1/simple/file"
headers = {"accept": "application/json", "apikey": "YOUR_API_KEY"}

with open("receipt.jpg", "rb") as f:
    response = requests.post(url, headers=headers, files={"file": ("receipt.jpg", f, "image/jpeg")})

print(response.json())

// Node 20+
import { openAsBlob } from "node:fs";

const form = new FormData();
form.append("file", await openAsBlob("receipt.jpg"), "receipt.jpg");

const response = await fetch("https://api.taggun.io/api/receipt/v1/simple/file", {
  method: "POST",
  headers: { accept: "application/json", apikey: "YOUR_API_KEY" },
  body: form,
});

console.log(await response.json());

The response returns the extracted totals, tax, date, and merchant details as JSON. To see the full field-by-field breakdown, read Understanding Your Results; to go deeper than the core fields, switch to the verbose form.

Authentication

Every request needs your API key in the apikey header — exactly as in the first request above. Your key is emailed on sign-up and available in your account dashboard. New to Taggun? Start with the Quick Start.

If the apikey header is missing, the API gateway returns 401 with { "message": "No API key found in request" }. If the key is present but invalid, it returns 403 with { "message": "Invalid authentication credentials" }.

Simple vs Verbose Endpoints

Each extraction input method has two forms. Simple returns the compact core-field schema. Verbose uses the broader extraction schema and can return line items, helper arrays, detailed merchant fields, per-field metadata, and enabled feature envelopes when those values are produced for the document. The API playground uses the feature settings on the API key you test with, so an account with more settings enabled can return a broader response shape than a default/core-only account. Evaluating Taggun? Use verbose. See Understanding Your Results.

Campaign Validation vs Receipt Validation

Both validation families check a receipt against your rules and return pass/fail with reasons — they differ in where the rules live. Campaign Validation stores them once as a campaign under a campaignId; every receipt is validated against that campaign, and five management endpoints cover the campaign lifecycle. Running a defined promotion? Start there. Receipt Validation (Beta) takes the rules inline with each request instead — nothing is stored, which is more flexible when rules vary per request or live in your own system, at a higher integration cost.

Errors

The API uses standard HTTP status codes; error causes and retry guidance are covered in Error Handling & Status Codes.

Try It in the Playground

Endpoint pages provide an interactive console. Paste your API key, supply that operation's required fields or file, and press Try It! to see its response in your browser — no code required.