Get Ad Collection

Added in server version 3.3.

A collection is a grouping of ads that fit some theme or purpose. Basic collection metadata is included in the response to GET /ads. In order to get the ads belonging to a collection and any sub-collections, call this endpoint with the collection ID. Note that due to the nature of collections, ads may appear in a collection that do not otherwise get returned by a call to GET /ads.

GET /customers/<token>/collections/<collectionId>

Input Parameters

Path Param	Type	Required	Description
token	string	Required	The security token for the customer
collectionId	string	Required	The ID of the top-level collection to obtain

Query Param	Type	Required	Description
channelId	int	Required	Value from Channel list
locationId	int	Required	Value from Location list
status	int	Optional	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. This parameter is optional. If not specified, a default value of 15 is used (New,Served,Activated,Processing).
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
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 can return various HTTP status codes in addition to the standard Ad Server response codes:

Code	Details
200	Success. The response body is a Collection.
404	Collection not found (or at least not applicable to this customer). The response body is undefined.
500	Server Error. The response body is undefined.

---

Example

This example will return collection c122 for channelId 1 and locationId 2.

Request

GET api/v1/customers/C1FA3C38-1B28-4B54-A2F8-E577FFEEF9F5/collections/c122?channelId=1&locationId=2

Response

{
   "metadata": {
      "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"
      }
   },
   "ads" : [ /* Empty in this example, as all ads are part of sub-collections instead */ ],
   "subCollections" : [
      {
         "metadata" : {
            "id" : "111222333",
            "name" : "Last-Minute Gift Ideas",
            "tagLine" : "Stores open on holidays.",
            "bannerImage" : null /* Will be null for Sub-Collection */
         }
         "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"
               }
            ]
      },
      {
         "metadata" : {
            "id" : "F009A",
            "name" : "Holiday Gifts for Kids",
            "tagLine" : "Shop for the little ones this holiday season",
            "bannerImage" : null /* Will be null for Sub-Collection */
            }
            "ads" : [
               // Omitted for brevity
            ]
      }
   ],
   "categories":[
      {
         "name":"Shopping",
         "id":"Shopping-123",
         "adIds":[
            "10132748",
            "11244212"
         ]
      }
   ]
}