Get Ads

The primary endpoint for retrieving ads to display.

GET /customers/<token>/ads

Input Parameters

Path Param	Type	Required	Description
token	string	Required	The security token for the customer

Query Param	Type	Required	Description
channelId	int	Required	Value from Channel list
locationId	int	Required	Value from Location list
status	int	Required	A bitwise concatenation of the various AdStatus desired. For example if ads with status 2 or 16 are desired, the value specified here will be 18. For improved readability, this parameter also supports a comma-separated list of AdStatus values. For example, &status=7 is equivalent to &status=New,Served,Activated.
includeParked	boolean	Optional	If true, only parked ads are returned. If false, only ads which have not been parked are returned. If not specified, ads in both states are returned.
maxAdLimit	int	Optional	the maximum number of the ads are returned. If not set, then return all available ads. Should be positive number (1 to int. max value)
enableSuppression	boolean	Optional	If this parameter is true, customer offer pairs which are marked as suppressible will be excluded from the ads response, if false, all ads will be returned, Default as false.

---

Output

This endpoint returns an AdList object with the matching ads for the customer.

Property	Type	Description
ads	Map with adId (string) keys and Ad objects as values	Data for ads, keyed by adId to make referencing from ranking section simpler
rankings	Map keyed by type of ranking returned	Indicator for how to rank ads returned. If no sections are used, then use “ALL” section id
assets	Creative[]	Array of metadata for creatives. This is an optional response object that can be disabled through ad-metadata and creative-metadata caching integration.
storeLocations	Map keyed by AdId, values: array of StoreLocation objects

---

Example

This example will return ads for channelId 1 and locationId 2 which are not parked and which are in either the redeemed (16), activated (4), or served (2) status.

Request

GET api/v1/customers/C1FA3C38-1B28-4B54-A2F8-E577FFEEF9F5/ads?channelId=1&locationId=2&includeParked=false&status=22&maxAdLimit=50&enableSuppression=false

Response

{
   "ads":[
    {
        "adId": "10132748",
        "status": 2,
        "creatives": [
            {
                "creativeId": "10132748-c",
                "shortPreMessage": "Get 10% back at Bob's",
                "thankYouMessage": "Thank you for shopping! You got $24.46 back!",
                "headline" : "10% back",
                "images": {
                    "logo": {
                        "url": "https://images.cardlytics.com/ads/logo/10132748.png",
                        "text": "Bob's Logo"
                    },
                    "heroImage": {
                        "url": "https://images.cardlytics.com/ads/hero/warehouse.png",
                        "text": "Warehouse Storefront"
                    }
                },
                "links" : {
                    "callToActionLink": {
                        "url": "http://example.com/callToActionLink/WestRock%0D/?ot=testFI&xt=gF49Db7mM7CA%2BRSOOVBYwwYtmXqWcYpU9JSU%2BfgreARy1PeUKsES18FA8nrIplgPQqo01Z2%2BZ4PpzJLLNZkYBquYsvYVo%2FZYFfNftz8Q2u6VgCCBurtYJ%2BxUWS%2BV915aKb5sCf09xJ4n7YiykWyHViyWAxzko7qp9QWlsaFxRhQ%3D",
                        "text": "Shop Now"
                    }
                },
                "beacons": {
                    "preMessageImpression": "http://example.com/foo",
                    "postMessageImpression": "http://example.com/bar"
                },
                "impressionToken": "CIy66gQoATAB",
                "preMessage": "Get 10% back on any purchase of $5 or more at Bob's Warehouse.",
                "postMessage": "Time and inventory is limited. Maximum of $30 back. Minimum transaction of $5 required. Terms and conditions apply. <a class='cardlytics_anchor_styling cardlytics_anchor_target' target='_blank' href='http://example.com' aria-label='here'>Please click here </a> to find a location near you."
            }
        ],
        "isParked": true,
        "categoryId": 3,
        "daysRemaining": 28,
        "endDate": "2019-03-22T09:39:25",
        "isPercentageOffer": true,
        "merchantName": "Bob's Warehouse",
        "offerAmount": 10.0,
        "maxRewardAmount": 30.0,
        "minSpendAmount": 5.0,
        "adType": 101,
        "isMappable": true,
        "redemptions": [
            {
                "redemptionId": 992745,
                "accountId": 25895672459,
                "adId": 2784221,
                "amount": 34.12,
                "date": "2019-03-21T12:58:34",
                "isMyReward": false,
                "paidAccountId": 388836454,
                "redeemingTransactionAmount": 34.46,
                "transactionId": 929994552,
                "rewardSettlementRunDate": "2019-03-21T23:59:50"
            }
        ],
        "tags": [
            {
                "key": "purchase-channel",
                "value": "In-Store"
            }
        ],
        "purchaseChannels": [
            "InStore"
        ],
        "purchaseRequirement" : {
            "requirementType" : "MustPurchase",
            "purchaseTypes" : [
                "Fuel"
            ]
        },
        "offerPromotions": [
            "FlashDeal"
        ],
        "position": 4,
        "activatedDate": "2021-10-26T19:11:27Z"
    }
   ],
   "categories":[
      {
         "name":"Shopping",
         "id":"9823782",
         "subcategories":[

         ],
         "adIds":[
            "10132748"
         ]
      }
   ],
   "collections" : [
      {
         "id" : "c122",
         "name" : "Holiday Gift Shopping",
         "tagLine" : "Gift yourself while gifting others.",
         "bannerImage" : {
            "url":"https://images.cardlytics.com/collections/banner/c122.png",
            "text":"wrapped presents"
         }
      },
      {
         "id" : "999888",
         "name" : "Local Businesses",
         "tagLine" : "Shop local and save!",
         "bannerImage" : {
            "url":"https://images.cardlytics.com/collections/banner/999888.png",
            "text":"storefront"
         }
      }
   ]
}