# Taggun

Taggun is an AI-powered receipt OCR API that extracts structured data from receipt and invoice images in real-time. It supports 85+ languages, fraud detection, and automated expense tracking.

- **Category:** ai document extraction
- **Auth:** API_KEY
- **Tools:** 5
- **Triggers:** 0
- **Slug:** `TAGGUN`
- **Version:** 20260211_00

## Tools

### Add Merchant Name

**Slug:** `TAGGUN_ADD_MERCHANT_NAME`

Tool to add a merchant name keyword to your account's model for predicting merchant names. Use when you want to improve merchant name recognition by training the model with specific merchant names. Changes to your account's model are updated daily and will affect future receipt processing.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `merchantName` | string | Yes | Merchant name keyword to add to your account's model for predicting merchant names. The model updates are applied daily. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | object | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Export Known Merchants

**Slug:** `TAGGUN_EXPORT_KNOWN_MERCHANTS`

Export the complete list of known merchants used for merchant name normalization in Taggun. Returns CSV data with merchant details including location IDs, names, addresses, and coordinates. Use this when you need to retrieve the full merchant registry for synchronization, auditing, or analysis. No parameters required - this is a read-only GET operation.

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | object | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Export Known Product Codes

**Slug:** `TAGGUN_EXPORT_KNOWN_PRODUCT_CODES`

Export the complete list of known product codes used for product normalization and matching in Taggun. Returns CSV data with product code information. Use this when you need to retrieve the full product code registry for synchronization, auditing, or analysis. No parameters required - this is a read-only GET operation.

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | object | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Export Product Categories

**Slug:** `TAGGUN_EXPORT_PRODUCT_CATEGORIES`

Export a list of product categories and descriptions used for product categorization in CSV format. Returns CSV data with product category information for analysis or synchronization purposes. Use this when you need to retrieve the complete product category registry.

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | object | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Generate Merchants CSV

**Slug:** `TAGGUN_GENERATE_MERCHANTS_CSV`

Generate a CSV file with mock merchant data for testing purposes. Creates a temporary CSV file with the specified number of merchant rows, including fields like name, alias, address, coordinates, contact info, and tags. Use this when you need sample merchant data for bulk import operations or testing merchant-related API endpoints. The generated CSV follows a standard format with 10 columns: name, alias, address, postcode, lat, lng, country, phone, email, tags.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `row_count` | integer | Yes | Number of merchant rows to generate in the CSV |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | object | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Import Known Merchants

**Slug:** `TAGGUN_IMPORT_KNOWN_MERCHANTS`

Import a list of merchant names and addresses to normalize and match in CSV or TSV format. Use this when you need to bulk upload merchant data for name normalization and matching. File must be less than 20MB and contain merchant information in CSV or TSV format.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `file` | object | Yes | CSV or TSV file containing merchant data to import. Must be less than 20MB. File should have columns for merchant names and addresses. FileUploadable object where 'name' should be the filename (e.g., 'merchants.csv'). |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | object | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Import Known Product Codes

**Slug:** `TAGGUN_IMPORT_KNOWN_PRODUCT_CODES`

Tool to import a list of product codes in CSV or TSV format for normalization and matching. Use when you need to upload product code data to Taggun for receipt/invoice processing. The file should contain product codes with descriptions (e.g., code,description columns).

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `file` | object | No | CSV or TSV file containing product codes to import. FileUploadable object where 'name' is the filename (e.g., 'product_codes.csv'). File must be less than 20MB and contain product code data with columns like 'code' and 'description'. Accepted formats: CSV, TSV. If not provided, you may use raw_content instead. |
| `raw_content` | string | No | Inline CSV or TSV file content to upload as bytes or UTF-8 string, used when FileUploadable is not available. |
| `raw_filename` | string | No | Filename for the inline content (e.g., 'product_codes.csv'). Defaults to 'product_codes.csv'. |
| `raw_mimetype` | string | No | MIME type for the inline content (e.g., 'text/csv', 'text/tab-separated-values'). Defaults to text/csv. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | object | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Import Product Categories

**Slug:** `TAGGUN_IMPORT_PRODUCT_CATEGORIES`

Import a list of product categories and descriptions for product categorization. Accepts CSV or TSV files (less than 20MB) with category and description columns. Use this when you need to bulk import product category data for matching during receipt processing.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `file` | object | No | CSV or TSV file containing product categories and descriptions. FileUploadable object where 'name' should be the filename (e.g., 'categories.csv', 'categories.tsv'). File must be less than 20MB. Format: category,description. If not provided, you may use raw_content instead. |
| `raw_content` | string | No | Inline CSV or TSV file content to upload as bytes or UTF-8 string, used when FileUploadable is not available. |
| `raw_filename` | string | No | Filename for the inline content (e.g., 'categories.csv'). Defaults to 'categories.csv'. |
| `raw_mimetype` | string | No | MIME type for the inline content (e.g., 'text/csv', 'text/tab-separated-values'). Defaults to text/csv. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | object | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Transcribe Receipt from Base64 Encoded Image

**Slug:** `TAGGUN_TRANSCRIBE_RECEIPT_ENCODED_SIMPLE`

Extract structured data from a receipt or invoice using base64 encoded image data. Provide a base64 encoded image (JPEG, PNG, PDF, GIF) along with filename and content type to get back extracted fields like total amount, date, merchant name, tax, line items, and confidence scores. Use this when you have receipt/invoice image data already encoded as base64 and need to digitize the data. The API uses machine learning OCR to detect and extract key fields automatically.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `image` | string | Yes | Base64 encoded image data of the receipt or invoice. Supported formats: JPEG, PNG, PDF, GIF. The string should contain only the base64-encoded data without any data URI prefix. |
| `refresh` | boolean | No | Set to true to bypass Taggun's cache and force fresh OCR processing of the image. Default is false (uses cached results if available). |
| `filename` | string | Yes | Filename for reference purposes (e.g., 'receipt.jpg'). Required for proper processing. |
| `language` | string | No | Set language as a hint for OCR processing. Leave empty for auto detect. Supported languages: en, es, fr, jp, he, iw, et, lv, lt, fi, el, zh, th, ar |
| `incognito` | boolean | No | Set true to avoid saving the receipt in storage for privacy purposes. Default is false. |
| `ipAddress` | string | No | IP Address of the end user for fraud detection purposes |
| `containerId` | string | No | Tag a request with a container ID for fraud detection purposes. Maximum 50 characters. |
| `contentType` | string | Yes | MIME type of the image file. Required. Supported types: 'image/jpeg', 'image/png', 'application/pdf', 'image/gif'. |
| `extractTime` | boolean | No | Set true to return time if found on the receipt. Otherwise, the time is always set to 12:00:00.000. Default is false. |
| `ignoreMerchantName` | string | No | Ignore this merchant name if detected on the receipt. Use this field to avoid detecting the customer name as the merchant name. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | object | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Transcribe Receipt Encoded Verbose

**Slug:** `TAGGUN_TRANSCRIBE_RECEIPT_ENCODED_VERBOSE`

Tool to transcribe a receipt using base64 encoded image in JSON payload and return detailed results. Use when you have a base64 encoded receipt image and require comprehensive output including line items, merchant details, and confidence levels. The image must be larger than 1x1 pixels to avoid validation errors.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `image` | string | Yes | Base64 encoded receipt image. Must meet minimum size requirements (larger than 1x1 pixels). |
| `refresh` | boolean | No | Set true to force re-process image transcription if receipt is already in storage. |
| `filename` | string | Yes | The filename for the receipt image. |
| `incognito` | boolean | No | Set true to avoid saving the receipt in storage. |
| `containerId` | string | No | Tag a request with a container ID for fraud detection purposes. |
| `contentType` | string | Yes | MIME type of the image (e.g., image/jpeg, image/png). |
| `extractTime` | boolean | No | Set true to return time if found on the receipt. Otherwise, the time is always set to 12:00:00.000. |
| `extractLineItems` | boolean | No | Set true to return product line items in an array if found on the receipt. |
| `ignoreMerchantName` | string | No | Ignore this merchant name if detected on the receipt. Use this field to avoid detecting the customer name as the merchant name. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | object | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Transcribe Receipt File (Simple)

**Slug:** `TAGGUN_TRANSCRIBE_RECEIPT_FILE_SIMPLE`

Tool to upload a receipt or invoice image file and extract basic data including merchant name, total amount, tax amount, and date. Use when you need to digitize receipt data from a file (PDF, JPG, PNG, GIF, HEIC up to 20MB). The API uses OCR to detect and extract key fields.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `file` | object | Yes | Receipt or invoice image file to upload (less than 20MB). FileUploadable object where 'name' is the filename. Supported formats: PDF, JPG, PNG, GIF, HEIC |
| `near` | string | No | A geo location to search for merchant. Typically in the format of city, state, country. |
| `userId` | string | No | Tag a request with a user ID so that duplicate receipts by the same user can be detected |
| `refresh` | boolean | No | Set true to force re-process image transcription if the receipt is already in storage. Default is false. |
| `language` | string ("en" | "es" | "fr" | "jp" | "he" | "iw" | "et" | "lv" | "lt" | "fi" | "el" | "zh" | "th" | "ar") | No | Supported languages for receipt OCR processing. |
| `incognito` | boolean | No | Set true to avoid saving the receipt in storage. Default is false. |
| `ipAddress` | string | No | IP Address of the end user for fraud detection purposes |
| `containerId` | string | No | Tag a request with a container ID for fraud detection purposes |
| `extractTime` | boolean | No | Set true to return time if found on the receipt. Otherwise, the time is always set to 12:00:00.000. Default is false. |
| `referenceId` | string | No | Tag a request with a unique reference ID for feedback/training and receipt similarity check purposes |
| `subAccountId` | string | No | Tag a request with sub-account ID for billing purposes |
| `ignoreMerchantName` | string | No | Ignore this merchant name if detected on the receipt. Use this field to avoid detecting the customer name as the merchant name. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | object | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Process Receipt via URL

**Slug:** `TAGGUN_URL`

Extract structured data from a receipt or invoice image using OCR. Provide a public URL to a receipt/invoice image (JPEG, PNG, PDF, GIF) and get back extracted fields like total amount, date, merchant name, tax, line items, and confidence scores. Use this when you need to digitize receipt/invoice data from a publicly accessible image URL. The API uses machine learning OCR to detect and extract key fields automatically.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `url` | string | Yes | Public HTTPS URL of the receipt/invoice image. Supported formats: JPEG, PNG, PDF, GIF. URL must be publicly accessible and point directly to the image file. |
| `refresh` | boolean | No | Set to true to bypass Taggun's cache and force fresh OCR processing of the image. Default is false (uses cached results if available). |
| `filename` | string | No | Optional filename for reference purposes (e.g., 'receipt.jpg'). Does not affect processing. |
| `contentType` | string | No | Optional MIME type of the image file (e.g., 'image/jpeg', 'image/png', 'application/pdf'). Auto-detected if not provided. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | object | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### URL Validation

**Slug:** `TAGGUN_URL_VALIDATION`

Tool to extract and validate receipt data from a URL. Processes a receipt image from a public URL and returns extracted fields with confidence levels to assess receipt authenticity. Use when you have a receipt URL and need to verify it contains valid receipt data.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `url` | string | Yes | The URL of the receipt image to be validated. |
| `filename` | string | No | Optional filename to assign to the image. |
| `doNotSave` | boolean | No | If true, the receipt will not be saved in the database. |
| `externalId` | string | No | An external ID to link with the validation for tracking purposes. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | object | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### URL Verbose

**Slug:** `TAGGUN_URL_VERBOSE`

Tool to process a receipt or invoice from a URL for detailed data extraction. Use when you have a publicly accessible receipt or invoice URL and require comprehensive output including line items, merchant details, and confidence metrics. Call after verifying the URL is reachable.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `url` | string | Yes | Publicly accessible URL of the receipt or invoice image. |
| `near` | string | No | Location hint (city, state, country) for merchant search. |
| `refresh` | boolean | No | If true, forces reprocessing even if cached results exist. |
| `language` | string | No | Language hint for OCR (supports: en, es, fr, jp, he, iw, et, lv, lt, fi, el, zh, th). |
| `incognito` | boolean | No | If true, excludes this document from Taggun's learning dataset. |
| `ipAddress` | string | No | End-user IP address for fraud assessment. |
| `extractTime` | boolean | No | Return extracted time; defaults to 12:00:00.000 if not found. |
| `referenceId` | string | No | Unique reference ID for feedback tracking. |
| `subAccountId` | string | No | Tag request for billing purposes. |
| `extractLineItems` | boolean | No | Set true to return product line items in an array if found. |
| `ignoreMerchantName` | string | No | Merchant name to exclude from detection. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | object | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |
