Validate Receipts

Endpoints

Input type	Endpoint
File upload	`POST https://api.taggun.io/api/validation/v1/campaign/receipt-validation/file`
URL	`POST https://api.taggun.io/api/validation/v1/campaign/receipt-validation/url`

Access

Receipt validation requires Campaign Validation access. See Setting Up Purchase Validation Campaigns.

File Upload Request

Send this endpoint as multipart/form-data.

Field	Type	Description	Required
`file`	file	Receipt file under 20 MB. Accepted file types: PDF, JPG, PNG, GIF, HEIC.	Yes
`campaignId`	string	The campaign ID to validate the receipt against. Maximum 50 characters.	Yes
`referenceId`	string	Your receipt reference. Use the same `referenceId` for resubmissions of the same receipt; submissions with the same `referenceId` are not picked up by duplicate checks. Maximum 50 characters.	No
`userId`	string	Your end-user identifier. This helps duplicate checks compare receipts for the same user. Maximum 50 characters.	No
`subAccountId`	string	Optional sub-account identifier for reporting or billing segmentation. Maximum 100 characters.	No
`incognito`	boolean	Set to `true` to avoid saving the receipt in storage. Defaults to `false`.	No
`ipAddress`	string	IPv4 or IPv6 address of the end user.	No
`near`	string	Geographic hint for merchant search, typically `city, state, country`.	No
`language`	string	Two-letter language hint. Leave empty for auto-detection.	No

URL Request

Send this endpoint as JSON.

Field	Type	Description	Required
`url`	string	Public HTTPS URL containing the receipt file. Only HTTPS URLs are accepted.	Yes
`headers`	object	Optional headers to forward while downloading the receipt URL.	No
`campaignId`	string	The campaign ID to validate the receipt against. Maximum 50 characters.	Yes
`referenceId`	string	Your receipt reference. Use the same `referenceId` for resubmissions of the same receipt; submissions with the same `referenceId` are not picked up by duplicate checks. Maximum 50 characters.	No
`userId`	string	Your end-user identifier. This helps duplicate checks compare receipts for the same user. Maximum 50 characters.	No
`subAccountId`	string	Optional sub-account identifier for reporting or billing segmentation. Maximum 100 characters.	No
`incognito`	boolean	Set to `true` to avoid saving the receipt in storage. Defaults to `false`.	No
`ipAddress`	string	IPv4 or IPv6 address of the end user.	No
`near`	string	Geographic hint for merchant search, typically `city, state, country`.	No
`language`	string	Two-letter language hint. Leave empty for auto-detection.	No

URL Request Example

{
  "url": "https://example.com/receipts/receipt-123.png",
  "campaignId": "coffee-june-2026",
  "referenceId": "receipt-123",
  "userId": "customer-456",
  "incognito": false
}

Response

The validation response contains the receipt extraction result and campaign validation result in one object.

Field	Type	Description
`successful`	boolean	`true` when all enabled validation checks passed. `false` when one or more checks failed.
`failedValidations`	string[]	Validation keys that failed.
`passedValidations`	string[]	Validation keys that passed.
`productLineItems`	object[]	Product line items found on the receipt when line item extraction is enabled for the campaign or account.
`matchedProductLineItems`	object[]	Product line items that matched the campaign rules.
`date`	string \| null	Receipt transaction date, when detected.
`merchantName`	string \| null	Merchant name, when detected.
`merchantAddress`	string \| null	Merchant address, when detected.
`merchantCity`	string \| null	Merchant city, when detected.
`merchantPostalCode`	string \| null	Merchant postal code, when detected.
`merchantState`	string \| null	Merchant state, when detected.
`merchantCountryCode`	string \| null	Merchant country code, when detected.
`productCodes`	string[]	Product codes detected or validated for the campaign.
`balanceAmount`	number \| null	Balance owing detected on the receipt.
`smartValidate`	object	Smart Validate prompt results, when Smart Validate prompts are configured.
`totalAmount`	number \| null	Receipt total amount, when detected.
`currencyCode`	string \| null	Currency code for the total amount, when detected.
`receiptNumber`	string \| null	Receipt number, when detected.
`invoiceNumber`	string \| null	Invoice number, when detected.
`similarReceipts`	object[]	Similar receipt matches when similarity checking is enabled.
`tamperDetection`	object \| null	Tamper detection result when tamper detection is enabled.
`digitalDetection`	object \| null	Digital receipt detection result when digital detection is enabled.
`trackingId`	string	Taggun tracking ID for this validation request.

Product Line Item Object

Field	Type	Description
`name`	string	Product or service name.
`unitPrice`	number	Unit price, when detected.
`totalPrice`	number	Total line price, when detected.
`quantity`	number	Quantity, when detected.

Validation Keys

These keys can appear in failedValidations or passedValidations, depending on the campaign settings and receipt result.

Key	Meaning
`date_validated`	Receipt date was checked against the campaign date window.
`merchant_name_validated`	Merchant name was checked against the campaign merchant rules.
`product_code_validated`	Product codes were checked against the campaign product code rules.
`product_line_items_validated`	Product line items were checked against the campaign line item rules.
`balance_amount_validated`	Balance owing was checked against the campaign maximum balance owing.
`fraud_detection_unique_receipt_validated`	Receipt similarity or duplicate checking was evaluated.
`fraud_detection_genuine_receipt_validated`	Tamper detection was evaluated.
`fraud_detection_complete_receipt_validated`	Receipt completeness was evaluated for non-receipt or incomplete receipt detection.
Smart Validate output key	If a Smart Validate prompt has `skip` set to `false`, its output key can appear as a validation key. For example, `is_credit_card`.

Example Response

{
  "successful": false,
  "failedValidations": ["product_code_validated"],
  "passedValidations": ["date_validated", "merchant_name_validated"],
  "productLineItems": [
    {
      "name": "Coffee Beans",
      "unitPrice": 12.5,
      "totalPrice": 25,
      "quantity": 2
    }
  ],
  "matchedProductLineItems": [],
  "date": "2026-06-12T00:00:00.000Z",
  "merchantName": "Fresh Market",
  "merchantAddress": "1 Market Street",
  "merchantCity": "Auckland",
  "merchantPostalCode": "1010",
  "merchantState": null,
  "merchantCountryCode": "NZ",
  "productCodes": [],
  "balanceAmount": 0,
  "smartValidate": {
    "is_credit_card": true
  },
  "totalAmount": 25,
  "currencyCode": "NZD",
  "receiptNumber": "R12345",
  "invoiceNumber": null,
  "similarReceipts": [],
  "tamperDetection": null,
  "digitalDetection": null,
  "trackingId": "7f64b9e0-0000-0000-0000-000000000000"
}

Managing Settings

To retrieve, update, list, or delete campaign settings, see Manage Campaign Settings.