Skip to content

Get ads

Get Ads for a given Customer which are appropriate for a particular Ad Channel and Inputs.

1
POST /v2/ads/getAds

Request

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, then 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. If not set, then return all available ads in all states (including expired). If set, and the returned ads exceeds the amount requested, pagination will be used.

Values: a positive number (1 to int. max value)
returnMetadata boolean No If supplied, assets such as logo images and AdCopy will be returned
includeExpiredAds boolean No If set, ended ads will also be returned

Response

Property Type Description
ads Map<string, Ad> A Map of ads data, keyed by adId
rankings AdRankings See the AdRankings page for more information.
categories Map<string, CategoryGroup> A Map of ad categories, keyed by adId. See the CategoryGroup page for more information.

Ad Rankings

The ordering for a given section can be found in the rankings object of the response.

The ranking object will always have a catch-all ranking type titled all which provides a general, overall ranking of ads.

In the future, Cardlytics will support other rankings by section, category and curation.

Ad Assets

Ads and creatives are available as optional objects in the response.

Progression of Ad States

Ads have three stateful properties:

Activation State

Activation state transitions in the following order.

  1. NEW
  2. SERVED
  3. ACTIVATED

These states are mutually exclusive to each other.

Redemption State

Once an ad is activated, it can be redeemed. AdRedemptionState can progress through these states:

  1. PROCESSING
  2. FULLY_REDEEMED

Info

The PROCESSING redemption state only applies for FIs which have enabled RTM. In this case, an auth transaction is present that would redeem this offer once processed.

Visibility State

AdVisibilityState can be either VISIBLE (default) or PARKED, which respectively indicate whether the Ad should be visible to, or hidden from the customer.

Ad State Progression Diagram

Ad state progression diagram

Ad Serve Token

Each returned ad will include a unique AdServeToken. This token encodes metadata about where an ad was displayed and must therefore be included in events sent to Cardlytics servers. This is to avoid having to return multiple AdServeTokens for a single ad and having the client pick up the correct one. This also means that a serve tokens ** should not be cached** since they will change each time Ads are returned by Cardlytics.

Serves, activations and other client events will be properly validation to ensure attributes such as channel and ** display location** are included correctly.

Examples

Request a max of 50 VISIBLE Ads for the "EMAIL" advertising channel

1
POST /v2/ads/getAds

1
2
3
4
5
6
{
    "channel": "Email",
    "sections": ["Landing", "Summary"],
    "maxAdLimit": 50,
    "visibilityStates": ["VISIBLE"]
}

Response

1
200 OK


 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
{
  "adType": "CASH_BACK_OFFER",
  "adServeToken": "CiQxNDczMzRkZC0xYmIzLTQ3ZDUtOGE0My0zYTM0ZmY0MTQ3OWUQ7LWhxu4xGgoxMDAwMDUyNzI0IgVFbWFpbA==",
  "startDate": "2024-04-05T00:00:00Z",
  "endDate": "2024-04-19T23:59:59Z",
  "activationDate": "2024-04-14T13:42:18Z",
  "merchantName": "Costa Coffee",
  "isAffiliateMarketing": true,
  "reward": {
    "rewardType": "PERCENT_AMOUNT_PURCHASE",
    "rewardAmount": 15,
    "maxRewardAmount": 1,
    "isMultiRedemption": false,
    "purchaseRequirement": {
      "minSpendAmount": 0.2,
      "purchaseChannels": [
        "InStore",
        "Online"
      ],
      "merchantUrlLinkClickRequired": true
    },
    "activationModel": "AUTO_ACTIVATED",
  },
  "activationState": "ACTIVATED",
  "visibilityState": "VISIBLE",
  "assets": {
    "logo": {
      "type": "IMAGE_URL",
      "value": {
        "large": {
          "url": "https://publisher-cdn-eu.cardlytics.com/images/non-annotated-logo/de9483e8b755498bab4cd609c5d9fc04.jpg",
          "width": 627,
          "height": 627
        },
        "small": {
          "url": "https://publisher-cdn-eu.cardlytics.com/images/non-annotated-logo/3c2b4fe030834325abb3991a6894da7f.jpg",
          "width": 128,
          "height": 128
        }
      }
    },
    "copy": {
      "type": "AD_COPY",
      "value": {
        "preMessage": "Earn 15% Cash on your Costa Coffee purchase!",
        "rewardCopy": "Internal Monzo Test. One time only.",
        "postMessage": "Internal Monzo Test. One time only.<br/><br/>Offer expires 19 Apr 2024.",
        "thankYouMessage": "Thank you for your Costa Coffee purchase.",
        "headline": "15% Cash",
        "shortPreMessage": "Earn 15% Cash!",
        "termsAndConditions": "Offer expires 19 Apr 2024."
      }
    }
  }
}
A more detailed response of ads in all states.