Skip to content

Get Started with the Publisher v2.0 API

Steps

To get started with the Cardlytics Publisher API, you'll begin by making a POST call to start a session, which will enable you to retrieve a session token. Once you have that token, you'll be able to make API requests.

Two scopes are provided for you to work with: institution- or customer-level.

Typically, most banks will start with the customer-level scope. By selecting that scope, you can create a customer profile using the Data APIs. That is the beginning of your integration. Ad creation follows from that step forward.

Start a Session

You start a session by obtaining a session token and by making a POST call to this endpoint:

1
POST /v2/session/startSession
Note that a session token is an encoded JSON Web Token representing the institution and customer metadata relevant to a session.

By using that session token, you will be able to perform all API requests.

Institution-level scopes

You can use this type of token to interact with APIs broadly scoped to the level of an institution, in cases where no specific customer context is required.

To onboard customers into the Cardlytics system, financial institutions will typically use institutional scopes.

Customer-level scopes

Use this type of token to interact with APIs intended to be accessed on behalf of a customer. You'll need to get the sourceLevel Customer Id.

Details are described in the section on Start a Session & Get Scopes for API Access.

Create a Customer

If you're using the institutional scope to onboard into the Cardlytics system, you'll need to begin by using the Data API and making a POST call to create a customer.

Details about this API, including input parameters, output and examples are described in the section Create Customer.

The Data API section also describes POST and PUT calls for updating customer accounts, cards and customer information.

Important

Keep in mind that to create an ad, you have to create a customer first. In order for ads to serve, you have to onboard the customer through the Data API.

This first data flow lets you manage your customer accounts on a daily basis for updates, transactions and events.

Serve Offer Ads to Customers

Cardlytics makes a series of interfaces available that allow you to retrieve offers to display to the end customer. These APIs let you communicate and update the customer information needed to display targeted offer advertisements.

To start, you'll need to use getAds calls. But first, you'll first need to obtain the sessionToken, using the startSession POST call:

1
POST /v2/session/startSession
The sessionToken is required to be used in all subsequent requests you make.

Using the getAds call, you'll be able to retrieve matching and ranked ads for a specified customer.

The getAds call is described in detail in the Get Ads section.

Using Customer GET API calls, you'll be able to

  • retrive customer profiles that are externally exposed
  • get customer IDs corresponding to publisher's sourceCustomerid
  • get customer ad redemptions
  • get reward summaries
  • update customer profiles

Capture User Activity

Using the Events API, you'll be able to determine which actions your customers have performed in their accounts.

The Events API lets you capture user activity throughout a session. A variety of event types are available that can be used to model specific user interactions, such as interacting with an offer, denoting an impression from an Ad and exploring a history of offer redemptions.

When users log into events, you'll see what actions the users took -- for example, activating an offer.

See the section Create customer event for details.

Onboard New Customers

Whenever you wish to onboard new customers, you'll use the Data APIs which enable you to update information about the customers. Note that Data APIs are meant to be accessed server-side only.

Whenever a customer makes a transaction, you'll use the Data APIs to notify Cardlytics.