# Welcome Hello and welcome to our developer and integrations portal. We've built these pages to help you integrate and extend Airship using our APIs. Our documentation is organised into three main areas: * An overview of our REST API, how to get connected and a full API Reference * Some basic tutorials for common things you may wish to do with our API * Some full integration and accreditation tutorials aimed at our data partners for common full integration scenarios. # Overview New to developing with Airship? Start here. We have a growing REST API which makes extending and integrating with Airship simple and powerful. {% hint style="success" %} Our REST API endpoint is: {% endhint %} Authentication is via access tokens, which can be generated in the Airship dashboard. # Authentication How to get connected ### API Personal Access Tokens To connect to REST API, you will need a Personal Access Token (PAT). You can create an API Access Token within the Airship dashboard. Head to **Users** > **Personal Access Tokens** to do this. We have full details on how to do this [over on our Academy article here >](http://academy.airship.co.uk/en/articles/5432372-how-to-create-api-access-tokens) ### Tokens REST API uses Personal Access tokens to authenticate API requests. So before making any request to a protected resource, you'll need to make sure you have a valid token, as you'll need to include this in your authorisation header on each request. Personal Access Tokens do not refresh. Make sure you handle and store this token securely. If it becomes compromised, make sure you revoke access for it. ### Using tokens in requests Whenever the user wants to access a protected route or resource, the user agent should send their token in the Authorization header using the Bearer schema. The content of the header should look like the following: `Authorization: Bearer ` ### Authentication failure If you are not authorised and you attempt to make a request to a protected endpoint, the API will return JSON with errors.Authentication Failure ``` { "errors": [ { "message": "Unauthorized", } ] } ``` # Accreditation For approved partner integrations, you will need to complete our accreditation process. ### **Accreditation test cases** You will be asked to complete a series of test cases to ensure all use-cases for the type of integration have been met. Here is a sample list of test cases: **Authentication** * To test successful API authorisation * To test failed API authorisation with incorrect username/password **Contacts** * Create contact (new) * Create contact (update) * Create contact (new + Opted in) * Create contact (new + opted out) * Create contact (with rules) * Create contact (with valid unit) * Create contact with group(s) * Failed create contact (invalid unit) * Failed create contact (invalid email address) * Failed create contact (invalid DOB) **Bookings** * Create new booking (new contact) * Create new booking (update contact) * Create invalid booking (new contact) * Create invalid booking (update contact) * Search for valid booking reference * Search for invalid booking reference * Search and update booking **WIFI** * Create valid WIFI (new contact) * Create valid WIFI (existing contact) * Create valid WIFI with appropriate type (Detected / connected / authenticated) * Create invalid WIFI (new contact) * Create invalid WIFI (existing contact) **Purchases** * Create valid purchase (new contact) * Create valid purchase (existing contact) * Create invalid purchase * Create valid purchase (multiple QTY item) * Create valid purchase (multiple items in basket) **Retries** * Retry process **Logging** * API logging # Contacts Working with contacts in Airship Contacts are the basis of all customer data in Airship. Contacts records can store all sorts of data such as contact information and personal details. A contact record can also have any number of transactional records attached to them to represent a contact's timeline of interactions. For example, Table Bookings, WiFi interactions, Feedback, Purchase History and more. ### Contact merging Airship automatically merges contact records together based on unique customer identifiers. These identifiers are `email` or `mobile_number`. In other words, if you write a contact to us with an email address or mobile that already exists as part of a contact on Airship, we'll automatically update and/or append the data you send to the pre-existing contact record. # Write a contact How to store a contact to Airship ### Endpoint ```yaml https://api.airship.co.uk/v1/contact ``` ### Configuration | Field | Notes | | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `account_id` | The account ID represents the account that you are storing this contact to. If you are unsure of what your account ID is, ask our support team to confirm. | | `full_contact_object` |

Optional (defaults to True if not added)

Boolean for if you want the full contact object returned when creating a contact. If set to false, only a contact ID will be returned in the response (making the request quicker), else if true or not added to the request, the full contact object will be returned

| | `source_id` | The source ID represents the source of this data, for example "Table Booking" or "WiFi". Usually our support team will advise on a predefined source ID to use. However, you can also create them on-the-fly by passing in`source_name` rather than `source_id`. We'll create a source of that name if one doesn't already exist. | | `units` | Airship has predefined locations or "units" to store contacts for different physical locations. The units object represents which location you wish to store this contact to. You can fetch a list of units for your account using the `account/units`endpoint. You can pass in an array of units if you wish to store to more than one location. | | `groups > name` | Groups can represent any predefined tag or segment for a contact. If you pass in a name, a group of that name will be created on that unit if it doesn't already exist. Alternatively, you can pass in an `id` for a pre existing group. | | `groups > folder_name` | A folder\_name can be specified for your group, allowing the data to be structured in folders via the API for easier segmentation / categorisation. If no folder is defined, the `default` folder will be applied | | `gender` | Value is either "M" for Male or "F" for Female. For non-binary / other, leave blank. | ### Basic contact payload {% tabs %} {% tab title="Body" %} ```javascript { "account_id": 3, "full_contact_object": false, "first_name": "John", "last_name": "Smith", "mobile_number": "07780704261", "gender": "M", "email": "johnsmith@airship.co.uk", "dob": "1982-01-16", "source_id": 125795, "allow_sms": true, "allow_email": true, "units": [ { "id": 8775, "groups": [ { "name": "My First Group", "folder_name": "Web signups" } ] } ] } ``` {% endtab %} {% tab title="Response" %} ```yaml { "allow_sms": "1", "allow_email": "1", "allow_call": "", "allow_snail_mail": "", "udfs": [], "units": [ { "id": 8775, "name": "Sheffield", "groups": [ { "id": 121981, "name": "My First Group" } ] } ], "feedback": "https://api.airship.co.uk/v1/contact/44431435/feedback", "purchases": "https://api.airship.co.uk/v1/contact/44431435/purchases", "id": 44431435, "gender": "M", "title": "", "first_name": "John", "last_name": "Smith", "dob": "1982-01-16", "building_name": "", "building_num_street": "", "locality": "", "postcode": "", "city": "", "country": "", "county": "", "mobile_number": "447780704261", "home_number": "", "preferred_method_id": "0", "work_number": "", "email": "johnsmith@gmail.com", "source_id": "125795", "membership_number": "", "membership_type": "" } ``` {% endtab %} {% endtabs %} ### Using rules When creating a contact, you can also opt to use one of our "rules". These have been created to allow you to control how your contact will be stored in Airship, and can help take away the strain of dealing with extra logic to handle these scenarios within your app. | Rule | Description | | ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `discard_invalid_data` | We'll discard any data that doesn't pass our validation, and store the rest. For example, if you pass in an invalid `mobile_number` but a valid `email`, we'll discard the mobile but store the email, along with the rest of the data. Note that we require at least a valid email or mobile to be able to store a contact record. | | `historic_data` | If you pass in this rule, if the contact already exists on Airship, the consent/opt-in flags will be preserved regardless of what is passed in for the opt in values. | | `preserve_consent` | If you pass in this rule, if the contact already exists on Airship, the consent/opt-in flags will be preserved when passing in 'N' opt in values. | | `detach_existing_groups` | If you pass in this rule, all existing groups will be removed from the contact record, and they will be only added to the group passed in the request | | `update_only` | If you pass in this rule, it will only append / update existing Airship contact profiles with any information passed, and never create a new contact record | Example using "rules": ```json "account_id": 3, "email": "johnsmith@airship.co.uk", //...etc... "rules": [ { "rule_name": "preserve_consent" }, { "rule_name": "discard_invalid_data" } ] ``` ### Contact notes Contact notes are optional, and can be appended to a contact record. A note cannot be amended once added, and we will add a new note for every request we receive with a notes field
FieldNotes
textNotes string that you want to store. Max 500 character length
created_atDate/time of note creation. If no created_at field is added, it will default to the timestamp the request was received

Optional
```json "account_id": 3, "email": "johnsmith@gmail.com", //...etc... "notes": [ { "text": "I liked the cocktails!", "created_at": "2024-02-10 15:10:00" } ] ``` ### Custom fields As well as the standard fields documented on our API Reference, we can also store custom values to User Defined Fields (UDFs). These have to be pre-created in the Airship dashboard and you will need to know the UDFID of the field you wish to write data to. UDFs can be passed in as an array as part of your payload. ```yaml "account_id": 3, "email: "johnsmith@gmail.com", //...etc... "udfs": [ { "id": 1234, "data": "some text" }, { "id": 5678, "data": "2021-05-01" } ] ``` ### Mobile number validation Mobile numbers are validated for an accepted prefix, which can be any of the following: 4471, 4472, 4473, 4474, 4475, 4476, 4477, 4478, 4479, 071, 072, 073, 074, 075, 076, 077, 078, 079 ### Email validation Emails are validated to contain a `@` and a `.` and are also checked against a list of domains with valid MX records, to protect against commonly mistyped or fake domains. # Append feedback Store transactional feedback records as you send contact data to us ### Overview Airship can store full feedback history for contact records. This is useful to show the sentiment of a particular guest, and can be used in campaigns whereby a broadcast could be suppressed if someone has left feedback recently (for example if you don't want to ask someone for feedback about a recent visit if they've already done so). ### Storing feedback To store feedback, simply include a feedback object as you write a contact to us. We'll store a historic feedback record against the contact. | Field | Notes | | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `type_id` |

1 = positive

2 = negative

3 = neutral

4 = unknown

You can also retrieve feedback types from the /feedback/types endpoint.

| | `source_id` |

1 = website

2 = facebook

3 = tablet

4 = email

5 = twitter

| | `unit_id` | The unit\_id representing the physical location for which this feedback relates. | | `comments` | Pass in a `type` to tag comment types together (e.g. "Toilets", "Service" etc) along with a text string for this comment. | | `ratings` |

Pass in a ratings category\_id along with a value for this rating in the rating\_text field, and an optional contact\_note..

You can retrieve a list of categories from the /feedback/categories endpoint. However, commonly used ones are:

1 - Food

2 - Drink

3 - Service

4 - NPS

| ```javascript "account_id": 3, "email: "johnsmith@gmail.com", //...etc... "feedback": [ { "type_id": 1, // positive "source_id": 1, // website "unit_id": 8775, "comments": [ { "type": "Toilets", "note": "Recently cleared and sparkling!" }, { "type": "Other Comments", "note": "Had a great time, will definitely return!" } ], "ratings": [ { "category_id": 1, // Food "rating_text": "Excellent", "contact_note": "Food was super tasty." }, { "category_id": 2, // Drink "rating_text": "Good", "contact_note": "Drinks were great, if a little expensive." }, { "category_id": 3, // Service "rating_text": "Poor", "contact_note": "We had to wait 15 minutes to pay at the end." }, { "category_id": 4, // NPS "rating_text": "8", "contact_note": "Would definitely recommend to a friend" } ] } ] ``` # Append purchase history Store transactional purchase history as you send contact data to us ### Overview Airship can store full purchase history for contact records. This is useful to measure customer value and target recent or lapsed visitors based on their purchase history. ### Storing purchase history To store purchase history, simply append a `purchases` object to your contact as you send it to us. | Field | Notes | | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | provider\_id | This is the partners ID to help identify the source of a purchase. If you need one creating, please contact , we'll get one added and provide you an ID | | order\_type\_id |

The order type relating to how the purchase was made;

1 = Unknown

2 = Pay at table

3 = Click and Collect

4 = Dine in

5 = Delivery

6 = Online Shop

7 = Other

| ```javascript "account_id": 3, "email: "johnsmith@gmail.com", //...etc... "purchases": [ { "transaction_reference": "77FF-24FF-234F-77FF", "unit_id": 8775, "created_at": "2021-06-01 00:00:00", "provider_id": 1, "order_type_id": 4, "items": [ { "description": "Negroni", "sku": "abc_8913", // string SKU for this product "quantity": 1, // qty of this item "value": 7 // total value (quantity x item value) in decimal }, { "description": "Garlic Bread", "sku": "5621", "quantity": 2, "value": 8.40 } ] } ] ``` # Append booking data ### **Overview** Airship can store full table booking history for each contact. Having booking data attached to contacts is useful to measure and target recent or lapsed visitors based on their last visit. ### Storing bookings To store booking history, simply append a `bookings` object to your contact as you send it to us. All new and updated bookings can use the same endpoint / payload - Airship will determine if the booking is a New booking, or an Update to an existing booking based on if we have the Booking\_reference stored against another reservation. | Field | Notes | | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `source_id` |

1 = Website

9 = In House

10 = Third Party

etc.

You can also retrieve booking source IDs from the /booking/sources endpoint.

| | `stage_value` |

1 = New

100 = Complete

550 = Cancelled

You can also retrieve stage values from `booking/stage_values` endpoint. We use ranges to represent more granular booking stages, though the three values above satisfy most requirements.

| | `unit_id` | The unit\_id representing the physical location for which this booking relates. | | `type_name` | A descriptive value for the booking type, i.e. `Table Booking` or `Drinks table` | | `provider_id` | This ID is unique per partner. See your airship integration contact to get this ID | | `table_numbers` |

If the table numbers are assigned against the booking, then these can be passed in an array

Optional

| ```javascript "account_id": 3, "email: "johnsmith@gmail.com", //...etc... "bookings" : [ { "source_id" : 1, // Website, In-house etc. "party_size" : 10, // how many guests in this booking "stage_value" : 1, // New, complete, cancelled etc "type_name" : "General Booking", // General booking, Birthday etc. "unit_id" : 67, "party_datetime" : "2021-04-27 20:30:00", // seated date "enquiry_datetime" : "2021-04-27 21:00:06", // enquiry date "deposit_paid" : 0, // if applicable "hpbr_drink" : 0, // deposit split against drink "hpbr_food" : 0, // deposit split against food "hpbr_entertainment" : 0, // deposit split against entertainment "booking_reference" : "4355-GH3TG-AERA", // unique booking reference for booking "provider_id" : 5, // this ID is unique to the partner - see your airship contact "table_numbers": [ "1", "24", "34" ], "data": { "element_01" : "juice", // dynamic field content that can be stored against reservation } "notes" : [ // optional notes { "text" : "Test note on bookingID 5", "time" : "2021-04-27 21:00:06" } ] } ] ``` ### What are data\_elements? Data elements can store any alphanumeric string, so are, in effect, placeholders for any custom data you wish to store. Airship can store up to 20 data element fields against a reservation which aren't covered in the native fields. # Append WiFi data Store WIFI Interaction history as you send contact data to us ### Overview Airship can store WIFI interaction history for each contact. Having WIFI data attached to contacts is useful to measure and target recent or lapsed visitors based on their last visit. ### Storing WIFI interactions To store WIFI interactions, simply append a `wifi_interactions` object to your contact as you send it to us. | Value | Notes | | ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `datetime` |

The date / time of the WIFI interaction

Required field

| | `unit_id` |

The unit\_id representing the physical location for which this WIFI interaction relates

Required field

| | `type` |

detected - This interaction type should be used when a user's device passively connects to the WiFi hotspot.

connected - This interaction type should be used once a user proactively views your captive portal.

authenticated - This interaction type should be used once a user has provided the information required by the captive portal to connect to the Internet via your WiFi service.

unknown - If your platform doesn't support the above connection types, use the unknown type

Required field

| | `hotspot_name` |

Text description of where the connection was made (i.e. Upstairs Bar)

Optional

| | `mac_address` |

Unique device reference

Optional

| | `device_mime_type` |

Text description for the source of the WIFI interaction

Required Field

| ### Example Payload ```json { "account_id": 3, "email": "johnsmith@gmail.com", //...etc... "wifi_interactions" :[ { "datetime":"2022-01-01 12:00:00", "unit_id": "4", "type": "authenticated", "hotspot_name": "Bar 01", "mac_address": "01:A1:C1:11:C1:11", "device_mime_type": "Airship Splash page" } ] } ``` # Append Stay data Store Hotel Stay Interaction history as you send contact data to us ### **Overview** Airship can store full hotel stay booking history for each contact. Having stay data attached to contacts is useful to measure and target recent or lapsed visitors based on their last visit. ### Storing Stays To store stay history, simply append a `stays` object to your contact as you send it to us. | Field | Notes | | --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `booker` |

True / False, if the contact data being provided is the Booker of the Stay
Required field

| | `guest` |

True / False, if the contact data being provided is the Guest of the Stay
Required field

| | `unit_id` |

The unit\_id representing the physical location for which this WIFI interaction relates

Required field

| | `provider_id` |

Unique ID for the integration partner. If you are a new integrator, please contact our support team to get a new ID setup
Required field

| | `stay_reference` |

Unique booking reference for the stay. If the stay\_reference has previously been provided by the same provider, we will interoperate this as an update to that Stay
Required field

| | `enquiry_date` |

Date/time the stay was created, in the format 'yyyy-mm-dd hh:mm:ss'
Required field

| | `checkin_date` |

Date/time of the stay checkin, in the format 'yyyy-mm-dd hh:mm:ss'
Required field

| | `checkout_date` |

Date/time of the stay checkout, in the format 'yyyy-mm-dd hh:mm:ss'
Required field

| | `room_type_id` |

1 = Basic

2 = Standard

3 = Premium

The classification of the room type booked
Required field

| | `total_guests` |

This is a sum of the total guests booked for the stay (adults + children)
Required field

| | `total_children` | This is the total children booked for the stay | | `booking_enquiry_source_id` |

1 = Website
9 = In house
10 = 3rd Party

You can also retrieve booking source IDs from the /booking/sources endpoint.
Required field

| | `deposit_amount` | Deposit paid for Stay | | `room_gross_value` | Gross room value for stay | | `room_net_value` | Net room value for Stay | | `extras_gross_value` | Extras gross value for Stay | | `extras_net_value` | Extras net value for Stay | | `booking_status_id` |

1 = Enquiry

2 = Provisional

3 = Confirmed

4 = Checked in

5 = Cancelled

6 = No show

7 = Checked out

The latest status for the Stay
Required field

| | `room_rate_code` | Internal Room Rate Code for the booking | | `room_package_code` | Internal Room Package Code for the booking | | `used_voucher` |

If the booking had a voucher associated

Boolean, true / false

| | `booking_has_pets` |

If the booking has pets

Boolean, true / false

| | `stay_travel_agent` | If the booking was an OTA, what is the travel agent provider? (i.e. Booking.com) | ### Example Payload ```json { "account_id": 3, "email": "johnsmith@gmail.com", //...etc... "stays": [ { "booker": true, "guest": false, "provider_id": 3, "stay_reference": "my-unique-ref", "unit_id": 13822, "enquiry_date": "2021-04-27 20:30:00", "check_in_date": "2022-02-01 14:30:00", "check_out_date": "2021-02-03 10:30:00", "room_type_id": 2, "total_guests": 4, "total_children": 2, "booking_enquiry_source_id": 10, "deposit_amount": 250, "room_gross_value": 400, "room_net_value": 400, "extras_gross_value": 210, "extras_net_value": 210, "booking_status_id": 1, "room_rate_code": "DBL", "room_package_code": "Package-23a", "used_voucher": true, "booking_has_pets": false, "stay_travel_agent": "booking.com", "extras": [ { "name": "Pets", "reference": "PT", "start_date": "2023-04-28 20:30:00", "end_date": "2023-04-28 20:30:00", "quantity": 4, "price": 400 }, { "name": "Breakfast", "reference": "Break", "start_date": "2023-04-28 20:30:00", "end_date": "2023-04-28 20:30:00", "quantity": 1, "price": 1000 } ] } ] } ``` ### Extras Extras can now be added to a Booking to allow us to capture any additional products / purchases / upsells. | Field | Notes | | ----------- | -------------------------------------------------------------------------------------- | | name |

String description of the extra
Required

| | reference |

SKU or product reference number for the extra
Required

| | start\_date |

Extra start date (use stay checkin date if not applicable)
Required

| | end\_date |

Extra end date (use stay check out date if not applicable)
optional

| | price |

value of the extra(s) in pence
Required

| ### Update bookings To update a booking, you can pass the same object against a contact - and if we identify the `stay_reference` and `provider_id` against an existing stay, that stay will be updated. # Append Loyalty data Store Loyalty Interaction details as you send contact data to us ### **Overview** Airship can store Loyalty data for each contact. This is stored as a card entity against the contact, and each card can have different details such as Card balance, card points, etc. A must be part of a Scheme, which is a grouping for the cards. Each card must also be unique within a Scheme, as if we see a duplicate reference - we will update the original card details. ### **Overview** Airship can store Loyalty data for each contact.
FieldNotes
transaction_datetimeDate time of interaction
Required field
unit_id

The unit_id representing the physical location for which this Loyalty interaction relates. If provided, a PoP will also be generated for the specified transaction_datetime

Optional field

reference

The unique loyalty reference, which relates to the entity which identifies the balance / points (i.e. Card number, or customer identifier)

Required field

pin

If applicable, the pin associated to the card

Optional field

card_points

If the card has a points balance, the amount of points on that card

Optional field

card_balance

If the card has a cash value, the value that is on that card

A card can have a mixture of Points and Balance

Optional field

active

If the card is active, then active = true.

If the card has been suspended, then active = false

The flag will always default to active if not specified

Optional field

provider_id

Unique ID for the integration partner. If you are a new integrator, please contact our support team to get a new ID setup


Required field

purchase_valueIf the card was purchased, the value which the card was sold for

Optional field
next_expiry_amountIf the card has any points or balance which are due to expire, the next amount which will be removed from the card

Optional field
next_expiry_dateIf the card has any points / balance which are due to expire - the date they are due to expire

Optional field
### Example Payload ``` { "account_id": 3, "email": "johnsmith@gmail.com", //...etc... }, "membership_cards": [ { "reference": "ABC-001-XYZ", "scheme_reference": "Staff Loyalty Scheme", "transaction_datetime": "2021-04-27 20:50:00", "unit_id": 67, "pin": 123456, "points": 100, "balance": 0, "active": true, "provider_id": 5, "purchase_value": 0, "next_expiry_amount": 0, "next_expiry_date": "2022-01-02" } ] } ``` # Append ticket data Article coming soon... # Append other PoPs ### **Overview** Where a guest has visited a venue and there is a digital footprint which doesn't neatly fit into any of our pre-existing native categories (e.g. table booking, purchase history, loyalty interaction, voucher redemption, WiFi login, ticket), we also have the option to store a Proof of Presence (PoP) without full context. Having this "PoP" data stored historically is useful to measure and target guests based on recency and frequency. To store a PoP, add a `pops` object as you write a contact record. ```javascript "account_id": 3, "email: "johnsmith@gmail.com", //...etc... "pops" : [ { "unit_id" : 123, // where the PoP happened "type_id" : 2 // Member check-in, feedback submission etc "datetime" : "2021-06-01 00:00:00" // When the pop happened } ] ``` #### PoP Types To retrieve a list of `pop_type_ids` you can call the `/pop/types` endpoint. {% hint style="warning" %} Note that storing a PoP is not a substitute for sending a full record of an interaction in scenarios where we have full native storage fields. For example: Bookings, WiFi, Purchase History, Loyalty, Voucher Redemptions and Tickets. You should always use our native storage where we have an appropriate category. {% endhint %} # Stoplight replacement - BETA {% openapi src="/files/YR7SA54M0DBg2Ui7jFA0" path="/v1/contact" method="post" %} [openapi2.json](https://2302983881-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MaxcxnRYSpu4Ro2wmf4%2Fuploads%2FPYszrW9cgRs2YZ8cvIHn%2Fopenapi2.json?alt=media\&token=07d44a2c-c6b6-4a91-bc79-9dbe9490497f) {% endopenapi %} # Bookings Working with bookings in Airship ### Booking search Our booking search endpoint allows you to query table bookings on a specific field (i.e. booking reference) to return the booking payload. The Booking ID returned from this call can then be used as a parameter update the booking. ### Booking Update Our booking update enables partners to provide an update to an existing booking within Airship, for status changes (i.e. cancelations) / reservation updates. In order to update a booking within Airship, the Airship Booking ID is required to be passed as a parameter. Note, [Airships Contacts + Append booking data](/basics/contacts/append-booking-data) endpoint will automatically update an existing booking based on if the Booking\_reference is already in Airship. # Booking Search by reference ### Overview Airship allows partners to query bookings on certain fields. If a booking reference is provided when the data is passed to Airship, then the `/bookings` endpoint can be used to search for that booking, and return key information about it. ### Endpoint {% tabs %} {% tab title="GET" %} ``` https://api.airship.co.uk/v1/bookings?account_id={account_id}&booking_reference={your_ref} ``` {% endtab %} {% endtabs %} ### Configuration #### Path Parameters | Field | Notes | | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `account_id` | The account ID represents the account that you are searching bookings in. If you are unsure of what your account ID is, ask our support team to confirm. | | `booking_reference` | The booking reference is the reference you have previously provided against the booking. Note, this must have been provided in the booking\_reference field when creating the booking | #### Headers | Field | Notes | | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `Authentication` (bearer token) | The authentication token is linked to the account that you are searching bookings in. If you are unsure of what your Authentication token is, ask our support team to confirm. | ### Basic booking search payload {% tabs %} {% tab title="Response" %} 
{
    "booking_contact_id": "87534364",
    "booking_reference": "test-booook1",
    "id": 44922318,
    "account_id": "806",
    "contact_id": "87534364",
    "unit_id": "13835",
    "stage_value": "69",
    "type_id": "51",
    "datetime": "2021-04-27 20:30:00",
    "source_id": "6",
    "party_datetime": "2022-07-20 20:30:00",
    "party_size": "10",
    "deposit_paid": "501.00",
    "hpbr_food": "0.00",
    "hpbr_drink": "0.00",
    "hpbr_entertainment": "0.00",
    "updated_at": "2021-04-27 20:30:00"
}
{% endtab %} {% endtabs %} # Booking Search by data\_element ### Overview Airship allows partners to query bookings on certain fields. If a booking reference is provided when the data is passed to Airship, then the `/bookings` endpoint can be used to search for that booking, and return key information about it. Airship can store up to 20 dynamic fields against a booking, and any of these values can be used with the booking search. ### Endpoint {% tabs %} {% tab title="GET" %} ``` https://api.airship.co.uk/v1/bookings?account_id={account_id} ``` {% endtab %} {% endtabs %} ### Configuration #### Path Parameters | Field | Notes | | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- | | `account_id` | The account ID represents the account that you are searching bookings in. If you are unsure of what your account ID is, ask our support team to confirm. | #### Headers | Field | Notes | | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `Authentication` (bearer token) | The authentication token is linked to the account that you are searching bookings in. If you are unsure of what your Authentication token is, ask our support team to confirm. | #### Query Parameters | Field | Notes | | ------------ | ---------------------------------------------------------------------------------------------------------------------------- | | `element_01` | Dynamic field provided by 3rd party at the point of creating the booking in airship. This is typically the booking reference | | `element_02` | Dynamic field | | ... | Dynamic field | | `element_20` | Dynamic field | ### Basic booking search payload {% tabs %} {% tab title="Body" %} ```javascript { "data": { "element_01": "My-Booking-Reference" } } ``` {% endtab %} {% tab title="Response" %} ```javascript { "current_page": 1, "data": [ { "stage_value_status": "Deposit Secured", "data_element_01": "My-Booking-Reference", "data_element_03": "Large Party", "data_element_20": "beef", "id": 12116500, "account_id": "806", "contact_id": "47426742", "unit_id": "13835", "stage_value": "69", "type_id": "51", "datetime": "2021-04-27 20:30:00", "source_id": "16", "party_datetime": "2021-04-27 20:30:00", "party_size": "10", "deposit_paid": "10.00", "hpbr_food": "0.00", "hpbr_drink": "0.00", "hpbr_entertainment": "0.00", "updated_at": "2021-04-27 20:30:00" } ], "first_page_url": "https://api.airship.co.uk/v1/bookings?page=1", "from": 1, "last_page": 1, "last_page_url": "https://api.airship.co.uk/v1/bookings?page=1", "next_page_url": null, "path": "https://api.airship.co.uk/v1/bookings", "per_page": 100, "prev_page_url": null, "to": 1, "total": 1 } ``` {% endtab %} {% endtabs %} # Booking Update ### Overview Airship allows partners to update bookings within the airship platform, to enable booking updates / cancelations / no shows to be updated. To update a booking, you'll need an Airship booking ID to be passed in the URL, which can be found from the [booking search](/basics/bookings/booking-search). ### Endpoint {% tabs %} {% tab title="POST" %} ```markup https://api.airship.co.uk/v1/bookings/{booking_id} ``` {% endtab %} {% endtabs %} ### Configuration #### Path Parameters | Field | Notes | | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `booking_id` | The booking ID is Airships unique reference for the booking, and represents the booking that you are attempting to update. The booking ID can be found via the [Booking Search](/basics/bookings/booking-search) endpoint | #### Headers | Field | Notes | | ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `Authentication` (bearer token) | The authentication token is linked to the account that you are searching bookings in. If you are unsure of what your Authentication token is, ask our support team to confirm. More details on authentication can be found [here](/rest-api/authentication) | #### Query parameters The booking fields which can be accepted in this section can be found in the [Append Booking Data](/basics/contacts/append-booking-data) section, with the addition of `account_id` (required) | Field | Notes | | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- | | `account_id` | The account ID represents the account that you are searching bookings in. If you are unsure of what your account ID is, ask our support team to confirm. | ### Basic update booking payload {% tabs %} {% tab title="Body" %} ```json { "account_id": 3, "enquiry_datetime": "2021-04-27 20:30:00", "updated_at": "2021-04-27 20:30:00", "source_id": 16, "party_size": 10, "stage_value": 69, "type_id": 51, "unit_id": 67, "party_datetime": "2021-04-27 20:30:00", "party_enquirytime": "2021-04-27 21:00:06", "deposit_paid": 0.01, "hpbr_drink": 0, "hpbr_food": 0, "hpbr_entertainment": 0, "data": { "element_01": "My-Booking-Reference", "element_03": "juice", "element_20": "chicken" }, "notes": [ { "text": "Test note on bookingID", "time": "2021-04-27 21:00:06" } ] } ``` {% endtab %} {% tab title="Response" %} ```json { "stage_value_status": "Deposit Secured", "data_element_01": "My-Booking-Reference", "data_element_03": "juice", "data_element_20": "chicken", "comments": [ { "id": 455628, "text": "Test note on bookingID", "created_at": "2021-08-13 15:24:54" }, { "id": 457554, "text": "Test note on bookingID", "created_at": "2021-08-26 13:43:49" } ], "id": 12116500, "account_id": "3", "contact_id": "47426742", "unit_id": 67, "stage_value": 69, "type_id": 51, "datetime": "2021-04-27 20:30:00", "source_id": 16, "party_datetime": "2021-04-27 20:30:00", "party_size": 10, "deposit_paid": 0.01, "hpbr_food": 0, "hpbr_drink": 0, "hpbr_entertainment": 0, "updated_at": "2021-04-27 20:30:00" } ``` {% endtab %} {% endtabs %} # Search Contact Airship gives the ability for API users to 'search' for contacts on certain attributes, to enable partners to query and identify contacts. Some use cases for this are; * Ability to search for a contact by Email, Mobile or first / last name * Ability to search for a contact by a specific booking reference * Ability to search for a contact who has a specific voucher code assigned # Search PoPs by contact Search for specified PoPs for a contact record, within a defined date range. The get PoP by date will allow you to see all PoPs for a specific contact, and the associated Purchase, Booking, WIFI interaction details. ## Configuration {% tabs %} {% tab title="GET" %} ``` https://api.airship.co.uk/v1/pop/by_date ``` {% endtab %} {% endtabs %} #### Headers
FieldNotes
Authentication (bearer token)The authentication token is linked to the account that you are searching bookings in. If you are unsure of what your Authentication token is, ask our support team to confirm.
#### Body
FieldNotes
account_idThe account ID represents the account that you are searching bookings in. If you are unsure of what your account ID is, ask our support team to confirm.
contact_idContact ID which you want to perform a PoP Search on
start_dateStart date to search for a PoP

Required
end_dateEnd date to search for a PoP

Required
typesArray of PoP types, you can add;

- purchases
- wifi
- booking

Required
### Example request {% tabs %} {% tab title="Request" %} ```json { "account_id": 2, "contact_id": 90357243, "start_date": "2023-01-03", "end_date": "2023-09-03", "types" : ["purchases", "booking", "wifi"] } ``` {% endtab %} {% tab title="Response (200)" %} ```json { "purchases": [ { "transaction_lines": [ { "id": 21811807, "description": "TYRRELLS SEA SALT &", "sku": "8507", "quantity": "-1", "value": "1.29" }, { "id": 21811808, "description": "LATTE REGULAR 12oz", "sku": "3001", "quantity": "1", "value": "3.00" } ], "unit_name": "The shack", "id": 4753469, "contact_id": "90357243", "transaction_reference": "wqeqweqeqw-1c96-44fd-bc98-4dab1248ebd2", "unit_id": "13835", "provider_id": "1", "order_type_id": "1", "transaction_date": "2023-07-04 12:11:58" } ], "booking": { "current_page": 1, "data": [], "first_page_url": "https://api.airship.co.uk/v1/pop/by_date?page=1", "from": null, "last_page": 1, "last_page_url": "https://api.airship.co.uk/v1/pop/by_date?page=1", "next_page_url": null, "path": "https://api.airship.co.uk/v1/pop/by_date", "per_page": 100, "prev_page_url": null, "to": null, "total": 0 }, "wifi": { "current_page": 1, "data": [], "first_page_url": "https://api.airship.co.uk/v1/pop/by_date?page=1", "from": null, "last_page": 1, "last_page_url": "https://api.airship.co.uk/v1/pop/by_date?page=1", "next_page_url": null, "path": "https://api.airship.co.uk/v1/pop/by_date", "per_page": 100, "prev_page_url": null, "to": null, "total": 0 } } ``` {% endtab %} {% tab title="Response (422)" %} ```json { "message": "The given data was invalid.", "errors": { "contact_id": [ "This contact does not belong to this account" ] } } ``` {% endtab %} {% endtabs %} The results will return the PoPs by type, in an array if there are more than 1 interaction within that range # Search contact by Email, Mobile, Name ### Overview Any active contact within an Airship account can searched for, and returned via the REST API. This allows third parties to identify contact details based on a key identifier, if multiple contacts exist against a query (i.e. Name = John Smith), then an array of contacts will be returned in the response. All queries by Email or Mobile will only return a single result, as they are unique in an account. ### Example Request {% tabs %} {% tab title="GET" %} ``` https://api.airship.co.uk/v1/contacts ``` {% endtab %} {% endtabs %} ### Configuration #### Headers | Field | Notes | | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `Authentication` (bearer token) | The authentication token is linked to the account that you are searching bookings in. If you are unsure of what your Authentication token is, ask our support team to confirm. | #### Body | Field | Notes | | ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | | `account_id` | The account ID represents the account that you are searching bookings in. If you are unsure of what your account ID is, ask our support team to confirm. | | `email` | Email address of contact you are searching for | | `mobile_number` | Mobile number of contact you are searching for | | `name (first_name / last_name)` | First / last name of contact you are searching for | ### **Basic payload example** #### Email search Contacts can be searched for by email address, there is some basic regex validation on the email to ensure it is in a valid format. {% tabs %} {% tab title="Request" %} ```json { "account_id": 3, "email": "john.smith@airship.co.uk" } ``` {% endtab %} {% tab title="200 Response" %} ```json { "allow_sms": false, "allow_email": true, "allow_call": false, "allow_snail_mail": false, "udfs": [], "units": [ { "id": 14458, "name": "Head Office", "groups": [ { "id": 126832, "name": "Football visitor" }, { "id": 126842, "name": "Christmas Competition entry" } ] }, { "id": 14478, "name": "London venue", "groups": [ { "id": 126778, "name": "WIFI" } ] } ], "feedback": "https://api.airship.co.uk/v1/contact/51616336/feedback", "bookings": "https://api.airship.co.uk/v1/contact/51616336/bookings", "purchases": "https://api.airship.co.uk/v1/contact/51616336/purchases", "proof_of_presence": "https://api.airship.co.uk/v1/contact/51616336/pops", "id": 51616336, "gender": "M", "title": "Mr", "first_name": "John", "last_name": "Smith", "dob": "1984-11-27", "building_name": "", "building_num_street": "2 Test Way", "locality": "", "postcode": "L1 1AA", "city": "London", "country": "United Kingdom", "county": "", "mobile_number": "447816000001", "home_number": "", "preferred_method_id": "0", "work_number": "", "email": "John.Smith@airship.co.uk", "source_id": "134747", "membership_number": "", "membership_type": "" } ``` {% endtab %} {% tab title="422 Response" %} A 422 response can be given in the following scenarios; 1. Account ID is incorrect ```json { "message": "The given data was invalid.", "errors": { "account_id": [ "You do not have access to this account" ] } } ``` 2\. Invalid email address ```json { "message": "The given data was invalid.", "errors": { "email": [ "test.test@airship is not a valid email address" ] } } ``` {% endtab %} {% endtabs %} #### Mobile search Contacts can be searched for by Mobile number. All mobile numbers are stored in Airship with the country code (447....), and the API will automatically add this when you pass in a value. {% tabs %} {% tab title="Request" %} ```json { "account_id": 3, "mobile_number": "447810000001" } ``` {% endtab %} {% tab title="200 Response" %} ```json { "allow_sms": false, "allow_email": true, "allow_call": false, "allow_snail_mail": false, "udfs": [], "units": [ { "id": 14458, "name": "Head Office", "groups": [ { "id": 126832, "name": "Football visitor" }, { "id": 126842, "name": "Christmas Competition entry" } ] }, { "id": 14478, "name": "London venue", "groups": [ { "id": 126778, "name": "WIFI" } ] } ], "feedback": "https://api.airship.co.uk/v1/contact/51616336/feedback", "bookings": "https://api.airship.co.uk/v1/contact/51616336/bookings", "purchases": "https://api.airship.co.uk/v1/contact/51616336/purchases", "proof_of_presence": "https://api.airship.co.uk/v1/contact/51616336/pops", "id": 51616336, "gender": "M", "title": "Mr", "first_name": "John", "last_name": "Smith", "dob": "1984-11-27", "building_name": "", "building_num_street": "2 Test Way", "locality": "", "postcode": "L1 1AA", "city": "London", "country": "United Kingdom", "county": "", "mobile_number": "447816000001", "home_number": "", "preferred_method_id": "0", "work_number": "", "email": "John.Smith@airship.co.uk", "source_id": "134747", "membership_number": "", "membership_type": "" } ``` {% endtab %} {% tab title="422 Response" %} A 422 response can be given in the following scenarios; 1. Account ID is incorrect ```json { "message": "The given data was invalid.", "errors": { "account_id": [ "You do not have access to this account" ] } } ``` 2. Invalid mobile number ```json { "message": "The given data was invalid.", "errors": { "phone": [ "The phone must be at least 10 characters." ] } } ``` {% endtab %} {% endtabs %} #### Name search A contact can be searched for by; * First name * Surname If either of these are left blank (i.e. just John searched for), an array of contacts matching that will be returned. {% tabs %} {% tab title="Request" %} ```json { "account_id": 3, "name": { "first_name": "John", "last_name": "Smith" } } ``` {% endtab %} {% tab title="200 Response" %} ```json { "allow_sms": false, "allow_email": true, "allow_call": false, "allow_snail_mail": false, "udfs": [], "units": [ { "id": 14458, "name": "Head Office", "groups": [ { "id": 126832, "name": "Football visitor" }, { "id": 126842, "name": "Christmas Competition entry" } ] }, { "id": 14478, "name": "London venue", "groups": [ { "id": 126778, "name": "WIFI" } ] } ], "feedback": "https://api.airship.co.uk/v1/contact/51616336/feedback", "bookings": "https://api.airship.co.uk/v1/contact/51616336/bookings", "purchases": "https://api.airship.co.uk/v1/contact/51616336/purchases", "proof_of_presence": "https://api.airship.co.uk/v1/contact/51616336/pops", "id": 51616336, "gender": "M", "title": "Mr", "first_name": "John", "last_name": "Smith", "dob": "1984-11-27", "building_name": "", "building_num_street": "2 Test Way", "locality": "", "postcode": "L1 1AA", "city": "London", "country": "United Kingdom", "county": "", "mobile_number": "447816000001", "home_number": "", "preferred_method_id": "0", "work_number": "", "email": "John.Smith@airship.co.uk", "source_id": "134747", "membership_number": "", "membership_type": "" } ``` {% endtab %} {% tab title="422 Response" %} 1. Account ID is incorrect ```json { "message": "The given data was invalid.", "errors": { "account_id": [ "You do not have access to this account" ] } } ``` {% endtab %} {% endtabs %} # Search contact by voucher ### Overview Any contact that has a unique voucher code assigned can be searched for using the get /Contact endpoint. An account ID, voucher code and voucher code group must be provided to ensure the relevant contact is returned. This is currently used to identify a contact by a unique voucher code, and the POS / Order and pay provider will then apply a basket to that contact using the [Append booking data](/basics/contacts/append-booking-data) ### Example Request {% tabs %} {% tab title="GET" %} ``` https://api.airship.co.uk/v1/contacts ``` {% endtab %} {% endtabs %} ### Configuration #### Headers | Field | Notes | | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `Authentication` (bearer token) | The authentication token is linked to the account that you are searching bookings in. If you are unsure of what your Authentication token is, ask our support team to confirm. | #### Body | Field | Notes | | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `account_id` | The account ID represents the account that you are searching bookings in. If you are unsure of what your account ID is, ask our support team to confirm. | | `code` | The unique voucher code which you are searching for. | | `ucgid` | The unique voucher code group which the voucher is associated with. As the same voucher code can exist in different code groups (be issued in different campaigns at different points in time) - the ucgid enables us to narrow down which code is being searched for. | ### **Basic payload example** {% tabs %} {% tab title="Request" %} ```json { "account_id": 2, "voucher_code_data": { "code": "PL1022393E", "ucgid": 523 } } ``` {% endtab %} {% tab title="200 Response" %} ```json { "allow_sms": false, "allow_email": true, "allow_call": false, "allow_snail_mail": false, "udfs": [], "units": [ { "id": 14458, "name": "Head Office", "groups": [ { "id": 126832, "name": "Football visitor" }, { "id": 126842, "name": "Christmas Competition entry" } ] }, { "id": 14478, "name": "London venue", "groups": [ { "id": 126778, "name": "WIFI" } ] } ], "feedback": "https://api.airship.co.uk/v1/contact/51616336/feedback", "bookings": "https://api.airship.co.uk/v1/contact/51616336/bookings", "purchases": "https://api.airship.co.uk/v1/contact/51616336/purchases", "proof_of_presence": "https://api.airship.co.uk/v1/contact/51616336/pops", "id": 51616336, "gender": "M", "title": "Mr", "first_name": "John", "last_name": "Smith", "dob": "1984-11-27", "building_name": "", "building_num_street": "2 Test Way", "locality": "", "postcode": "L1 1AA", "city": "London", "country": "United Kingdom", "county": "", "mobile_number": "447816000001", "home_number": "", "preferred_method_id": "0", "work_number": "", "email": "John.Smith@airship.co.uk", "source_id": "134747", "membership_number": "", "membership_type": "" } ``` {% endtab %} {% tab title="422 Response" %} A 422 response can be given in the following scenarios; 1. Account ID is incorrect ```json { "message": "The given data was invalid.", "errors": { "account_id": [ "You do not have access to this account" ] } } ``` 2\. Unique code group ID is incorrect ```json { "message": "The given data was invalid.", "errors": { "ucgid": [ "This ucgid does not exist" ] } } ``` {% endtab %} {% endtabs %} # Vouchers Airship has the ability to store and generate unique vouchers, associate them to a contact and act as a gatekeeper for if a voucher is active, or has been redeemed. Airships APIs allows partners (typically POS) to; * Create unique code groups * Check the status of a voucher code * Redeem a voucher code Vouchers are contained in Unique Code Groups - Which is a collection of vouchers for a single purpose - I.e. a specific offer might be for a 'Free cup of coffee' - in which case a Unique Code Group will be created for that offer and all the relevant vouchers generated within that group. When a partner attempts to check the status, or redeem a voucher code - The clients Account ID and Unique Code Group ID must be provided to Airship so the correct voucher is validated # Redeem voucher code ### Overview In the scenarios where Airship is the gatekeeper for voucher codes, an unredeemed single use voucher can be marked as 'Redeemed' within Airship, so any subsequent [Voucher Checks](/basics/vouchers/check-voucher-code) return the status of 'Redeemed', or attempted Redemptions return an 'Already Redeemed' style message. ### Example Request {% tabs %} {% tab title="POST" %} ``` https://api.airship.co.uk/v1/unique_code/redeem ``` {% endtab %} {% endtabs %} ### Configuration #### Headers | Field | Notes | | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `Authentication` (bearer token) | The authentication token is linked to the account that you are searching bookings in. If you are unsure of what your Authentication token is, ask our support team to confirm. | #### Body | Field | Notes | | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `account_id` | The account ID represents the account that you are searching bookings in. If you are unsure of what your account ID is, ask our support team to confirm. | | `unit_id` | Airship has predefined locations or "units" to store contacts for different physical locations. The units object represents which location which the voucher code was redeemed at. You can fetch a list of units for your account using the `account/units`endpoint. | | `unique_code_group_id` |

Optional (providing the voucher codes are set to unique by account within Airship)

The unique voucher code group which the voucher is associated with. As the same voucher code can exist in different code groups (be issued in different campaigns at different points in time) - the UCGID enables us to narrow down which campaign the voucher belongs to when codes are not unique by account.

| | `unique_code` | The unique voucher code which you are attempting to redeem. | | `redemption_date` |

Optional

The date time that the voucher was redeemed. If this is not included, the current date time of the request will be used

| ### Basic Payload example {% tabs %} {% tab title="Request" %} ```json { "account_id": 2, "unit_id": 10252, "unique_code_group_id": 44125, "unique_code": "AB03-23RTT0", "redemption_date": "2022-07-13 12:30:04" } ``` {% endtab %} {% tab title="200 Response" %} ```json { "id": 62123846, "unique_code": "AB03-23RTT0", "unique_code_group_id": "44125", "contact_id": "5162520", "redeemed_at_unit_id": 10252, "redeemed_at_datetime": "2021-11-02T16:29:05.558280Z", "unique_code_status": "Redeemed" } ``` {% endtab %} {% tab title="422 Response" %} 1. Voucher already redeemed ```json { "message": "The given data was invalid.", "errors": { "unique_code": [ "This unique code has already been redeemeed." ] } } ``` 2\. Invalid Unit ID ```json { "message": "The given data was invalid.", "errors": { "unit_id": [ "Unit ID 5234 does not exist or has been deleted on this account" ] } } ``` 3\. Invalid Unique Code Group ID ```json { "message": "The given data was invalid.", "errors": { "unique_code_group_id": [ "This unique code group id doesn't exist" ] } } ``` 4\. Invalid account ID ```json { "message": "The given data was invalid.", "errors": { "account_id": [ "You do not have access to this account" ] } } ``` {% endtab %} {% endtabs %} ### Results Once a voucher has successfully been redeemed, if it is assigned to a contact - then you will be able to check if the voucher has been redeemed in Airship. ![](/files/xqBrh6hR7QTHlTNhhm4g) Once a voucher is redeemed, you should see the Redemption date (based on the date/time the call was made) and Redeemed at unit populated (based on the Unit ID provided in the redemption call). # Check voucher code ### Overview A vouchers current status can be checked within Airship. This will return the following information: * Contact id associated * Redemption unit (if redeemed) * Redemption date/time (if redeemed) * Status; * "Active" (not yet redeemed) * "Redeemed" ### Example Request {% tabs %} {% tab title="GET" %} ```json https://api.airship.co.uk/v1/unique_code ``` {% endtab %} {% endtabs %} ### Configuration #### Headers | Field | Notes | | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `Authentication` (bearer token) | The authentication token is linked to the account that you are searching bookings in. If you are unsure of what your Authentication token is, ask our support team to confirm. | #### Body | Field | Notes | | ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `account_id` | The account ID represents the account that you are searching bookings in. If you are unsure of what your account ID is, ask our support team to confirm. | | `unique_code` | The unique voucher code which you are searching for. | | `unique_code_group_id` | The unique voucher code group which the voucher is associated with. As the same voucher code can exist in different code groups (be issued in different campaigns at different points in time) - the ucgid enables us to narrow down which code is being searched for. | ### Basic Payload example {% tabs %} {% tab title="Request" %} ```json { "account_id": 2, "unique_code": "AB9201E11", "unique_code_group_id": 14252 } ``` {% endtab %} {% tab title="200 Response" %} 1. Code Active ```json { "id": 62123810, "unique_code": "AB9201E11", "unique_code_group_id": "14252", "contact_id": "51626835", "redeemed_at_unit_id": "0", "redeemed_at_datetime": "0000-00-00 00:00:00", "unique_code_status": "Active" } ``` 2\. Code redeemed ```json { "id": 62123810, "unique_code": "AB9201E11", "unique_code_group_id": "14252", "contact_id": "51626835", "redeemed_at_unit_id": "14458", "redeemed_at_datetime": "2021-11-02 10:12:26", "unique_code_status": "Redeemed" } ``` {% endtab %} {% tab title="422 Response" %} 1. Invalid Unique Code Group ID ```json { "message": "The given data was invalid.", "errors": { "unique_code_group_id": [ "This unique code group id doesn't exist" ] } } ``` 2\. Invalid Unique Code ```json { "message": "The given data was invalid.", "errors": { "unique_code": [ "This unique code doesn't exist" ] } } ``` 3\. Invalid Account ID ```json { "message": "The given data was invalid.", "errors": { "account_id": [ "You do not have access to this account" ] } } ``` {% endtab %} {% endtabs %} # Create Unique Code Group ### Overview Unique Code Groups are containers for vouchers, they are typically related to a specific campaign or promotion and the group will contain all unique voucher codes for that specific campaign or promotion. When creating a unique code group, no unique vouchers will be generated. This is a manual process that will require Airship customer success to generate them. ### Example Request {% tabs %} {% tab title="POST" %} ``` https://api.airship.co.uk/v1/unique_code/group ``` {% endtab %} {% endtabs %} ### Configuration #### Headers | Field | Notes | | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `Authentication` (bearer token) | The authentication token is linked to the account that you are searching bookings in. If you are unsure of what your Authentication token is, ask our support team to confirm. | #### Body | Field | Notes | | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `account_id` |

The account ID represents the account that you are searching bookings in. If you are unsure of what your account ID is, ask our support team to confirm.

| | `unit_id` |

Airship has predefined locations or "units" to store contacts for different physical locations. The units object represents which location which the voucher code group to be created against. You can fetch a list of units for your account using the account/unitsendpoint.

Typically code groups are created against the Head Office account, but check with Airship Customer Services if you are unsure.

| | `name` | A text descriptive name is required against the code group. The unique code group name must be unique against the Account > Unit. An error will be returned if the group name already exists. | ### Example Payload {% tabs %} {% tab title="Request" %} ```json { "account_id": 2, "unit_id": 14212, "name": "test group" } ``` {% endtab %} {% tab title="200 Response" %} ```json { "id": 10616 } ``` {% endtab %} {% tab title="422 Response" %} 1. Duplicate group name ```json { "message": "The given data was invalid.", "errors": { "name": [ "Sorry, You've all ready used this name on another unique code group in this unit." ] } } ``` 2\. Invalid unit ID ```json { "message": "The given data was invalid.", "errors": { "unit_id": [ "Unit ID 2 does not exist or has been deleted on this account" ], "name": [ "In order to add a name the unit id must also be correct" ] } } ``` 3\. Invalid account ID ```json { "message": "The given data was invalid.", "errors": { "account_id": [ "You do not have access to this account" ] } } ``` {% endtab %} {% endtabs %} # Anonymous purchase data Working with anonymous basket data in Airship Contacts are core to Airship, but we also collect a large amount of data from other sources which are associated to the contact. We can use that additional information to act as a unique identifier for the contact, so if we see some data from another source (i.e. Purchase data), which has a unique voucher code associated, providing airship issued that voucher, we can use this to tie the transaction back to the customer from the POS. Fields we can use to associate purchase information to a contact include; * Booking reference * Loyalty Card number / Loyalty Membership reference * Gift card number * Unique voucher code * Booking - Table number Depending on your POS, and its capability - not all of these touch points may be available to link to a customer. Airship will require at least 1 of the above in order to associate any purchase to a contact. # Add anonymous purchase data ### Endpoint ``` https://api.airship.co.uk/v1/purchases ``` ### Configuration Along with the account\_id, either the `booking_reference`, `unique_code`, `card_reference`, `membership_number` or `table_number` is required to associate a purchase to a contact. | Field | Notes | | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `account_id` |

Required

The account ID represents the account that you are storing this contact to. If you are unsure of what your account ID is, ask our support team to confirm

| | `booking_reference` | The unique booking reference associated to the purchase. | | `unique_code` | The unique voucher code used on the purchase. | | `unique_code_group_id` |

Optional
Airships unique code group ID associated to the voucher. If the client has re-useable vouchers codes (for different promotions) - this id is required to pass in a unique\_code.

| | `membership_number` | The customers loyalty / membership number used on the purchase. | | `card_reference` | The customers loyalty card number used on the purchase. | | `table_number` | The table number which the customer sat at\* | | `provider_id` | This is the partners ID to help identify the source of a purchase. If you need one creating, please contact , we'll get one added and provide you an ID | \*The table number has some additional checks in place within Airship. We will look for any customers from the booking integration who; * Has a booking * Had that table number associated in the booking extract * Had a booking seated date on the same day as the purchase date * Whose booking start time was within 3 hours of the purchase completed time Operationaly, this requires the customer to be seated at the table defined within the booking platform - or the booking platform to be updated with the seated table number to work. More detail on the purchases history which can be passed can be found [here](/basics/contacts/append-purchase-history). ### Basic payload example ```json { "account_id": 3, "booking_reference": "5G83-234G-23TG", "unique_code": "BD34G53", "unique_code_group_id": 45121, "membership_number": "76398763-42T", "card_reference": "1234abc5678", "table_number": "44", "purchases": [ { "transaction_reference": "77FF-24FF-234F-7", "unit_id": 8775, "provider_id": 2, "created_at": "2021-06-01 00:00:00", "items": [ { "description": "Bacon Cheeseburger", "sku": "abc_8913", "quantity": 1, "value": 7, "tags": [ "Burger", "Main course" ] }, { "description": "Garlic Bread", "sku": "5621", "quantity": 2, "value": 8.40, "tags": [ "Sides" ] } ] } ] } ``` # Units From the API, you are able to obtain a list of current active Units (venues / locations). The API user is linked to an Airship account, and all the units associated to that account will be returned, paginated in the response. ### **Endpoint** {% tabs %} {% tab title="GET" %} ``` https://api.airship.co.uk/v1/account/units ``` {% endtab %} {% endtabs %} ### Query parameters | Parameter | Type | Description | | --------- | ------- | ------------------------------------------------------------------ | | `groups` | boolean | Optional. Set to `true` to include each unit's folders and groups. | Use `?groups=true` to return folder IDs and names. Each folder includes its group IDs and names. ### Response **Fields**
FieldNotes
id
Airships unique unit ID for the unit. It is required when sending Airship data
name
The unit name
is_root
Each Airship account has a 'root' account (typically named Head Office) - this is used for data that can't be associated with a specific location. Only 1 root account can be setup for each account, and is identified by this flag
#### Fields returned with `groups=true` | Field | Notes | | ------------------------- | ----------------------------------------------------- | | `folders` | The unit's folders. Returned only when `groups=true`. | | `folders[].id` | Airship's unique folder ID. | | `folders[].name` | The folder name. | | `folders[].groups` | Groups within the folder. | | `folders[].groups[].id` | Airship's unique group ID. | | `folders[].groups[].name` | The group name. | #### Example response ```json { "current_page": 1, "data": [ { "id": 13822, "name": "Head Office", "is_root": true }, { "id": 13835, "name": "Sheffield Pizza Place", "is_root": false } ], "first_page_url": "https://api.airship.co.uk/v1/account/units?page=1", "from": 1, "last_page": 1, "last_page_url": "https://api.airship.co.uk/v1/account/units?page=1", "next_page_url": null, "path": "https://api.airship.co.uk/v1/account/units", "per_page": 100, "prev_page_url": null, "to": 2, "total": 2 } ``` #### Example response with groups ```json { "data": [ { "id": 2251799825000010, "name": "Sheffield Pizza Place", "is_root": false, "deleted": "N", "folders": [ { "id": 2251799825000076, "name": "Default", "groups": [ { "id": 2251799825000819, "name": "Default" }, { "id": 1125899918001338, "name": "Tables Bookings" } ] }, { "id": 1125899918000104, "name": "Airship signup forms", "groups": [ { "id": 1125899918001339, "name": "Enquiry - Hotel stay" } ] } ] } ] } ``` # Postman collection Get started with our Postman collection You can download a Postman collection with some example requests at the link below. {% hint style="success" %} [Download Postman collection >](https://api.postman.com/collections/7822542-f6aa1d2d-b6bd-4be9-9e03-0d69a37881fa?access_key=PMAT-01GP16QBKCTN14K6FGJ169E0EV) {% endhint %} # Overview {% hint style="warning" %} #### Have you considered using our REST API? While our SOAP API remains fully supported and operational, we recommend all new integrations use our newer REST API. {% endhint %} ### Introduction to SOAP We have a fully featured SOAP API which is in use across hundreds accounts. The Airship SOAP API supports operations for writing contact and transactional data to Airship and much much more. ### Getting started Before you begin, you must have: * An Airship dashboard account * SOAP authentication credentials * An Airship dashboard user account ### SOAP API Reference Our SOAP API is published as a downloadable PDF. [Download our SOAP API reference >](https://www.airship.co.uk/docs/Airship_SOAP_API_V3.pdf) ### Test API credentials To aid your development and testing, we create full ‘test’ Airship accounts. This allows you to carry out your integration in an environment that is not associated with live data. Any credentials provided for test use are kept separate to credentials for production use. Please request a test development account from our support team. ### Test dashboard access Separately to the SOAP credentials, we also issue Airship dashboard user accounts on an individual basis. As a developer, you will be provided with a dashboard user account that is assigned with a ‘developer’ role, with the permission to access the following Console interfaces: * Ability to search for your contact record * Ability to view your contact record and edit it Follow the [Activating your Airship account](http://academy.airship.co.uk/en/articles/1946745-activating-your-airship-account) article to get started.