Smartix API

The Smartix API lets your own applications create and manage Apple Wallet and Google Wallet passes, update pass data, send notifications and administer your Smartix account.

APIs

Smartix exposes three APIs:

• Passes API — create, update, query and delete wallet passes, and send notifications.
• Clients API — manage clients, users and API keys, and retrieve account and billing information.
• Devices API — deliver Apple Wallet passes to devices. Installation URLs are normally returned by the pass-creation response. Google Wallet installation is handled through Google’s wallet service.

API Versions

Devices and Clients API will be updated from time to time. Updates to these APIs will always have backward compatibility.

Passes API, on the other hand, may have breaking changes in further versions. For this reason, Smartix confines changes to the API to non-breakign changes. Where a breaking change is necessary we will deploy an additional version of the API.

eg. current API version is passes-01 (Internally 01.03.xx)

If we release a version with a breaking change we will deploy passes-02, whilst also maintaining passes-01. You will need to change your configuration to use the new version (and can downgrade if necessary). We will maintain older version for s minimum of 12 months after a new API major release.

Authentication and test mode

API keys are created in Studio. See Accounts > API Keys

Requests must include the API key in the x-api-key header. Where an endpoint supports both modes (typically pass creation), the mode is selected using the x-mode header which is set to “live” or “test”. If omitted it default to “live”.

Keep keys server-side (Do not invoke Smartix API directly from a browser based application) and create a separate pair for each application that needs access.

API Reference and examples

The complete endpoint reference, request and response examples, authentication details and sample payloads are maintained in Postman.

Open the Smartix API documentation in Postman

You can also download the Postman collection from the Smartix downloads page.

Before going live

Create and test a template in Studio, issue test passes and inspect them on real Apple and Google devices. Before switching to LIVE, confirm that your application handles validation errors, rate limits, asynchronous pass updates and the credit cost of actions that consume credits.

Find out more about API integrations on our main website

Creating your first pass with the API

Create a template

Templates must be created in Smartix Studio. You use a WYSIWYG editor to design your template using one of our base tempates as a starting point.

Watch this video to learn how to create a template.

Pay special attension to the Google sharing options (In the META DATA section of the editor). You cannot switch to any of the single user options, after you have issued a pass with the default multi-user option.

Make a note of your template ID (Find this under template details)

Create an API key

In order to use the API you require an API key.

If you have multiple applications you should create a separate API key for each. Do not re-use a single API key accross multiple applications.

If you suspect your key may have been compromised, create a new one and delete the old one.

To create an API key select Account in the left side menu, then API KEYS

Here you can see and manage your existing keys…

Click the NEW API KEY button, give your key a suitable name to identify it (anything you like) and select the required Key usage option. Use Custom for our API.

For added security you can limit the IPs that your key can be used from. IPs should be specified in CIDR format.

Click CREATE API KEY button.

Make a copy of your API Key and configure it secuerly in your application.

Create a pass

URL : https://api.smartix.uk/passes-01/makePass/:template_id where :template_id is the ID you copied from your template
METHOD: PUT
HEADER :
     x-api-key : {your API key}
     x-mode : {live or test} (default to live if omitted)
BODY: {}

Body will contain any pass variables that you wish to set. Any variable not provided will default to using the template defaults. eg.

{
  "loyalty" : {
    "points" : {
      "balance" : 99,
      "collected" : 600
    }
  }
}

or

{
  "loyalty.points.balance" : 99,
  "loyalty.points.collected" : 600
}

The resonse will look something like this:

{
    "appleUrl": "https://api.smartix.uk/pkpass/eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjIjoyLCJ0IjoibG95YWx0eV9FRFZfVjFXX1FOUF9KSEZfNjVGIiwicCI6Ik1DWUgtQ0pWQy1EWDJaLTRDOTMiLCJpYXQiOjE3OTE5ODk1MDV9.ein1Iw1X_MPnQq-XkXiMkZhjfVLEV5iF5FBOilDyNns",
    "credits_used": 10,
    "googleUrl": "https://pay.google.com/gp/v/save/eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzbWFydGl4QHNtYXJ0aXgtMzA1ODE0LmlhbS5nc2VydmljZWFjY291bnQuY29tIiwiYXVkIjoiZ29vZ2xlIiwib3JpZ2lucyI6WyJ3d3cuc21hcnRpeC51ayJdLCJ0eXAiOiJzYXZldG93YWxsZXQiLCJwYXlsb2FkIjp7ImxveWFsdHlPYmplY3RzIjpbeyJpZCI6IjMzODgwMDAwMDAwMTAwNzM2OTMuMi5sb3lhbHR5X0VEVl9WMVdfUU5QX0pIRl82NUYuTUNZSC1DSlZDLURYMlotNEM5MyJ9XX0sImlhdCI6MTc5MTk4OTUwN30.27DquPc0XzaEjk2FCYHvyHMXJOjj1Lu3A6OQuyPzOM80MoBO0CvPolVzCW_u_ww_MSnL9GMFPqaz_FPLkfWVzKHxsdSSbattOECu2PCv5suwBwKdEJ-rW_98sqHChCEHA4F_d2ZmQvYnaWDWYnryULdDG4QCYYI1hJh44GlKjOL20H-sK6keAqqWf1Zfy8R4Q8Ky1NmVsqXRyD1Jfgu9c0tlS_mIn7-AmVl-MruGibJYE6GDBiU-UfwiCGV3SFnQege82ADrHHz6zyJBWTzibLDTiOvLLJ1besxn3HefYlyFvJE0lgO9OO6WJsitifJnmSrBRG1NIO0bazuMLPBNLw",
    "mode": "live",
    "ok": true,
    "pass_id": "MCYH-CJVC-DX2Z-4C93",
    "shortUrl": "https://api.smartix.uk/i/l9K2hPwDYucFvkdQ"
}

The most important elements are: pass_id which you need in order to update or notify the pass, and shortUrl which is the URL you can provide to an end user so they can install the pass on their device.