Skip to main content

Read time 3 minutes

DOCUMENT CONTROL

#Introduction

This document defines the required technical interface for searching and viewing offer listings provided in a Rest API web service transferring data in JSON format.

What are listings

Listings are our partners and offers that are available to reward consumers through promotional websites.

Partners are organisations we contract with to provide offers.

Locations are the physical or online locations where offers from a partner can be redeemed. Offers are the individual rewards that are available to consumers to enjoy.

The hierarchy is one partner can have one or more locations, and each location can have one or more offers.

image.png

Classifications​

We have many thousands of offers and organise these with classifications to make them manageable. An offer can only be associated with a single Reward classification. The classification hierarchy is:

image.png

Where TLC's standard classification structure is not appropriate for a particular campaign the offers can be organised into Groups. This is a tier structure of just groups and subgroups.

Tags​

Are used to filter offers across multiple classifications. For example a soccer lesson and a music streaming full into different classifications but could be tagged as activities for 'teenagers'.

Location information​

Locations can be at a physical address, an online location or delivery. Physical locations include full address information to facilitate filtering by region or city and include longitude/latitude to allow geolocation filtering.

Environments

The application is hosted on Azure and access to the API requires a Webkey which is unique to each campaign website. Communications are only allowed over HTTPS. The Listings API is read only.

Swagger​

Use the Swagger links for details of endpoints and example responses.

PRD environment​

https://api.tlcmarketing.com/listings/swagger/index.html

UAT environment​

https://uat.api.tlcmarketing.com/listings/swagger/index.html

PRD includes test and live areas for managing campaigns; both areas share the same listings. As this API is read only, this normally used for developing a campaign website. UAT is typically used for testing new features on the Cosmos platform.

API Explained

The offer data is maintained on our CRM platform and published to the Listings API in near real time.

Listings should be filtered to display on a website only those offers of interest to the end user.

Filtering can be done via classifications, tags or location information. Classifications filters by experience type, tags for grouping rewards for a target audience and location for geographic filtering.

The Swagger documentation lists all endpoints and gives examples of request sand responses.

Mandatory fields​

For each API call it is mandatory to include the Webkey, version, country and language.

Webkey - unique GUID for each campaign website. This is auto-generated by the Cosmos platform when a manager creates a campaign. Version - API version (current version is 1) Country - ISO 3166-1 alpha-2 (2 digits) Language - ISO 639 set 1 (2 digits)