Abstract

The API - Integration Guide is a comprehensive resource for implementing and integrating the Cardlytics Rewards platform. The guide outlines the technical and procedural steps required to enable businesses to deliver personalized offers and rewards to their customers through Cardlytics' platform. It provides details on account setup, user journeys, API integrations, security requirements, and strategies for maximizing customer engagement with targeted promotional offers. The document also describes post-implementation testing, privacy controls, and advanced functionalities such as real-time reward notifications.

Summary

The API - Integration Guide is structured to assist developers and organizations in integrating into their systems. Below are the key components and highlights of the document:

1. Step-by-Step Integration Process:

   • Initial account setup by CDLX.
   • User journey steps, including obtaining session tokens, linking customer accounts via the Link SDK, fetching offers, activating them, and handling reward notifications.
   • Testing and validation using the Cardlytics Testing Tool.

2. Authentication:

   • Secure POST requests to obtain session tokens.
   • Token caching, expiration handling, and error responses.

3. Link SDK:

   • Methods for managing account linking (e.g., checking status, starting and deleting links).
   • Integration via script tags and API calls.

4. Offers and Rewards Management:

   • API endpoint for fetching ads tailored to specific customers or fallback offers for unlinked accounts.
   • Detailed request and response structures, including optional filters such as category, activation state, visibility state, and more.
   • Explanation of ad lifecycle states (e.g., activation, visibility, redemption).

5. Client Event Logging:

   • Logging user activity and interactions with offers, including impressions, activations, and session-level events.

6. Welcome Basket Offers:

   • Placeholder offers for new Cardlytics Rewards Platform users until sufficient transaction data is collected for personalized recommendations.

7. Reward Notifications:

   • S3 File Transfer and Real-Time Messaging (RTM) Webhooks to immediately relay Redemption events as they occur..

8. Category Mapping:

   • A detailed mapping of customer-facing categories to internal classifications for better offer targeting.

9. Security Requirements:

   • Guidelines for securing sensitive data, including obfuscation of the x-source-customer-id using the HMAC-SHA-256 algorithm.

This guide provides detailed technical instructions, sample payloads, and response formats to ensure smooth integration. It also emphasizes security, scalability, and the ability to dynamically adapt to customer preferences and offer performance.

Step-by-Step Implementation

One-Time Account Setup

Step 1: CDLX will set up your account.

User Journey

Step 2: Get session token.
Step 3: A - Check existing Linking
B - Enable users to link their card (using CDLX Link SDK).
Step 4: Make your first call to get offers.
Step 5: Activating an offer (&send other user interactions with the offer)
Step 6: You earned a reward! Getting redemption signal.

Step 7: Use Cardlytics Testing Tool to validate your implementation.

• https://selfserve-testing.cardlytics.com
  Step 8: Implement User privacy controls.

1. Allowing users to unlink their card.
2. Allow users to delete an account.
3. Allow users to request for information.

Starting Session

Get Session Token (Authentication)

POST /v2/session/startSession

To authenticate and begin your session, you will need to provide the following credentials in a secure POST request:

Request Headers:

• Content-Type: application/json
• x-source-customer-id: string
  
  

Note: Refer to the Security Requirements section on suggestions to secure the x-source-customer-id. Also for customers who have not linked a card to the Cardlytics Rewards platform, you can use no-user-available as the x-source-customer-id to receive a valid token.

Request Payload:

• clientId: Your unique clientId provided by Cardlytics.
• secret: A secure secret key shared with you by Cardlytics.

Request Payload Sample:

{
  "clientId": "String",
  "secret": "String"
}

Response

Upon successful authentication, the API will provide a bearer token that you can use to access our services.

Token Details:

• Bearer Token Validity: The token is valid for 15 minutes from the time of issue.

• This Bear Token should be cached for subsequent API calls.

• Only request a new token if the previous one has expired.

Errors and Handling Expired Tokens:

• Providing an invalid clientId or clientSecret the API will return a 500 Internal Server Error

• If your token expires, all subsequent API requests will return a 401 Unauthorized response indicating that the session is no longer valid.

• To continue accessing the API, you must request a new token using the same token generation endpoint (POST /v2/session/startSession).

Link SDK

Overview

The Link SDK provides several methods to manage customers’ account linking between your application and financial institutions through our platform. Below you'll find detailed explanations of how to use each method.

Methods

1. getAccountLinkStatus

   • Description: Retrieves the account linking status. {#exceptions:}

   • Parameters:

     • cdlxSessionToken (string): A valid CDLX session token. {#exceptions:}

     • x-source-customer-id (string): A valid source customer Id. Should be the same hashed id used during /startSession

   • Returns: CardlyticsCustomerProfile

2. startAccountLink

   • Description:

     Initiates the account linking process. The process varies depending on the selected link provider but aims to store an access token in the CDLX backend.

   • Parameters:

     • cdlxSessionToken (string): A valid CDLX session token.

     • linkProvider (string): Must be one of the supported linking providers. Currently supports "PLAID_HOSTED". {#exceptions:}

     • redirect_uri (string): The URL to redirect to after a successful link.

     • x-source-customer-id (string): A valid source customer Id. Should be the same hashed id used during /startSession

   • Returns: void

   • Exceptions:

     • Invalid linkProvider value.

     • Invalid session token value (401).

     • Other errors from CDLX APIs.

3. deleteAccountLink

   • Description: Deletes an existing account link.

   • Parameters:

     • cdlxSessionToken (string): A valid CDLX session token.

     • accountLinkId (string): The ID of the account link.

     • x-source-customer-id (string): A valid source customer Id.

   • Returns: A Promise that resolves to a boolean indicating success or failure.

   • Exceptions: Rejects under error cases.

Script Tag

To include the Cardlytics Link SDK in your project, use the following script tag:

<script src="/linking-sdk/v1/cardlytics-linking-sdk.js"></script>

Make a call to get offers (GetAds)

POST /v2/ads/getAds

This API returns ads that are suitable for a specific customer.

Request Headers:

• Content-Type: application/json
• Authorization: Bearer
• x-source-customer-id: string
• x-mock-data: true

For customers who have not linked a card to the Cardlytics Rewards platform, you can use no-user-available as the x-source-customer-id to receive non-target offers..

Note: x-mock-data is only required to return dummy data for testing and development. Refer to the Security Requirements section on suggestions to secure the x-source-customer-id.

Request Payload Attributes:

Ad Assets

Ads may include optional objects such as creatives in the response.

Progression of Ad States

Ads progress through states of activation, visibility, and redemption. Each state has specific transitions as detailed below:

• AdActivationState: NEW → SERVED → ACTIVATED
• AdRedemptionState: FULLY_REDEEMED (applies to FIs with RTM enabled)
• AdVisibilityState: Typically VISIBLE by default, but can include PARKED state.

Ad Serve Token

Each returned ad includes a unique AdServeToken which encodes metadata about the ad and changes with each fetch. It expires after one hour.

Channel

Defines the channel through which an ad was delivered, like Email, SMS, MMS, or various online and mobile banking channels.

Ranking

The Ad Rankings object is dynamically generated based on the scenarios outlined below.

Important:
Currently, only the Default Ad Rankings response is supported. Future support for additional ranking types is planned.

In the GetAds response, the rankings section is structured as a map. At a minimum, it includes a default "all" key, which provides a complete list of adIds. This default ranking can be used across any section of the user interface.

{
    "all": ["adId-123", "adId-456", "adId-789"]
}

Section

Sections define specific areas where ads can appear, like Email, SMS, Transaction, Dashboard, and others, each tailored to a specific part of the user interface or customer interaction.

Important:
Currently, only the Default Ad Rankings response is supported. Future support for additional ranking types is planned.
In the GetAds response, the rankings section is structured as a map. At a minimum, it includes a default "all" key, which provides a complete list of adIds. This default ranking can be used across any section of the user interface.

Category Group

Defines hierarchical groupings of ads by category, useful for organizing ads into related groups like Dining or Shopping.

Request Payload:

{
    "channel": "Email",
    "sections": ["Landing", "Summary"],
    "maxAdLimit": 50,
    "visibilityStates": ["VISIBLE"]
}

Response:

• 200 OK: Indicates successful retrieval of ads.
• 401 Unauthorized: Indicates that token is invalid
• 500 Internal Server Error: Indicates a failure in fetching ads.

Response Payload:

{
  "requestId": "8de221a2-efa9-40ef-9cdb-53475d4e1ac8",
  "ads": {
    "1000056632": {
      "adType": "CASH_BACK_OFFER",
      "adServeToken": "CiQ4ZGUyMjFhMi1lZmE5LTQwZWYtOWNkYi01MzQ3NWQ0ZTFhYzgQ9O3XkKoyGgoxMDAwMDU2NjMyIgVFbWFpbA==",
      "startDate": "2024-06-13T23:00:00Z",
      "endDate": "2024-11-30T22:59:59Z",
      "merchantName": "CDLX - US Test Account 1",
      "reward": {
        "rewardType": "PERCENT_AMOUNT_PURCHASE",
        "rewardAmount": 5.0,
        "maxRewardAmount": 30.0,
        "isMultiRedemption": false,
        "purchaseRequirement": {
          "minSpendAmount": 0.2,
          "purchaseChannels": ["Online", "InStore"],
          "merchantUrlLinkClickRequired": false
        },
        "activationModel": "ACTIVATABLE"
      },
      "activationState": "NEW",
      "visibilityState": "PARKED",
      "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 CDLX - US Test Account 1 purchase!",
            "rewardCopy": "Earn 5% Cash on your CDLX - US Test Account 1 purchase, with a £30 Cash maximum.",
            "postMessage": "Earn 5% Cash on your CDLX - US Test Account 1 purchase, with a £30 Cash maximum.<br/><br/>Offer expires 30 Nov 2024. Offer valid one time only.",
            "thankYouMessage": "Thank you for your CDLX - US Test Account 1 purchase.",
            "headline": "£5 Bonus Rewards",
            "shortPreMessage": "Earn 5% Cash!",
            "termsAndConditions": "Offer expires 30 Nov 2024. Offer valid one time only."
          }
        }
      },
      "isAffiliateMarketing": false
    },
  "rankings": {
    "all": [
      "1000056632",
      "1000058746"
    ]
  },
  "categories": {
    "1000058746": {
      "name": "Other",
      "id": "6"
    },
    "1000056632": {
      "name": "Food",
      "id": "2"
    }
  },
  "storeLocations": null
}

Note: We request that the logo images are displayed in the following way:

• “assets.logo.small” images are used in the offer list or tile.
• “assets.logo.large” images are used in the offer details.

Send Client Event

POST /v2/events/clientEvent

This endpoint is used to capture user activity throughout a session by logging various client events. It allows modeling specific user interactions such as interacting with an offer and recording an ad impression.

Request Headers:

• Content-Type: application/json
• Authorization: Bearer
• x-source-customer-id: string
• x-mock-data: true

Note: x-mock-data is only required to return dummy data for testing and development purposes. Refer to the Security Requirements section on suggestions to secure the x-source-customer-id.

Here is the documentation formatted for better readability:

Request Attributes:

ClientEventMessage

LogEnrollment (Send Client Event)

Request Payload

{
    "clientEvents": [
        {
            "clientEventId": "12395199-1565-4565-bf99-3f94ee505d12",
            "clientEventType": "SessionAction",
            "clientEvent": "LogEnrollment",
            "clientEventTimestamp": "2024-10-01T07:00:00Z",
         }
    ]
}

Response

{
    "requestId": "380052b4-3a64-4952-b640-ba696eb9f44b"
}

Activating an offer (Send Client Event)

Request Payload

{
    "clientEvents": [
        {
            "clientEventId": "12395199-1565-4565-bf99-3f94ee505d12",
            "clientEventType": "AdInteraction",
            "clientEvent": "ActivateOffer",
            "clientEventTimestamp": "2024-10-01T07:00:00Z",
            "clientEventMetadata": {
                "serveToken": "CiQ3MGU5ZjQzMy0xMjQxLTRlZTctOTZlZi02ZWM4MDQwZjg3MzgQqoTjo6syGgoxMDAwMDYyNzQwIgVFbWFpbA==",
                "section": "Dashboard",
                "channel": "OLB",
            }
        }
    ]
}

Response

{
    "requestId": "380052b4-3a64-4952-b640-ba696eb9f44b"
}

Send an Impression (Send Client Event)

Request Payload

{
    "clientEvents": [
        {
            "clientEventId": "12395199-1565-4565-bf99-3f94ee505d12",
            "clientEventType": "AdImpression",
            "clientEvent": "AdViewableImpression",
            "clientEventTimestamp": "2024-10-01T07:00:00Z",
            "clientEventMetadata": {
                "serveToken": "CiQ3MGU5ZjQzMy0xMjQxLTRlZTctOTZlZi02ZWM4MDQwZjg3MzgQqoTjo6syGgoxMDAwMDYyNzQwIgVFbWFpbA==",
                "section": "Dashboard",
                "channel": "OLB",
            }
        }
    ]
}

Response

{
    "requestId": "380052b4-3a64-4952-b640-ba696eb9f44b"
}

Response:

• 200 OK: Indicates successful retrieval of ads.
• 401 Unauthorized: Indicates that token is invalid
• 500 Internal Server Error: Indicates a failure in submitting clientEvent.

Welcome Basket Offers

Welcome Offers are introductory promotions provided to customers who are new to the Cardlytics Rewards program. These offers give customers immediate value and engagement opportunities while the system gathers data and completes the offer targeting process. Once sufficient transaction history is collected, customers will begin receiving personalized offers tailored to their shopping behaviors.

In order to provide Welcome Offers to new customers, you must send “no-user-available” as the x-source-customer-id header value for the /startSession API call.

Reward Notification

File Transfer

• Publisher will set up S3 File Transfer as detailed here: https://platform.cardlytics.com/publisher-integrations/docs/s3-publisher-file-transfer.

Webhook

• Cardlytics will also provide a Real-Time Messaging (RTM) Webhook to immediately relay Redemption events as they occur. For more details, visit https://platform.cardlytics.com/publisher-integrations/docs/real-time-messaging.

Sample Reward File

{
  "redemptionId": "517713527",
  "sourceOrganizationId": "AFFINA",
  "sourcePortfolioId": "AFFINA-Standard",
  "redemptionDate": "2025-03-08T00:00:00.000Z",
  "sourceAccountId": "c5f0be70-bb01-4da1-a01c-8d63b1425633",
  "sourceCustomerId": "7554b88f-167d-4aed-aaff-8bd01ba8fdcb",
  "sourceTransactionIds": [
    "b59977fa-7b66-4fde-88c6-89acec5d57cf"
  ],
  "adId": "1000080445",
  "rewardId": "84359",
  "rewardAmount": "359",
  "rewardCurrencyType": "USD",
  "isOfferFullyRedeemed": true,
  "isReversal": false,
  "rewardSettlementProcessDate": "2025-03-11T16:48:52.261Z"
}

Data Specs

CardlyticsCustomerProfile

interface CardlyticsCustomerProfile {
  accountLinks: [
    null // No linked account or linked account deleted 
    | LinkingInitiated  // Initiate linking process
    | LinkingInProgress // Server proccessing Linked Account
	]

  accounts: [
    {
      accountId: string;
      status: string;
      cardType: string;
      last4: string;
    }
  ];
}

Note: If no account is linked or been deleted, the response will be 204 No Content.

Types

ClientEventType

ClientEvent

ClientEventAdMetadata

Channel

Section

Security Requirements

x-source-customer-id

It is important that the x-source-customer-id obfuscated before passing in the header of the API calls. We suggest using the HMAC-SHA-256 algorithm to insure security.

For example: https://www.devglan.com/online-tools/hmac-sha256-online

1. One-Time Account Setup

• CDLX will provide your clientId and secret.
• Set these as environment variables in the backend.

2. Step-by-Step User Flow

2.1. Start Session (Obtain Token)

• POST /v2/session/startSession with:

  • Headers:
    • x-source-customer-id (HMAC-SHA-256 hashed or "no-user-available" if not logged in)
    • Content-Type: application/json
  • Body:
    • clientId, secret

• Cache the token for 15 minutes.

2.2. Check/Start Account Linking

• Use Cardlytics Link SDK (via script tag on frontend).
• Methods:
  • getAccountLinkStatus
  • startAccountLink
  • deleteAccountLink

2.3. Fetch Offers

• POST /v2/ads/getAds
  • Headers:
    • Authorization: Bearer <token>
    • x-source-customer-id
    • Content-Type: application/json
  • Body (example):
    JSON

    {
      "channel": "Email",
      "sections": ["Landing", "Summary"],
      "maxAdLimit": 50,
      "visibilityStates": ["VISIBLE"]
    }
    

2.4. Activate Offer (Send Client Event)

• POST /v2/events/clientEvent
  • Log actions like ActivateOffer and AdViewableImpression.

2.5. Reward Notification

• Listen for webhook events

3. Security

• Use HMAC-SHA-256 to obfuscate x-source-customer-id:
  • Example (Node.js):
    JavaScript

    const crypto = require('crypto');
    function hashCustomerId(customerId, secret) {
      return crypto.createHmac('sha256', secret).update(customerId).digest('hex');
    }
    

4. Advanced: Real-Time Messaging/Webhook

• The MVP includes a stub endpoint for webhook reward notifications.
• For production, set up as described in CDLX docs.

5. References

• Cardlytics Link SDK
• Cardlytics Testing Tool