Event Tickets

Event tickets in a mobile wallet project are different from most other pass types. This document covers information specific to setting up events and issuing adaptive links for event tickets.

While you can create and modify event ticket templates from the mobile wallet dashboard, you must perform all other operations — creating and modifying events, creating adaptive linksA vendor-agnostic, shortened mobile wallet pass link that supports templates for both Google Wallet and Apple Wallet. When a user taps the link, Airship determines the user’s platform and generates the right pass for that platform. with event and attendee information, etc. — through the API. See the Events API and Multiple Adaptive Links APIs for a complete reference of methods and payloads.

Event Ticket Composition

An event ticket is an Adaptive LinkA vendor-agnostic, shortened mobile wallet pass link that supports templates for both Google Wallet and Apple Wallet. When a user taps the link, Airship determines the user’s platform and generates the right pass for that platform. that references an event ticket template populated with one or more events and an array of attendees per ticket.

Because of the specific event and attendee information required for each event ticket, you cannot create event tickets using the standard dashboard or /links/adaptive methods. You must use the /links/adaptive/multiple/project endpoint instead.

An event ticket works like a standard adaptive link, with the following differences.

Event ticket templates are referenced by ID. You must provide at least one iOS or Android template ID in the adaptive link payload.
The adaptive link payload references an eventId, eventExternalId, or contains a complete event object.
Each event in an event ticket adaptive link request includes an array of attendees. The endpoint generates an adaptive link for each attendee.
Assets referenced by ID (templates, events, etc.) must belong to the same project; you cannot specify events or templates belonging to different projects when creating an event ticket.

Events

An Event is the part of an event ticket representing the venue and times of an event. You can make changes to an event to easily update passes for attendees. You can create events either:

Using the POST method for the /events endpoint.
By providing an event payload when creating adaptive links.

In both cases, the result of your request is an eventId or eventExternalIdthat you can use to reference the event. After you create an event, you can modify it from the /events endpoint. Any changes you make — moving the venue, pushing back event times, etc. — automatically propagate to event tickets (adaptive links) that reference the event.

The example below represents a single baseball game that you can use when generating tickets for attendees. You can edit the event to update the passes of all attendees.

Event request example

POST /v1/events/project/<projectExternalId>/id/<eventExternalId> HTTP/1.1
Authorization: Basic <authorization string>
Content-Type: application/json

{
  "fields": {
    "eventName": {
      "label": "Event",
      "value": "LA Dodgers at SF Giants"
    },
    "venueTitle": {
      "label": "Venue",
      "value": "AT&T Park"
    },
    "venueAddress": {
      "label": "Address",
      "value": "24 Willie Mays Plaza\nSan Francisco, CA 94107"
    },
    "doorsOpen": {
      "label": "Doors Open",
      "value": "2019-09-25T08:35:00"
    },
    "startTime": {
      "label": "Start Time",
      "value": "2019-09-25T09:00:00"
    },
    "endTime": {
      "label": "End Time",
      "value": "2019-09-25T11:00:00"
    }
  },
  "passGroups": ["giants_2019-09-25"]
}

External IDs for Events

You can create an event with a custom identifier using the /v1/events/project/id/{projectExternalId}/id/{eventExternalId} endpoint or by providing an eventExternalId when you provide an event object as a part of an adaptive link request. A request specifying an external event ID returns the custom identifier as eventExternalId, which you can use to reference events in lieu of the standard eventId in subsequent payloads, including the request to create event ticket adaptive links.

Pass Groups for Events

You can group events together, so that you can modify multiple events simultaneously — something you might need to do for multiple events at the same venue, e.g., a concert with a backstage pass, baseball game with a pre-game or field-level event, etc.

To do this, you can assign eventsThe part of an event ticket representing the venue and times of an event. You can make changes to an event to easily update passes for attendees. to passGroups — plain text strings, similar to tags for passes. You can assign pass groups in any payload where you create an event or after you create an event using /passgroups endpoints.

Add a pass group to an existing event with an external ID

POST /v1/events/project/id/<projectExternalId>/id/<eventExternalId>/passGroups HTTP/1.1
Authorization: Basic <authorization string>
Content-Type: application/json

{
   "passGroups": [
         "giants_2019-09-25"
   ]
}

You can get a list of, or modify, all the events belonging to a passGroup. When you modify a pass group, you only need to provide the individual fields that you want to update for all events in the pass group. Any passes generated from events in the group are automatically updated accordingly.

Update all events in a pass group

PUT /v1/events/project/12345/passGroups/giants_2019-09-25 HTTP/1.1
Authorization: Basic <authorization string>
Content-Type: application/json

{
   "fields": {
      "venueTitle": {
         "value": "Oracle Park"
      }
   }
}

Attendees

The attendees array represents pass holders. Each object in the array represents an individual attendee and results in an individual adaptive link.

The attendees array appears within an event object when creating event ticket adaptive links.

Example event ticket with attendee array

{
   "iosTemplateExternalId": "giantsBaseballTicket-ios",
   "androidTemplateExternalId": "giantsBaseballTicket-android",
   "payload":{
      "events":[
         {
            "eventExternalId": "dodgersAtGiants-2019-09-25",
            "attendees":[
               {
                  "adaptiveLinkExternalId": "<adaptiveLinkExternalId1>",
                  "fields":{
                     "ticketHolderName": { "label": "Name", "value":"SMITH/JOE" },
                     "seat": { "value":"33" },
                     "ticketType": { "value":"VIP" },
                     "barcode_value": { "value": "1234" },
                     "barcodeAltText": { "value": "1234" },
                     "faceValue": { "value": "50" }
                  }
               }
            ]
         }
      ]
   }
}

Google Wallet Event Ticket Templates

Event ticket templates are not as customizable as other template types. Many of the fields on an event ticket adaptive link are required and cannot be moved or customized in any way.

You can set colors, logos, and otherwise customize the general feel of your event tickets. But event tickets templates take a defined set of information (from both events and attendees) and do not offer as much variance as other pass types that take a wider and more customizable range of information.

In the dashboard template editor, you can provide sample event data to test the look and feel of your pass. The event data you fill out in the template editor is purely an example to help you visualize your event ticket. It is not saved as an event or used when creating event tickets.

Important

The event information you enter when creating your template is only to help you design your template and send test passes; it is overwritten by a event object when you create event tickets. See the Event Ticket Request object for information about the event object or ID you must provide when creating passes.

Note

In general, you should set set ignoresTimeZone: true for template fields that take date-time values. Event dates and times are typically UTC local to the venue; setting ignoresTimeZone: true prevents Apple Wallet from modifying times based on the time zones of attendees’ devices.

Apple Wallet Event Ticket Templates

While event and attendee fields are native to Google Wallet templates, they are not native to Apple Wallet templates. You must name fields on your Apple Wallet template according to the event and attendee schemas to support event ticket adaptive links. See Event Ticket Objects for a complete list of the field names your template should use.

If you create your Apple Wallet event ticket template through the dashboard, you must rename fields on your template to match event and attendee object fields through the API.
If you create your Apple Wallet event ticket template through the API, you must name fields identically to event and attendee objects.

Example default Apple Wallet field names and supported event ticket equivalents:

Default field name	Rename field to
`Seat`	`seat`
`Row`	`row`
`Vendor Name`	`venueTitle`
`Section`	`section`
`Ticket Details`	`finePrint`
`Location`	`venueAddress`

Important

Adaptive Links for Event Tickets

Event ticket adaptive links are adaptive link that generate or return platform-appropriate passes of the eventTicket type. They are created from event ticket templates and associated with events and attendees.

Note

You must use the /links/adaptive/multiple/project/ endpoint to create event tickets. While event ticket adaptive links have a similar request structure to other adaptive links, you cannot create event tickets through the standard /links/adaptive endpoint.

When you create an event ticket adaptive link, you can specify events by eventId (returned when creating an event), or you can create the event as a part of the adaptive link request. Creating an event as a part of an adaptive link request is the same as creating an event ticket through the /events endpoint: the adaptive link response will return an eventId or eventExternalId that you can use to reference or modify the event later on.

Note

Templates and events in an adaptive link payload must belong to the same project.

Within each event, you will specify attendees — an array of objects, each object representing an individual event ticket holder. In general, you should set an adaptiveLinkExternalId for each attendee. You will modify event ticket adaptive links with a POST to the /v1/links/adaptive/multiple/id/{adaptiveLinkExternalId} endpoint; you cannot modify an event with an adaptiveLinkId in the same way.

Example adaptive link request

POST /v1/links/adaptive/multiple/project/id/<projectExternalId> HTTP/1.1
Authorization: Basic <authorization string>
Content-Type: application/json

{
   "iosTemplateExternalId": "<iosTemplateExternalId>",
   "androidTemplateExternalId": "<androidTemplateExternalId>",
   "payload":{
      "events":[
         {
            "eventExternalId": "<eventExternalId1>",
            "fields":{
               "eventName": { "value":"LA Dodgers at SF Giants" },
               "venueTitle": { "value":"AT&T Park" },
               "venueAddress": { "label": "Address", "value":"24 Willie Mays Plaza\nSan Francisco, CA 94107" },
               "doorsOpen": { "label": "Doors Open", "value":"2019-09-25T08:35:00" },
               "startTime": { "label": "Start Time", "value":"2019-09-25T09:00:00" },
               "endTime": { "label": "End Time", "value":"2019-09-25T11:00:00" }
            },
            "attendees":[
               {
                  "adaptiveLinkExternalId": "<adaptiveLinkExternalId1>",
                  "fields":{
                     "ticketHolderName": { "label": "Name", "value":"SMITH/JOE" },
                     "seat": { "value":"33" },
                     "ticketType": { "value":"VIP" },
                     "barcode_value": { "value": "1234" },
                     "barcodeAltText": { "value": "1234" },
                     "faceValue": { "value": "50" }
                  }
               },
               {
                  "adaptiveLinkExternalId": "<adaptiveLinkExternalId2>",
                  "fields":{
                     "ticketHolderName": { "label": "Name", "value":"SMITH/SALLY" },
                     "seat": { "value":"34" },
                     "ticketType": { "value":"VIP" },
                     "barcode_value": { "value": "1235" },
                     "barcodeAltText": { "value": "1235" },
                     "faceValue": { "value": "50" }
                  }
               }
            ]
         }
      ]
   }
}

Adaptive link response

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

[
   {
      "adaptiveLinkId": "<uaAdaptiveLinkId1>",
      "adaptiveLinkExternalId": "<adaptiveLinkExternalId1>",
      "iosTemplateId": "iosTemplateId>",
      "iosTemplateExternalId": "<iosTemplateExternalId>",
      "androidTemplateId": "<androidTemplateId>",
      "androidTemplateExternalId": "<androidTemplateExternalId>",
      "eventId": 476,
      "eventExternalId": "<eventExternalId1>",
      "url": "https://wallet-api.urbanairship.com/v1/pass/<adaptiveLinkSerialNumber1>",
      "iosUrl": "https://wallet-api.urbanairship.com/v1/pass/<adaptiveLinkSerialNumber1>/ios",
      "androidUrl": "https://wallet-api.urbanairship.com/v1/pass/<adaptiveLinkSerialNumber1>/android",
      "createdAt": "2018-09-24T09:12:32Z",
      "updatedAt": "2018-09-24T09:15:32Z",
      "isPersonalized": "false",
      "availablePasses": 1000000,
      "iosPassLinkId": "a5711a29-7b38-41f2-8202-8f792df89b0b",
      "androidPassLinkId": "c1f512e5-fda3-4ddf-82c6-066c5681161d",
      "status": 200
   },
   {
      "adaptiveLinkId": "<uaAdaptiveLinkId2>",
      "adaptiveLinkExternalId": "<adaptiveLinkExternalId2>",
      "iosTemplateId": "iosTemplateId>",
      "iosTemplateExternalId": "<iosTemplateExternalId>",
      "androidTemplateId": "<androidTemplateId>",
      "androidTemplateExternalId": "<androidTemplateExternalId>",
      "eventId": 476,
      "eventExternalId": "<eventExternalId1>",
      "url": "https://wallet-api.urbanairship.com/v1/pass/<adaptiveLinkSerialNumber2>",
      "iosUrl": "https://wallet-api.urbanairship.com/v1/pass/<adaptiveLinkSerialNumber2>/ios",
      "androidUrl": "https://wallet-api.urbanairship.com/v1/pass/<adaptiveLinkSerialNumber2>/android",
      "createdAt": "2018-09-24T09:12:32Z",
      "updatedAt": "2018-09-24T09:15:32Z",
      "isPersonalized": "false",
      "availablePasses": 1000000,
      "iosPassLinkId": "a5711a29-7b38-41f2-8202-8f792df89b0b",
      "androidPassLinkId": "c1f512e5-fda3-4ddf-82c6-066c5681161d",
      "status": 200
   },
]

Modifying Events

Any endpoint you can provide an event payload to returns an eventId. You can look up, modify, or delete an event using its ID in the path of the /v1/events endpoint, regardless of whether you created the event using the /v1/events endpoint or provided all event information directly in an adaptive link payload.

If you assigned your events to Pass GroupsGroups of flights or events that you can modify in bulk. You can assign events or flights to one or more pass groups when you create them., you can target the pass group to modify a common field across multiple events in a group. For example, if you need to update venueTitle for a group of events, you could target the group and with a single update rather than updating each flight individually. When you update events in a pass group, event tickets associated with events in the group are updated accordingly.

Modify all events belonging to a pass group

PUT /v1/events/project/12345/passGroups/giants_2019-09-25 HTTP/1.1
Authorization: Basic <authorization string>
Content-Type: application/json

{
   "fields": {
      "venueTitle": {
         "value": "Oracle Park"
      }
   }
}

You can also modify an event while modifying corresponding event tickets, using a POST to /v1/links/adaptive/multiple/project/id/{externalProjectId}, specifying an existing event and existing adaptiveLinkExternalId values for the tickets you want to modify in the payload.

Modifying, Looking-up, and Deleting Event Tickets

Each attendee represents receives their own event ticket adaptive link. You can modify event ticket adaptive links using a POST to /v1/links/adaptive/multiple/project/id/{externalProjectId}, specifying an existing event and adaptiveLinkExternalId value for each event ticket you want to modify in the payload; Airship treats this call as a PUT and updates event tickets for the specified adaptive links. You cannot do the same with the standard adaptiveLinkId. Therefore, you should expect to set external IDs for your adaptive links.

You can look up and delete event ticket adaptive links using the standard GET and DELETE methods for the /v1/links/adaptive/{adaptiveLinkId} and /v1/links/adaptive/id/{adaptiveLinkExternalId} endpoints.

Feedback

Was this page helpful?