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:

Property	Type	Required	Description
channel	Channel	Yes	Filters results by ad channel.
sections	Section[]	No	Array of sections (FI-specific). Examples: Regular location, "Featured Local Offers" in a side bar panel, Bottom of the page. If not included, all sections will be returned.
categoryIds	string[]	No	Value from Ad Category list.
curationIds	string[]	No	Value from predefined value for a specific campaign list.
activationStates	AdActivationState[]	No	Limit ads by activation state. If not supplied then NEW, SERVED and ACTIVATED ads will all be returned.
visibilityStates	AdVisibilityState[]	No	Default is to return only ads with visibilityStatus of VISIBLE. This field can be used to also return PARKED ads.
redemptionStates	AdRedemptionState[]	No	Use to limit ads returned to ones that are redeemed, for example.
maxAdLimit	int	No	The maximum number of ads to be returned. Values: a positive number (1 to int. max value). If not set, then return all available ads in all states (including expired). Pagination may be used if the returned ads exceed the amount requested.
returnMetadata	boolean	No	If supplied, assets such as logo images and AdCopy will be returned.
includeExpiredAds	boolean	No	If enabled, ended ads will be included in the results. Note: The default lookback period is 120 days.

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.

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.