Validating Receipts

Once your campaign settings exist, submit each receipt against the campaign by file upload or URL. Validation is synchronous — the pass/fail result and the validation response fields documented below return in the same HTTP response, so there are no webhooks to build. Typical timings are covered in Performance & Response Times.

Endpoints

API console: Validate Receipts

Availability

📘

Availability: Receipt validation is included on the Advanced plan and above. Enable Campaign Validation in your account Feature Settings when it is available on your plan. See Plans & Feature Access and Setting Up Validation Campaigns.

File Upload Request

Send as multipart/form-data.

curl --request POST \
     --url https://api.taggun.io/api/validation/v1/campaign/receipt-validation/file \
     --header 'accept: application/json' \
     --header 'apikey: YOUR_API_KEY' \
     --header 'content-type: multipart/form-data' \
     --form file='@receipt.jpg' \
     --form campaignId=coffee-june-2026 \
     --form userId=customer-456

URL Request

Send as JSON. The URL must use HTTPS and be reachable by Taggun. HTTP URLs and localhost, loopback, link-local, or private-network hosts are rejected. Use headers when the HTTPS resource requires authorised access.

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

Response

The response contains the campaign validation result and the selected extracted fields in the table below.

Properties whose value is undefined may be absent. Where the schema permits null, handle it unless endpoint-specific semantics are documented.

The inner fraud-result shapes differ between validation and verbose extraction. Compare the exact paths in Data Fields That Taggun Extracts.

Product line item object

Validation Keys

These keys appear in passedValidations or failedValidations depending on the campaign settings and the receipt result. They are the machine-readable contract your integration should branch on.

When campaign settings use balanceOwing.skip: true, balanceAmount can still be returned, but balance_amount_validated is not added to passedValidations or failedValidations and does not affect successful. The balanceOwing schema still requires max; see Campaign Settings Reference.

Worked Example

A receipt fails the product-code check, passes the date and merchant checks, and returns the approved generic credit-card-payment SmartValidate illustration:

{
  "successful": false,
  "failedValidations": ["product_code_validated"],
  "passedValidations": ["date_validated", "merchant_name_validated", "is_credit_card"],
  "productLineItems": [
    {
      "name": "Coffee Beans",
      "unitPrice": 12.5,
      "totalPrice": 25,
      "quantity": 2
    }
  ],
  "matchedProductLineItems": [],
  "date": "2026-06-12T00:00:00.000Z",
  "merchantName": "Fresh Market",
  "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"
}

Reading it: successful is false because product_code_validated failed — no qualifying product codes were found — even though the date, merchant, and generic is_credit_card checks passed. The SmartValidate example shows the response shape and does not describe a particular customer's production use case. Your workflow may use actionable, non-fraud failures to request a correction or resubmission. Keep fraud-related validation keys server-side; use neutral customer messaging and route suspicious submissions to your review or rejection workflow.

When similarity checking is enabled and a near-duplicate exists, similarReceipts contains the matched receipts with their trackingId, your original referenceId/userId where available, and a similarityScore. similarityScore is a numeric similarity signal; 1.0 is the maximum returned score, not proof of identity or authenticity. See Duplicate & Similarity Detection for score interpretation.

Status codes

For general error handling, see Error Handling & Status Codes.

For an unknown campaignId, both file and URL requests return 400 with { "statusCode": 400, "error": "Bad Request", "message": "The Campaign ID is not found" }. A deleted campaign is expected to fail, but its exact Receipt Validation status and body remain unconfirmed and must not be inferred from the unknown-campaign branch.

Managing Settings

To retrieve, update, list, or delete campaign settings, see Managing Campaigns.

Need something not covered here? Contact [email protected] — see Contacting Support.