📘

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
  },
  "fraudDetection": {
    "similarityScore": 0.12,
    "passed": true
  }
}

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
  },
  "fraudDetection": {
    "similarityScore": 0.12,
    "passed": true
  }
}

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
  • fraudDetection: Fraud detection results including similarity score

Status Codes

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