📘
Defintions
For request and response defintions, visit Defintions For Validate Receipts

Example Request

cURL

curl --request POST \
     --url https://api.taggun.io/api/validation/v1/campaign/receipt-validation/file \
     --header 'accept: application/json' \
     --header 'apikey: 12345678abcd1234efgh567890abcdef' \
     --header 'content-type: multipart/form-data' \
     --form incognito=false \
     --form file='@example-image.jpeg' \
     --form campaignId=october-cola-24

Request Breakdown

file: The receipt image/PDF file (required)
- Maximum size: 20MB
- Supported formats: PDF, JPG, PNG, GIF, HEIC
campaignId: Unique identifier for the campaign settings (required)
incognito: Boolean flag to control receipt storage (optional)
- Default: false
ipAddress: End user's IP address (optional)
near: Geographic location for merchant search (optional)
- Format: "city, state, country"
referenceId: Custom reference for tracking (optional)
userId: Individual user identifier for fraud detection (optional)

Example JSON Responses

Successful Validation

{
  "successful": true,
  "failedValidations": [],
  "passedValidations": [
    "merchant_name_validated",
    "campaign_date_validated",
    "product_line_items_validated",
    "fraud_detection_unique_receipt_validated",
    "is_credit_card"
  ],
  "productLineItems": [
    {
      "name": "COCA COLA 12PK",
      "unitPrice": 6.99,
      "totalPrice": 13.98,
      "quantity": 2
    },
    {
      "name": "DORITOS NACHO",
      "unitPrice": 4.99,
      "totalPrice": 4.99,
      "quantity": 1
    }
  ],
  "matchedProductLineItems": [
    {
      "name": "COCA COLA 12PK",
      "unitPrice": 6.99,
      "totalPrice": 13.98,
      "quantity": 2
    }
  ],
  "date": "2024-10-15T14:22:31.000Z",
  "merchantName": "Walmart",
  "merchantAddress": "2700 S Shackleford Rd",
  "merchantCity": "Little Rock",
  "merchantPostalCode": "71823",
  "merchantState": "Arkansas",
  "merchantCountryCode": "US",
  "productCodes": [],
  "balanceAmount": null,
  "totalAmount": 23.97,
  "receiptNumber": "0021556789",
  "invoiceNumber": null,
  "trackingId": "T-20241015-8834567",
  "targetRotation": 0,
  "smartValidate": {
    "is_credit_card": true
  },
  "similarReceipts": [
    {
      "referenceId": null,
      "userId": null,
      "trackingId": "T-20250121-6165563",
      "similarityScore": 0.93
    }
  ],
  "tamperDetection": {
    "isTampered": false,
    "details": {
      "elaTampered": false,
      "metadataTampered": false,
      "copyPasteTampered": false,
      "whiteBoxTampered": false,
      "duplicates": [],
      "rectangles": [],
      "percentageBlocksTampered": 0.0399250936329588,
      "normalisedOverallMeanDiff": 0.4901666666666529,
      "clusterPercentage": 0.09255784865540963,
      "blocksTampered": 1599
    }
  },
}

Failed Validation

{
  "successful": false,
  "failedValidations": [
    "merchant_name_validated",
    "product_line_items_validated",
    "fraud_detection_unique_receipt_validated",
    "is_credit_card"
  ],
  "passedValidations": [
    "campaign_date_validated",
  ],
  "productLineItems": [
    {
      "name": "PEPSI 12PK",
      "unitPrice": 6.99,
      "totalPrice": 13.98,
      "quantity": 2
    },
    {
      "name": "MTN DEW 2L",
      "unitPrice": 2.50,
      "totalPrice": 5.00,
      "quantity": 2
    },
    {
      "name": "DORITOS NACHO",
      "unitPrice": 4.99,
      "totalPrice": 4.99,
      "quantity": 1
    }
  ],
  "matchedProductLineItems": [],
  "date": "2024-10-15T14:22:31.000Z",
  "merchantName": "Kroger",
  "merchantAddress": "3850 E Flamingo Rd",
  "merchantCity": "Las Vegas",
  "merchantPostalCode": "89121",
  "merchantState": "Nevada",
  "merchantCountryCode": "US",
  "productCodes": [],
  "balanceAmount": null,
  "totalAmount": 23.97,
  "receiptNumber": "0021556789",
  "invoiceNumber": null,
  "trackingId": "T-20241015-8834567",
  "targetRotation": 0,
  "smartValidate": {
    "is_credit_card": false
  },
  "similarReceipts": [
    {
      "referenceId": null,
      "userId": null,
      "trackingId": "T-20250121-6165563",
      "similarityScore": 0.93
    }
  ],
  "tamperDetection": {
    "isTampered": false,
    "details": {
      "elaTampered": false,
      "metadataTampered": false,
      "copyPasteTampered": false,
      "whiteBoxTampered": false,
      "duplicates": [],
      "rectangles": [],
      "percentageBlocksTampered": 0.0399250936329588,
      "normalisedOverallMeanDiff": 0.4901666666666529,
      "clusterPercentage": 0.09255784865540963,
      "blocksTampered": 1599
    }
  },
}

Response Breakdown

successful: Boolean indicating if the receipt passed all validations
failedValidations: Array of validation rules that failed
passedValidations: Array of validation rules that passed
productLineItems: Array of all products found on the receipt
matchedProductLineItems: Array of products that match campaign requirements
date: Receipt transaction date
merchantName: Name of the merchant
merchantAddress: Address of the merchant
merchantCity: City of the merchant
merchantPostalCode: Postal Code for the merchant address
merchantState: State of the merchant address
merchantCountryCode: Country code for the merchant
totalAmount: Total amount of the receipt
receiptNumber: Receipt identifier from merchant
invoiceNumber: Invoice number if available
trackingId: Unique identifier for the validation request
targetRotation: Image rotation value
similarReceipts: Fraud detection results relating to receipt similarity
tamperDetection: Fraud detection results relating to receipt tampering
digitalDetection: Is this receipt digital or physical

Status Codes

200: Successful validation
400: Bad request (invalid parameters or file)
403: Authentication error (invalid API key)
404: Campaign ID is not found