The Basics
Refer to our “Getting Started” article for information about authentication, sandboxing, and Console access.
Prerequisites
You will need the following to get started:
SOAP credentials
sourceID (unique to account)
Endpoints
Use the endpoint for Contact API and Booking API provided in our SOAP API documentation.
Below is a summary of the API methods to use when writing contact and WiFi data to Airship.
Some of these may not be required depending on the usage scenarios.
createContact
contactValidation
unitList
groupList
getConsentTypes
createBooking
updateBooking
getBookingTypes
getBookingSources
getUpdatedContacts
getBookings
sendNewEflyer
Writing a contact record
Creating a record in Airship requires a mandatory consent array, and a mandatory groups array. The IDs required by these arrays can be obtained by using our API. Once you have the groupList response, this can be filtered down to the groups specifically for bookings. This should be polled at regular intervals so that your system has the most up to date groups as the client will open new locations over time.
Use API method unitList to retrieve the unitIDs. Use the returned unitIDs when you make requests to groupList to retrieve the groupIDs.
Use API method getConsentTypes to retrieve the consent IDs, which you will use when creating your consents array when making a createContact request.
Refer to the .NET and PHP examples in our SOAP API documentation in the footer of our website for more information.
Before attempting to create a contact, validate the data using the contactValidation API first.
To begin, make a SOAP request to API method createContact, with an array of contact data, using the groupIDs and consentIDs you retrieved earlier.
When a customer registers on your system, your system will write the contact data to Airship, with a unique identifier set by your system and saved to an Airship Dynamic Field. This will allow your system to find the contact in future to keep the record up to date.
Customer Data Mapping
It is recommended to create a spreadsheet with the mapping of your system’s fields to Airship fields, to ensure all data is correctly mapped before you start your integration with Airship.
Capturing affirmation of consent and passing this to Airship
When a customer registers on your system, they will provide their personal data, and your system will ask them to consent, on a granular basis, what they would like to give consent for.
Airship has a consent system which stores granular consent, associated with each contact record.
When you create a new contact, or update a contact, in Airship, you must provide an array of consent IDs and consent statuses.
Consent Mapping
You will need to map the consent captured by your system with the consent storage in Airship in a spreadsheet. This mapping will need to be signed off by your client.
Example Contact Creation Request
Use this endpoint:
https://secure.airship.co.uk/SOAP/V3/Contact.wsdl
$contact = array(
"uid" => "", // Leave uid blank
"email" => "joshua@airship.co.uk",
"allowemail" => "Y",
"sourceid" => "", //unique to account
);
$groups = array();
$groups = array(); //groupID relating to the physical venue location
$UDFs = array();
$UDFs[] = array("udfnameid"=>, "data"=>"Test Co", "type"=>"4b0e96af-011d-400e-bfb1-d9d767508d2f"); // Unique customer identifier from your system
$consents = array();
$consents[] = array("consenttypeid"=>1,"consentstatus"=>"Y");
$contactID = $client->createContact("username","password", $contact, $groups, $UDFs, $consents);
echo "contactID: ".$contactID;
Writing a booking record
Once you have written the contact and have the contactID, you can write the transactional booking data to Airship. Bookings should be pushed from your Bookings System, which will facilitate bookings made both online (website) and offline (walk-ins, telephone) being pushed to Airship.
Make sure to write your system’s unique transactional booking ID to 'booking_data_element_01' - this will be used later to identify the correct booking record when you perform update and cancel operations.
When defining the booking array, you will need to include the following parameters:
booking_contact_id - This is the contactID you retrieved from creating the contact.
booking_enquiry_source_id - Make a request to getBookingSources API method to find the ID to use.
booking_party_size - The number of guests.
booking_stage_value - Refer to the ‘Booking stage values’ section.
booking_type_id - Specify as ‘13’ for ‘General Booking’.
booking_unit_id - Make a request to unitList API method to find the ID to use.
booking_party_datetime - The date and time the booking will take place (seated date), e.g. 2013-05-02 20:30:00
booking_enquiry_datetime - The date and time the booking was made by the customer, e.g. 2013-03-21 21:00:06
booking_deposit_paid - If you system knows the total amount prepaid by the customer, send to this parameter as an integer.
booking_hpbr_drink - If you system knows the amount paid for drinks, send to this parameter as an integer.
booking_hpbr_food - As above, if your system knows the amount paid for food, send the value here.
booking_hpbr_entertainment - As above, if your system knows the amount paid for entertainment, send the value here. Values for drink, food and entertainment must total 100.
booking_data_element_01 - Write your system’s unique booking reference to this field.
Booking stage values
Booking stage field can contain “any” numeric value between 1 and 600. Airship have pre-defined status names assigned to different numeric values, as shown below. It is advised to use the status definitions as are, where possible, but it is possible to use extra stages inside external applications to facilitate between stage workflow.
New (10) range (1-19)
Customer Contacted (20) range (20-29)
Info Sent (30) range (30-39)
Follow-up (40) range (40-49)
Confirmation Received (50) range (50-59)
Deposit Secured (60) range (60-69)
Complete (100) range (100-499)
Unsuccessful (500) range (500-549)
Cancelled (550) range (550-600)
Bookings can also be kept up to date in Airship, by updating them each time a change is made in your Booking System. For example, if a customer cancels a booking, the booking can be looked up in Airship and marked as cancelled in Airship. Or, if a customer changes their booking date, the date can be updated in Airship to reflect this.
Retrieve new and updated contacts in Airship
Your system needs to keep data in sync between itself and Airship by polling Airship for updated records on an hourly basis. This will be important as data could change in Airship without Airship triggering a push to your system (e.g. a consent change or a DoB).
By polling Airship, you will retrieve an array of updated contacts, which can then be looped through with getContact to retrieve the most up to date information for each contact.
To ensure you are updating the correct contact record in your system, sense check using the unique customer identifier written to the Dynamic Field earlier.
Make a request to getUpdatedContacts.
Use getContact to retrieve the customer details for the contacts returned by getUpdatedContacts.
Use lookupContactByUDF to make a request to find the customer, using your unique customer reference as the search.
Use getContactConsent to request the existing consent for a customer.
Use getConsentTypes to retrieve Airship’s standard list of granular consent types.
Searching and Updating Bookings
To get the correct booking back to amend or cancel, you will first need to search for bookings to get the bookingID based the transaction ID stored against that booking in booking_data_element_01.
Use the following API methods to search and update bookings:
getBookings
updateBooking
To cancel a booking, set the stage value of the booking to 550.
Sending transactional emails using Airship
When a customer makes a booking, the system will send a confirmation email to them.
You can use the Airship API method sendNewEflyer to send transactional email using Airship’s email platform. You can pass the HTML and text content of an email to the API, meaning you can retain control over the content and appearance of the email.
Transactional email can be sent for booking confirmation and feedback emails.
Please note: This API method should only be used for transactional email broadcasts, where you have ensured legal grounds to send the message to the included recipients.
QA Procedure
Airship will send a data integrity testing spreadsheet, to be completed by the developer, and then sent to Airship to complete the QA process.
Here are some common scenarios that you should test your integration with:
A customer fills out a booking form on a venue’s website
A customer walks in to the venue without a booking
A customer calls to make a booking
A customer cancels a booking (e.g. via website or via phone call)
A customer amends a booking (e.g., changed the party date, or changed the number of guests)
A customer has made a booking
A customer’s booking has taken place (e.g. booking date is now in the past)
Glossary
Account - A client in Airship’s system. There is a separate account for testing purposes.
Unit - A physical location, such as individual restaurants. Units are associated with an account.
Folder - Folders are associated with a unit and contain groups.
Group - Groups are associated with a folder and contain contacts. Groups have unique IDs called groupIDs and names within each unit.
Contact - Contacts are individuals that are associated with groups. Contacts must have a valid email address and/or a valid UK mobile number in order to exist in Airship.
sourceID - A ID associated with a source for an account. These are unique on an account basis.