Before starting

Please read our SUV Integration options and introduction guide for context and familiarisation with our terminology on this subject.

You will also need access to our SOAP API. Please read http://support.airship.co.uk/en/articles/1957354-getting-started for an introduction.

Our API reference can be found here.

Getting started with our SOAP API

Please request the following from our support team:

  • API Username/password

These are unique to each Airship account, so will need to be manually configured for each of our mutual shared customers as part of an initial onboarding configuration.

We will also need the IP addresses you wish to connect from, which will be added to our allowed-list.

We will also provide you a user login for a Test Airship dashboard login, should you wish to visually check how data appears in our interfaces.

When working with our API, you should catch all SoapFault exceptions and handle these failures gracefully.

Configuration

For each customer, there should be the ability to set up some configurations. These include the following set-and-forget variables:

  • The root Unit ID where offer groups should be stored in Airship for this customer.
  • The folder ID for where offer groups should be stored in Airship for this customer.

And there also needs to be a way of mapping our UnitIDs (sites) to your sites/locations. The unitIDs are needed for passing redemption information to us, so we know where a particular code is being redeemed.

If you wish to build this into a self-service interface, you can call 3.8.1 - unitList to fetch a full list of our locations for this customer:

unitList(username As String, password As String) As StatSOAP.Unit()

You can then retrieve folderIds using 3.3.1 - groupList. Typically we would always use a Default or Offer Group containing folder on the root Unit, in which to store Offers.

groupList(username As String, password As String, unitID As Integer) As StatSOAP.Folder()

You will need the folderID and root UnitID in the next stage.

Creating a new offer in Airship

Step 1 - Create a contact group

You will need to call 18.1.1 - addGroup.

addGroup(username As String, password As String, groupName As String,
unitId as Integer, folderId as Integer) As Integer

Step 2 - Create a unique code group

Using the GroupID you created in Step 1. you will now need to call 9.8.1 - addUniqueCodeGroup.

addUniqueCodeGroup(username As String, password As String, groupid As
Integer, customerdescription As String, startdate As String, enddate As String, eflyerid As Integer, tflyerid As Integer) As Integer

addUniqueCodeGroup will return a UCGID. You will need to store this against your offer. You should now have a one-to-one relationship between our UCGID and your Offer.

Please show the UCGID and Offer name somewhere in your interface, as our mutual customer will need this when communicating with our team to set up a campaign.

Creating voucher codes

When batches of codes are created you will need to call 9.9.1 - addUniqueCodeGroupCodes, using the UCGID you created above.

addUniqueCodeGroupCodes(username As String, password As String, codes
As Array of Strings, ucGID As Integer) As Integer

Note that if a code already exists in the code group, we will reject it.

Redeeming voucher codes

When a customer presents a code for redemption, you will need to pass the following to our API:

  • the UCGID
  • the voucher code itself
  • an Airship UnitID that relates to the location of where this code is being redeemed (typically a particular restaurant, bar or cafe)

Call 9.5.1 - redeemUniqueCode

redeemUniqueCode(username As String, password As String, uniquecode As
String, ucgid As Integer, timestamp As Integer, unitid As Integer) As Integer

Use-case tests

You can access a list of scenario use-case tests that we recommend testing against, once you are familiar with our API.

User-experience check-list

On completion of an integration, can our customer do the following things?

  • Initially set-up the link between Airship and your platform, with minimal support from our respective Customer Success teams
  • Create offer groups and generate voucher codes in your platform, which will be immediately available for use in Airship
  • Easily track redemptions of voucher codes in both your platform and within in Airship

Did this answer your question?