Alerts Integration - File Based

Integration Guide

Introduction

This guide outlines how to integrate Customer Alerts for new and activated offers. It includes alert scheduling preferences, data file formats, and post-delivery requirements such as event tracking. Partners must follow the outlined specifications to ensure accurate and timely delivery of customer-targeted offer notifications.

List of Contents

End to End Customer Alerts Flow
Alert File Specs
Integration Requirements Checklist
End to End Testing Plan
Support & Questions

End to End Customer Alerts Flow

Alert Package File Specification

The Alerts package includes two files:

AlertInfo.jsonl
OfferInfo.jsonl

All files use a JSONL format and CR-LF line breaks.

1. AlertInfo File

File name format:
CDLX_ALERTINFO_{date}_{timestamp}_1of1.jsonl
Example:
CDLX_ALERTINFO_20250617_1727977924_1of1.jsonl

Schema:

Field Name	Type	Max Length	Value	Required/Optional	Note
`alertType`	Unicode String	-	"N" or "A"	Required
`sourceCustomerId`	Unicode String	-		Required
`sourceAccountId`	Unicode String	-		Optional
`adId`	String	-		Required	Key represents adId
`rankings`	String array	-		Required
`token`	Unicode String	50		Optional
`totalRewardAmount`	Float64	-		Req. for existing banks. Opt. for V2

Example:

{
  "sourceCustomerId": "392d974d-6bd9-4ca9-ac52-8231342",
  "sourceAccountId": "24231-9c2f-484a-a072-26fe35960d94",
  "ads": {
    "1000000001": {
      "token": "VNQcONRvBXIYdNJ5JJXgLyCOXDijmnIzRRV24smQ2Bg",
      "alertType": "N"
    }
  },
  "ranking": {
    "all": [
      {"adId": "1000000001"},
      {"adId": "1000000002"},
      {"adId": "1000000003"},
      {"adId": "1000000004"},
      {"adId": "1000000005"},
      {"adId": "1000000006"}
    ]
  },
  "rewardsSummary": {
    "allTime": {
      "totalRewardAmount": 35.05
    }
  }
}

2. OfferInfo File

File name format:
CDLX_OFFERINFO_{date}_{timestamp}_1of1.jsonl
Example:
CDLX_OFFERINFO_20250617_1727977924_1of1.jsonl

Schema:

Field Name	Type	Max Length	Value	Required	Note
`adId`	String	-		Required	Key represents adId
`preMessage`	Unicode String	1000		Required
`postMessage`	Unicode Text	-		Required
`shortPreMessage`	Unicode String	50		Required
`merchantName`	Unicode String	100		Required
`endDate`	Datetime (ISO8601)	-		Required
`thankYouMessage`	Unicode Text	-		Required
`rewardType`	Unicode String	-	`PERCENT_AMOUNT_PURCHASE`, `FIXED_AMOUNT_PURCHASE`	Required
`adType`	Unicode String	-	`CASH_BACK_OFFER`	Required
`rewardAmount`	Unicode String	-		Required
`url`	Unicode String	-		Required	Logo image URL

Example:

{
  "ads": {
    "1000000001": {
      "adType": "CASH_BACK_OFFER",
      "merchantName": "Little Ceasars",
      "endDate": "2025-07-30 03:59:59Z",
      "reward": {
        "rewardType": "PERCENT_AMOUNT_PURCHASE",
        "rewardAmount": 5.0,
        "maxRewardAmount": 30.0
      },
      "assets": {
        "logo": {
          "type": "IMAGE_URL",
          "value": {
            "large": {
              "url": "https://publisher-cdn-us.cardlytics.com/images/non-annotated-logo/96b4939416014c47989b8331ddaf5067.jpg",
              "width": 627,
              "height": 627
            },
            "small": {
              "url": "https://publisher-cdn-us.cardlytics.com/images/non-annotated-logo/8f98ada322d648eebc44e599ed7ff9cc.jpg",
              "width": 128,
              "height": 128
            }
          }
        },
        "copy": {
          "type": "AD_COPY",
          "value": {
            "preMessage": "Earn 5% Cash on your Avis purchase!",
            "rewardCopy": "Earn 5% Cash when you spend with Avis. Maximum reward £30 Cash.",
            "postMessage": "Earn 5% ...",
            "thankYouMessage": "Thank you for your Avis purchase.",
            "shortPreMessage": "Earn 5% Cash!"
          }
        }
      }
    }
  }
}

Note: The file format is JSONL – each JSON object must be on a single line.

Integration Requirements Checklist

Offer Limits
- Alert Type N: Min 1 offer/email
- Alert Type A: Min 1 offer/email
Email Frequency
- N Offers: Weekly or Bi-weekly
- A Offers: Weekly or Bi-weekly (can differ from new offers)
Email Schedule
- Partners must define specific delivery day/time
- Files are delivered a few hours beforehand
- Activated type ads included in the same package
Email Latency Handling
- Alerts must be processed and emails generated within a few hours to maintain ranking relevance
Post-Email Event Tracking
- Track email opens
- Log activations post-redirect to bank experience
Expired Offer Experience
- If email is opened after expiration, redirect user to reward summary
Processing Timeline
- Alerts must be processed and emails sent within 24 hours

End to End Testing Plan

UAT Testing

Cardlytics sends test alert file via FIUAT environment
Publisher processes the file and sends sample email to [email protected]
Both teams join a call to validate impressions and activations

Production Testing (Optional)

Similar process, but executed in the production environment
Goal: Validate same flow with real data

Support & Questions

For questions or help with implementation, contact:

Email: [email protected]