Last updated: 21 July 2016

Introduction

Welcome to the Xerts REST API.

This API is designed to work with the Xerts app and also allow 3rd party developers access to the Xerts coupon system.

Definitions

Term	Meaning
Vendor	The Advertising organisation who creates offers to be distributed as coupons at one or more sites.
Offer	A template created by a vendor that can be assigned to one or multiple sites for registration by Xerts POS users
Coupon	An instance of an Offer which is allocated to a user’s device
Member	A member is a user in the system. Can be one of ‘admin’, 'appProvider’, 'siteOwner’, 'vendorOwner’.
Site	A physical location of an Xerts device - owners can have multiple sites.
App Provider	A user who provides an application (web/iOS/Android) to access the API with an API Key
Site Owner	A Client User who has one or multiple sites (physical sales locations).
Vendor Owner	A User that has control over a vendor organisation and it’s offers.

User Flow

When a user walks to a location with his/her app, they are presented with a variety of coupon registration methods at the point of sale (POS). When using one of these registration methods, a web address with a special unique identifier is relayed to the user’s device. The user’s device then receives access to a range of 'coupons’ which are redeemable on the spot.

Staff at the site can manually redeem the coupon with an interface behind the counter. This is done via a 5-digit redeem code shown on the user’s device. The communication and validation process may change in the future, however this is the current way.

Data model

The following provides an example of the way the various data objects are related in the Xerts API:

Coupons

Testing whether a coupon has been redeemed

The JSON Response for a coupon contains a redeemedOn property that is defined if a coupon has been redeemed. If a coupon has not been redeemed then this property will not be present.

Test whether a coupon has been redeemed:

if (coupon.redeemedOn) {
  // coupon has already been redeemed
}

Coupon Expiration

Coupon expiration can be defined in a few different ways through the SiteOffer. The relevant fields are:

Field	Type	Description
instanceExpiresOn	Date	The date the campaign (site offer) ends. No coupons will be issued or redeemed after this date
couponExpiresAfterDays	number	The coupon will expire X days after it was issued, or on `siteOffer.instanceExpiresOn`, whichever is sooner

A siteOffer that only has the instanceExpiresOn property will result in coupons that all expire on this date.
A siteOffer that only has the couponExpiresAfterDays property will result in coupons that are valid for that number of days after being issued. New coupons can be issued forever
A siteOffer with both fields set will cause the coupon expiry to be the earlist date based on instanceExpiresOn and couponExpiresAfterDays

A coupon’s expiration date is stored in the coupon.expiresOn field. The value in this field is generated by the server when the coupon is first issued. Client applications can use this field directly, and should not calculate the coupon expiration date themselves.

Triggers

A trigger’s type is defined by which of these properties it contains. For a location based trigger would look like this:

{
  "id": "1234",
  "triggerLocation": {
    "lat": 37,
    "lng": 20 
  },
  "triggerRadius": 30
}

Where as a time based trigger would only have the triggerOn property:

{
  "id": "1234",
  "triggerOn": "2016-05-30T03:14:18.000Z"
}

A Site offer can contain zero or more Triggers which affect the behaviour of a coupon on the user’s device. A coupon should become active (able to be redeemed) once all triggers have fired. Note that the server does not store any information about whether triggers have fired or not; this happens entirely on the user’s device. Rather, the server defines what triggers should be required before a coupon becomes active. If there are no triggers, the coupon should activate immediately.

Triggers have the following properties:

Property	Type	Description
id	string	A unique identifier for the Trigger
triggerOn	date	The trigger will fire on this date
triggerAfterMinutes	number	The trigger will fire X minutes after the coupon was issued
triggerLocation	geopoint	The trigger will fire when the user visits the specified location
triggerLocationRadius	number	A radius, in metres, used in conjunction with triggerLocation. Specifies a distance from the location on which to trigger the coupon.
triggerLocationPoly	geopoint[]	An array of points that define a polygon. The trigger will fire when the user enters the area specified by the polygon
firesAfter	object	This trigger will not be evaluated until after firesAfter has fired. Can be used to define a sequence of events that must be met before a coupon activates.
timeAfterTrigger	number	This trigger will fire X minutes after the previous trigger

Example: Activate coupon when the user visits the Adelaide CBD

A trigger for entering the Adelaide CBD.

{
  "id": "1234",
  "triggerLocationPoly": [
    {
      "lat": -34.920983,
      "lng": 138.610821
    },
    {
      "lat": -34.922214,
      "lng": 138.58728
    }
    {
      "lat": -34.936235,
      "lng": 138.588455
    },
    {
      "lat": -34.934719,
      "lng": 138.617743
    }

  ]
}

The Adelaide CBD is defined by the four corners of East, West, North, and South Terraces. This area can be defined using the triggerLocationPoly field of a trigger:

Chaining triggers

A sequence of triggers for a coupon that activates two hours after a user visits a location would look like this:

[
  {
    "id": "1234",
    "triggerLocation": {
      "lat": 37,
      "lng": 20 
    },
    "triggerRadius": 30
  },
  {
    "id": "4567",
    "timeAfterTrigger": 120
  }
]

Interesting sequences of events can be created by chaining triggers together. For example, suppose a coupon should activate 2 hours after the user visits a location. This would be accomplished by chaining a location trigger to a timeAfter trigger.

Authentication

Xerts API requests require a API-Key. To get an API-Key for Xerts, email xerts@xped.com.

Include the API-Key in every request as a HTTP header.

Like so:

curl -X POST https://api.xerts.io/api/ \
  -H "API-Key: '<Insert API Key here>'"

The above shell command returns the following response:

{
  "started": "2016-06-07T09:02:35.527Z",
  "uptime": 55190.337
}

Client Action Endpoints

Create Coupons for Device at Site

Use this command:

curl -X POST https://api.xerts.io/api/siteOffers/:siteId/device/:deviceId \
  -H "API-Key: '<Insert API Key here>'"

The above command returns JSON structured like this:

{
  "results": [
  {
    "id": "26db3760-5844-11e6-8af5-9d711fe30147",
    "redeemCode": "Y2BMA",
    "redeemedOn": "2016-08-02T01:28:08.000Z",
    "expiresOn": "2016-08-09T00:00:41.447Z",
    "deviceId": "cf570da0-456e-42b8-a3ac-fa6062e9a955",
    "createdOn": "2016-08-02T00:00:41.430Z",
    "updatedOn": "2016-08-02T01:28:08.073Z",
    "siteOfferId": "26d25dc0-5844-11e6-8af5-9d711fe30147",
    "offer": {
      "id": "26ce1800-5844-11e6-8af5-9d711fe30147",
      "title": "Makaylaberg",
      "description": "Perferendis unde et vero. Minus rerum vel eveniet id nihil velit et culpa. Tempore dolores alias ratione iste quod libero aut reiciendis expedita. Voluptatibus dolores et dignissimos ut neque. Odio ipsum ex fugiat provident ut et. Voluptas illum unde voluptatibus illum sit.\n \rQuia corporis itaque qui sunt eum. Soluta qui sint id eos voluptate voluptate delectus qui voluptatum. Dolores rem corrupti. In illo sunt illum quis aut corrupti recusandae. Occaecati aperiam et eos iusto. Atque libero assumenda voluptatem odio necessitatibus ut soluta qui iste.\n \rQui enim illo. Odio molestias minima aperiam iure exercitationem quia consequatur tenetur. Et voluptatem molestias repellat ea dolorum ut voluptatem.",
      "styleBorderColor": "green",
      "styleBackgroundColor": "magenta",
      "featureImage": "string",
      "url": null,
      "vendorId": "267a52b0-5844-11e6-8af5-9d711fe30147"
    },
    "redemptionSite": {
      "id": "26ca4770-5844-11e6-8af5-9d711fe30147",
      "title": "Bodeborough",
      "address": "62776 Kerluke Ville",
      "gps": {
        "lng": 102.2364,
        "lat": -35.4664
      },
      "adminId": "26a0c670-5844-11e6-8af5-9d711fe30147"
    },
    "triggers": []
  },
  {
    "id": "f6444060-5843-11e6-8864-b9214aa1b815",
    "redeemCode": "INLZH",
    "expiresOn": "2016-08-08T23:59:19.927Z",
    "deviceId": "7702f09e-425d-4370-b893-3940f3de182a",
    "createdOn": "2016-08-01T23:59:19.910Z",
    "updatedOn": "2016-08-01T23:59:22.121Z",
    "siteOfferId": "f63fac80-5843-11e6-8864-b9214aa1b815",
    "offer": {
      "id": "f63b8dd0-5843-11e6-8864-b9214aa1b815",
      "title": "Abernathymouth",
      "description": "Maiores vel rerum est. Quia cum ut omnis consequatur et quibusdam quidem. Vel accusamus id eius et nobis repudiandae. Id doloribus natus velit eum.\n \rNihil dolores totam rerum provident aut voluptatibus qui odio. Officia hic voluptas. Asperiores voluptas et perspiciatis voluptates amet laudantium voluptatibus et. Rerum ullam fuga qui. Quam tenetur veniam dolores qui exercitationem eos quod expedita.\n \rNostrum labore omnis ut recusandae minima. Ullam sint totam nulla quibusdam in enim quo. Omnis officia vel ea sequi tempora. Itaque sint in.",
      "styleBorderColor": "salmon",
      "styleBackgroundColor": "azure",
      "featureImage": "string",
      "url": null,
      "vendorId": "f435f9d0-5843-11e6-8864-b9214aa1b815"
    },
    "redemptionSite": {
      "id": "f6376f20-5843-11e6-8864-b9214aa1b815",
      "title": "Port Margarettview",
      "address": "878 Herman Estate",
      "gps": {
        "lng": -80.1553,
        "lat": 75.6046
      },
      "adminId": "f533bac0-5843-11e6-8864-b9214aa1b815"
    },
    "triggers": []
  }
  ]
}

If the siteId does not exist, JSON error is returned:

{
  "error": {
    "status": 404,
    "message": "Didnt return anything."
  }
}

This generates coupons for a device at a specific site. Use :siteId for the Site ID and :deviceId for the Device ID. If the device ID does not already exist in the sytem, it will be created.

HTTP Request

POST https://api.xerts.io/api/siteOffers/:siteId/device/:deviceId

Body Parameters

Parameter	Required	Type	ID	Description

Get Coupons for Device (all or for site)

Use this command to get every coupon for device:

curl -X GET https://api.xerts.io/api/coupons/site/all/device/:deviceId \
  -H "API-Key: '<Insert API Key here>'"

Use this command to get only site-specific coupons for device:

curl -X GET https://api.xerts.io/api/coupons/site/:siteId/devices/:deviceId \
  -H "API-Key: '<Insert API Key here>'"

The above commands return JSON structured like this:

{
  "results": [
  {
    "id": "26db3760-5844-11e6-8af5-9d711fe30147",
    "redeemCode": "Y2BMA",
    "redeemedOn": "2016-08-02T01:28:08.000Z",
    "expiresOn": "2016-08-09T00:00:41.447Z",
    "deviceId": "cf570da0-456e-42b8-a3ac-fa6062e9a955",
    "createdOn": "2016-08-02T00:00:41.430Z",
    "updatedOn": "2016-08-02T01:28:08.073Z",
    "siteOfferId": "26d25dc0-5844-11e6-8af5-9d711fe30147",
    "offer": {
      "id": "26ce1800-5844-11e6-8af5-9d711fe30147",
      "title": "Makaylaberg",
      "description": "Perferendis unde et vero. Minus rerum vel eveniet id nihil velit et culpa. Tempore dolores alias ratione iste quod libero aut reiciendis expedita. Voluptatibus dolores et dignissimos ut neque. Odio ipsum ex fugiat provident ut et. Voluptas illum unde voluptatibus illum sit.\n \rQuia corporis itaque qui sunt eum. Soluta qui sint id eos voluptate voluptate delectus qui voluptatum. Dolores rem corrupti. In illo sunt illum quis aut corrupti recusandae. Occaecati aperiam et eos iusto. Atque libero assumenda voluptatem odio necessitatibus ut soluta qui iste.\n \rQui enim illo. Odio molestias minima aperiam iure exercitationem quia consequatur tenetur. Et voluptatem molestias repellat ea dolorum ut voluptatem.",
      "styleBorderColor": "green",
      "styleBackgroundColor": "magenta",
      "featureImage": "string",
      "url": null,
      "vendorId": "267a52b0-5844-11e6-8af5-9d711fe30147"
    },
    "redemptionSite": {
      "id": "26ca4770-5844-11e6-8af5-9d711fe30147",
      "title": "Bodeborough",
      "address": "62776 Kerluke Ville",
      "gps": {
        "lng": 102.2364,
        "lat": -35.4664
      },
      "adminId": "26a0c670-5844-11e6-8af5-9d711fe30147"
    },
    "triggers": []
  },
  {
    "id": "f6444060-5843-11e6-8864-b9214aa1b815",
    "redeemCode": "INLZH",
    "expiresOn": "2016-08-08T23:59:19.927Z",
    "deviceId": "7702f09e-425d-4370-b893-3940f3de182a",
    "createdOn": "2016-08-01T23:59:19.910Z",
    "updatedOn": "2016-08-01T23:59:22.121Z",
    "siteOfferId": "f63fac80-5843-11e6-8864-b9214aa1b815",
    "offer": {
      "id": "f63b8dd0-5843-11e6-8864-b9214aa1b815",
      "title": "Abernathymouth",
      "description": "Maiores vel rerum est. Quia cum ut omnis consequatur et quibusdam quidem. Vel accusamus id eius et nobis repudiandae. Id doloribus natus velit eum.\n \rNihil dolores totam rerum provident aut voluptatibus qui odio. Officia hic voluptas. Asperiores voluptas et perspiciatis voluptates amet laudantium voluptatibus et. Rerum ullam fuga qui. Quam tenetur veniam dolores qui exercitationem eos quod expedita.\n \rNostrum labore omnis ut recusandae minima. Ullam sint totam nulla quibusdam in enim quo. Omnis officia vel ea sequi tempora. Itaque sint in.",
      "styleBorderColor": "salmon",
      "styleBackgroundColor": "azure",
      "featureImage": "string",
      "url": null,
      "vendorId": "f435f9d0-5843-11e6-8864-b9214aa1b815"
    },
    "redemptionSite": {
      "id": "f6376f20-5843-11e6-8864-b9214aa1b815",
      "title": "Port Margarettview",
      "address": "878 Herman Estate",
      "gps": {
        "lng": -80.1553,
        "lat": 75.6046
      },
      "adminId": "f533bac0-5843-11e6-8864-b9214aa1b815"
    },
    "triggers": []
  }
  ]
}

This gets all existing coupons for the device. Be sure to use the all, otherwise you should use a siteId to get all site-specific coupons for that device.

HTTP Request

GET https://api.xerts.io/api/coupons/sites/all/devices/:deviceId

GET https://api.xerts.io/api/coupons/sites/:siteId/devices/:deviceId

Body Parameters

Parameter	Required	Type	ID	Description
None.

Activate a coupon for redemption

Coupon Redemption is handled by the site administrator. The client app should make a request to activate a coupon for redemption. For example, when the user clicks a Redeem button on the client app.

This causes the coupon to be displayed in a list of recently activated coupons for the site on the site admin interface. Operators can then simply click a redeem button without having to enter the redemption code.

If this request cannot be made (for example, loss of network connection), then the coupon can still be redeemed. However, the site operator will need to manually enter the redemption code and verify the coupon.

Activate a coupon for redemption

curl -X PUT \ https://api.xerts.io/api/coupons/sites/:siteId/activate/:code \
  -H "API-Key: '<Insert API Key here>'"

The above commands return JSON structured like this:

{
  "results": {
    "id": 19,
    "redeemCode": "B5Z7E",
    "redeemedOn": "2016-05-30T03:14:18.000Z",
    "deviceId": "60ef5b5e-7229-4758-8184-da613de405a9",
    "siteOfferId": "0583f660-2612-11e6-9206-cd9a11b559ba"
  }
}

If the coupon is already redeemed, the following JSON response will boomerang:

{
  "error": {
    "status": 404,
    "message": "Coupon not found honey. Check if it's already been redeemed."
  }
}

This endpoint redeems a coupon with redeem code :code at site with id siteId. If the coupon has already been redeemed, an error 404 will be returned.

HTTP Request

PUT https://api.xerts.io/api/coupons/sites/:siteId/devices/:deviceId/redeem/:code

Body Parameters

Parameter	Required	Type	ID	Description
None.

Management Endpoints

Create a User

Use this command:

curl -X POST https://api.xerts.io/api/members -d \
  "{ \
    'phone': 'string', \
    'firstName': 'string', \
    'lastName': 'string', \
    'username': 'string', \
    'password': 'string', \
    'email': 'string', \
    'emailVerified': bool, \
    'status': 'string', \
    'appProvider': true, \
    'vendorOwner': false, \
    'siteOwner': false \
  }" \
  -H "API-Key: '<Insert API Key here>'"

The above command returns JSON structured like this:

{
  "id": "d426a9c0-22fe-11e6-96a3-bdf7343ebeee",
  "phone": "023584620",
  "firstName": "Micky",
  "lastName": "Blue",
  "username": "mblurulez",
  "email": "bluezey@gmail.com",
  "status": "active",
  "appProvider": true,
  "vendorOwner": false,
  "siteOwner": false
}

This endpoint creates a user.

HTTP Request

POST https://api.xerts.io/api/members

Body Parameters

Parameter	Required	Type	ID	Description
username	N	String	N	Conforms to User model
email	Y	String	N	Conforms to User model
password	Y	String	N	Conforms to User model
phone	N	String	N	User contact Phone
vendorOwner	N	String	N	user type is vendor owner - can create new vendors
siteOwner	N	String	N	user type is site owner - can create sites and manage them
appProvider	N	String	N	usually an organisation developing an app for 3rd party - appProviders receive API Keys that allow their 'App’ to access teh API.
firstName	N	String	N	First Name
lastName	N	String	N	Last Name

Log a user in

This endpoint logs a user in.

Use this command:

curl -X POST https://api.xerts.io/api/members/login -d \
  "{ \
    'email': 'string', \
    'password': 'string'
  }" \

The above command returns JSON structured like this:

{
  "id": "QvS1bIt6WkhA6rCZXpUDnFnzszaU0WZBW0RWNtEMCqGZ4iOZ2Mc9EFKJsTmt1czU",
  "ttl": 1209600,
  "created": "2016-05-26T05:17:55.231Z",
  "userId": "d426a9c0-22fe-11e6-96a3-bdf7343ebeee"
}

The id is an authentication token. Use this token in request headers: { Authentication: QvS1bIt6WkhA6rCZXpUDnFnzszaU0WZBW0RWNtEMCqGZ4iOZ2Mc9EFKJsTmt1czU }

HTTP Request

POST https://api.xerts.io/api/members/login

Body Parameters

Parameter	Required	Type	ID	Description
email	Y	String	N	user’s email address
password	Y	String	N	users’s password

Create a Vendor for User

Use this command:

curl -X POST https://api.xerts.io/api/members/:id/vendors -d
  "{ \
    'vendorName': 'string', \
    'headOfficeAddress1': 'string', \
    'headOfficeAddress2': 'string', \
    'headOfficeZipcode': 'string', \
    'headOfficeCity': 'string', \
    'headOfficeCountry': 'string', \
    'headOfficePhone': 'string', \
    'description': 'string' \
  }" \
  -H "Authorization: <Authorization key>" \
  -H "API-Key: '<Insert API Key here>'"

The above command returns JSON structured like this:

{
  "id": "9e3b8410-27a0-11e6-82bf-27ccd35b24dd",
  "vendorName": "Kihn, Lang and Kub",
  "headOfficeAddress1": "762 Alexane Key",
  "headOfficeAddress2": "Apt. 160",
  "headOfficeZipcode": "66893",
  "headOfficeCity": "Rubietown",
  "headOfficeCountry": "Argentina",
  "headOfficePhone": "1-653-021-8946 x487",
  "description": "Sint tenetur consequatur qui aperiam debitis recusandae ea nihil blanditiis. Eos fugiat rerum mollitia ea. In iusto ut exercitationem ducimus. Fugiat quis quis sit et aliquid ut modi id.",
  "ownerId": "9e1118b0-27a0-11e6-82bf-27ccd35b24dd"
}

This endpoint creates a vendor for user.

HTTP Request

POST https://api.xerts.io/api/members/:id/vendors

Body Parameters

Parameter	Required	Type	ID	Description
vendorName	Y	String	N	Name of the organisation
headOfficeAddress1	Y	String	N	Address First line
headOfficeAddress2	N	String	N	Address Second line
headOfficeAddress3	N	String	N	Address Third line
headOfficeZipcode	Y	String	N	Zipcode
headOfficeCity	Y	String	N	City / Province
headOfficeCountry	Y	String	N	Country
headOfficePhone	N	String	N	Contact Phone number
description	Y	String	N	Address First line

Create a Site for a Vendor

Use this command:

curl -X POST https://api.xerts.io/api/vendors/:id/sites -d \
  "{ \
    'title': 'string', \
    'address': 'string', \
    'gps': { \
      'lat': 'float', \
      'lng': 'float' \
    } \
  }" \
  -H "API-Key: '<Insert API Key here>'"

The above command returns JSON structured like this:

{
  "id": "d426a9c0-22fe-11e6-96a3-bdf7343ebeee",
  "title": "Whal Burger NY East",
  "address": "34 22nd East. St.",
  "gps": {
    "lat": "101.890",
    "lng": "22.456"
  }
}

This endpoint creates a site for a vendor.

HTTP Request

POST https://api.xerts.io/api/vendors/:id/sites

Body Parameters

Parameter	Required	Type	ID	Description
title	Y	String	N	Site title (Branch/Franchise Location)
address	N	String	N	If an address is available, add it here
gps	N	String	N	If GPS position is available, add it here { lat: 'float’, long: 'float’ }

Add a Site Admin

Use this command:

curl -H "Authorization: <ACCESS_TOKEN>" -X PUT \ https://api.xerts.io/api/sites/:id/admin -d \
  "{ \
    'adminId': 'string' \
  }" \
  -H "API-Key: '<Insert API Key here>'"

The above command returns JSON structured like this:

{
  "results": {
    "id": "74651f00-22e8-11e6-953c-b1e050c9762d",
    "title": "Danielhaven",
    "address": "069 Jayne Vista",
    "gps": {
      "lat": 11.78,
      "lng": 83.0154
    },
    "vendorId": "7461eab0-22e8-11e6-953c-b1e050c9762d",
    "adminId": "d426a9c0-22fe-11e6-96a3-bdf7343ebeee"
  }
}

This endpoint adds a user to a site. User must be owned by the vendor that owns the site.

HTTP Request

POST https://api.xerts.io/api/sites/:id/admin

Body Parameters

Parameter	Required	Type	ID	Description
id	Y	String	Y	The ID of the site (embed in URL)
adminId	Y	String	Y	The ID of the user you want to set as admin of this site.

Create an Offer for a Vendor

Use this command:

curl -H "Authorization: <ACCESS_TOKEN>" -X POST \ https://api.xerts.io/api/vendors/:id/offers -d \
  "{ \
    'title': 'string', \
    'description': 'string', \
    'styleBorderColor': 'string', \
    'styleBackgroundColor': 'string', \
    'featureImage': 'URL-String' \
    'url': 'URL String' \
  }" \
  -H "API-Key: '<Insert API Key here>'"

The above command returns JSON structured like this:

{
  "id": "58b52db0-22e6-11e6-b8de-1b32b0fa4bd3",
  "title": "West Bufordview",
  "description": "Illo aliquid eos velit quod. Eveniet facere vitae officia. Aliquam veniam iste. Adipisci laboriosam rerum eum ad ut molestiae hic. Doloremque et sit beatae reiciendis nisi reprehenderit eum ut ea.\n \rId voluptas quia non sunt distinctio. Molestiae alias maxime veritatis blanditiis vitae voluptas vitae non maiores. Nam cupiditate voluptatibus est aut. Qui repudiandae reiciendis in cumque dicta amet ipsum.\n \rConsequatur et magnam. Dicta corporis quasi sint distinctio neque et quis et. Quo nemo iste eveniet quibusdam suscipit velit sed.",
  "styleBorderColor": "mint green",
  "styleBackgroundColor": "blue",
  "featureImage": "http://lorempixel.com/720/300/",
  "url": "http://www.example.com/offer",
  "vendorId": "5887b510-22e6-11e6-b8de-1b32b0fa4bd3"
}

This endpoint adds an offer for a vendor. Vendor must be owned by logged in user to work.

HTTP Request

POST https://api.xerts.io/api/vendor/:id/offers

Body Parameters

Parameter	Required	Type	ID	Description
title	Y	String	N	The site title
description	Y	String	N	Description of the site
styleBorderColor	Y	String	N	Border color styling
styleBackgroundColor	Y	String	N	Background color styling
featureImage	Y	String	N	Feature image for offer/coupon.
url	N	String	N	A URL for more information about the offer.
vendorId	Y	String	N	Owning vendor ID

Add an Offer to a Site

Use this command:

curl -H "Authorization: <ACCESS_TOKEN>" -X PUT \ https://api.xerts.io/api/offers/:id/sites/rel/:siteId -d \
  "{ \
    'instanceCost': 0.12, \
    'instanceLimit': 1000, \
    'instanceIssues': 3, \
    'totalCost': 120.00, \
    'instanceExpiresOn': '2017-05-26' \
  }" \
  -H "API-Key: '<Insert API Key here>'"

The above command returns JSON structured like this:

{
  "id": "748ec710-22e8-11e6-953c-b1e050c9762d",
  "instanceCost": 0.12,
  "instanceLimit": 1010,
  "instanceIssues": 1,
  "totalCost": 121.19999999999999,
  "instanceExpiresOn": "2017-05-26",
  "offerId": "748d1960-22e8-11e6-953c-b1e050c9762d",
  "siteId": "74651f00-22e8-11e6-953c-b1e050c9762d"
}

This endpoint assigns an offer to a site. If an offer is assigned to a site, clients can receive coupons based on those offers at their sites.

HTTP Request

PUT https://api.xerts.io/api/offers/:id/sites/rel/:siteId

Body Parameters

Parameter	Required	Type	ID	Description
instanceCost	Y	String	N	Cost per coupon
instanceLimit	Y	String	N	Maximum number of coupons to be issued
instanceIssues	Y	String	N	Number of coupons been issued
totalCost	Y	String	N	Total cost of campaign, given instanceCost and instanceLimit
instanceStartIssueOn	N	String	N	Time of first coupon issue
instanceLastIssueOn	N	String	N	Last time a coupon was issued
instanceExpiresOn	N	String	N	expiry date of offer at site

Get all coupons for a Site

Use this command to get only site-specific coupons for device:

curl -X POST https://api.xerts.io/api/sites/:siteId/coupons \
  -H "API-Key: '<Insert API Key here>'"

The above commands return JSON structured like this:

{
  "results": [
    {
      "id": 36,
      "redeemCode": "D068Y",
      "redeemedOn": "2016-05-30T06:54:36.000Z",
      "deviceId": "656e6b6d-6a69-4e48-b66c-b917d3561ef0",
      "siteOfferId": "5f750170-2633-11e6-a10f-a197e0a3258d",
      "offer": {
        "id": "5f732cb0-2633-11e6-a10f-a197e0a3258d",
        "title": "North Lucileton",
        "description": "Quia aut unde quas consequuntur qui corporis maxime. Eum expedita consequatur dolore veritatis doloribus ullam perspiciatis. Aliquam aut sint atque. Quas autem officia et tempore sit reprehenderit veritatis dignissimos quidem.\n \rIpsa excepturi numquam nemo. Distinctio ad non est quo atque consequatur. Provident nihil accusantium qui. Necessitatibus soluta suscipit nobis commodi nihil deserunt sint corrupti recusandae. Itaque et et voluptas perspiciatis impedit quas quae aut.\n \rCommodi aspernatur provident odio beatae temporibus nam libero. Nihil enim voluptatum nostrum unde. Itaque velit consequuntur. Voluptas atque doloribus eligendi. Qui minima velit voluptates.",
        "styleBorderColor": "mint green",
        "styleBackgroundColor": "azure",
        "featureImage": "http://lorempixel.com/720/300/",
        "vendorId": "5f440660-2633-11e6-a10f-a197e0a3258d"
      }
    }
  ]
}

This endpoint gets all coupons for site with siteId.

HTTP Request

GET https://api.xerts.io/api/sites/:siteId/coupons

Body Parameters

Parameter	Required	Type	ID	Description
None.

Reporting Endpoints

Get Coupon Reports for vendors

Use this command:

curl -X GET https://api.xerts.io/api/reporting/vendors/:id?from=28-07-2016&to=14-08-2016 \
  -H "API-Key: '<Insert API Key here>'"
  -H "Authorization: '<Insert Authorization here>'"

The above command returns JSON structured like this:

{
    "totalCouponsIssued": 30,
    "totalCouponsRedeemed": 10,
    "sites": [
        "58c4fd10-31e5-11e6-n0a9-d3c289387tga" : {
      "id": "58c4fd10-31e5-11e6-n0a9-d3c289387tga",
            "label": "O\\'connel Street Bakery",
            "activeOffers": 1,
            "couponsIssued": 15,
            "couponsRedeemed": 2
        },
        "68c5fd11-31e5-11e6-n0a9-d3c289387tga" : {
      "id": "68c5fd11-31e5-11e6-n0a9-d3c289387tga",
            "label": "Main North Road On the Run",
            "activeOffers": 1,
            "couponsIssued": 10,
            "couponsRedeemed": 5
        },
        "78d5fd14-31e6-11e6-n0a9-d3c289387tga" : {
      "id": "78d5fd14-31e6-11e6-n0a9-d3c289387tga",
            "label": "Anzac Hwy On the Run",
            "activeOffers": 1,
            "couponsIssued": 5,
            "couponsRedeemed": 1
    }
    ],
    "from": "28-07-2016",
    "to": "14-08-2016"
}

HTTP Request

GET https://api.xerts.io/api/reporting/vendors/:id?from=dd-mm-yyyy&to=dd-mm-yyyy

Body Parameters

Parameter	Required	Type	ID	Description
id	Y	String	Y	vendor ID - unique identifier for the site

Query	Required	Description
from	Y	date from - the earliest date you want the range for
to	N	date to - the latest date you want the range for

Get coupon reports for a site

Use this command:

curl -X GET https://api.xerts.io/api/reporting/sites/:id?from=28-07-2016&to=14-08-2016 \
  -H "API-Key: '<Insert API Key here>'"
  -H "Authorization: '<Insert Authorization here>'"

The above command returns JSON structured like this:

{
    "totalCouponsIssued": 30,
    "totalCouponsRedeemed": 10,
    "vendors": [
        "48c4fd10-31e5-11e6-n0a9-d3c289387tga" : {
      "id": "48c4fd10-31e5-11e6-n0a9-d3c289387tga",
            "label": "Dymocks Books",
            "activeOffers": 2,
            "couponsIssued": 15,
            "couponsRedeemed": 2
        },
        "48c5fd11-31e5-11e6-n0a9-d3c289387tga" : {
      "id": "48c5fd11-31e5-11e6-n0a9-d3c289387tga",
            "label": "Mayhem Fireworks Co.",
            "activeOffers": 1,
            "couponsIssued": 10,
            "couponsRedeemed": 5
        },
        "48d5fd14-31e6-11e6-n0a9-d3c289387tga" : {
      "id": "48d5fd14-31e6-11e6-n0a9-d3c289387tga",
            "label": "Amazing Harry\'s Delicious Candy",
            "activeOffers": 3,
            "couponsIssued": 5,
            "couponsRedeemed": 1
    }
    ],
    "from": "28-07-2016",
    "to": "14-08-2016"
}

This endpoint gets all vendor coupons issued and redeemed for a site between two dates. If the to query parameter is not provided, system will give all stats up to now.

HTTP Request

GET https://api.xerts.io/api/reporting/sites/:id?from=dd-mm-yyyy&to=dd-mm-yyyy

Body Parameters

Parameter	Required	Type	ID	Description
id	Y	String	Y	site ID - unique identifier for the site

Query	Required	Description
from	Y	date from - the earliest date you want the range for
to	N	date to - the latest date you want the range for

Debug (developers)

Add a Client Device

Use this command:

curl -X POST https://api.xerts.io/api/device/ -d \
  "{ \
    'id': 'xxxx-xxxx-xxxx-xxxxx', \
    'deviceModel': 'iPhone 6s', \
    'deviceOs': 'iOS 9.3' \
  }" \
  -H "API-Key: '<Insert API Key here>'"

The above command returns JSON structured like this:

{
  "id": "89611c2c-f016-4e3b-8078-6abe40550552",
  "deviceModel": "iPhone 6s",
  "deviceOs": "iOS 9.3"
}

This endpoint creates a client device in the system. At this time there are no users associated devices, but this will change in future versions.

HTTP Request

POST https://api.xerts.io/api/devices

Body Parameters

Parameter	Required	Type	ID	Description
id	Y	String	Y	A unique identifier for the device will be posted to the API, generated by the client device it’s self.
deviceModel	N	String	N	Device model eg. iPhone 7
deviceOs	N	String	N	The operating system and version number.

Check if a device exists

Use this command:

curl -X POST https://api.xerts.io/api/device/:id \
  -H "API-Key: '<Insert API Key here>'"

The above command returns JSON structured like this:

{
  "exists": true
}

This endpoint checks if a device exists.

HTTP Request

POST https://api.xerts.io/api/devices/:id

Body Parameters

Parameter	Required	Type	ID	Description
id	Y	String	Y	A unique identifier for the device will be posted to the API, generated by the client device it’s self.

Errors

Error Code	Meaning
400	Bad Request – Your request sucks
401	Unauthorized – Your API key is wrong
403	Forbidden – The puppy requested is hidden for administrators only
404	Not Found – The specified puppy could not be found
405	Method Not Allowed – You tried to access a puppy with an invalid method
406	Not Acceptable – You requested a format that isn’t json
410	Gone – The puppy requested has been removed from our servers
418	I’m a teapot
429	Too Many Requests – You’re requesting too many puppies! Slow down!
500	Internal Server Error – We had a problem with our server. Try again later.
503	Service Unavailable – We’re temporarially offline for maintanance. Please try again later.