Alerts Integration - File Based

Abstract

This Integration Guide provides comprehensive instructions for partners to implement Customer Alerts for new and activated offers. It details the alert notification flow, file format specifications, integration requirements, and testing procedures to ensure accurate, timely, and trackable delivery of offers to customers. The guide aims to standardize the integration process, ensuring alert notifications are generated, processed, and tracked according to agreed-upon business rules and technical standards.

Summary

The document describes the end-to-end process for integrating Customer Alerts, covering:

• Alert Flow: Outlines the delivery mechanism for sending alerts to customers about new and activated offers, including scheduling and event tracking requirements.
• File Specifications: Defines the structure and required fields for two JSONL files (AlertInfo.jsonl and OfferInfo.jsonl) used to package and transmit alert and offer data. Schema tables and detailed examples are provided for both files.
• Integration Requirements: Lists mandatory criteria such as offer limits per email, allowable email frequencies, scheduling guidelines, post-delivery tracking (e.g., email opens and offer activations), handling of expired offers, and strict processing timelines (within 24 hours).
• Testing Plan: Specifies both UAT and optional Production testing steps to validate integration, including procedures for file delivery, email generation, and cross-team validation.
• Support: Provides a contact email for technical and integration-related queries.

Overall, the guide establishes a clear and standardized approach for partners to deliver targeted offer alerts, ensuring data format consistency, operational timeliness, and effective event tracking.

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:

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:

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

• Multiple Alert Types

  • If a package includes multiple types of alerts (e.g., N - New, X - Expiring, A - Activated), the Activated Alerts should be sent in a separate email.

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]](mailto:[email protected]

© 2025 Cardlytics