Event Tickets

Event tickets in Reach are different from most other pass types. This document covers information specific to events and event tickets.

While you can create and modify event ticket templates from the dashboard, you must perform all other operations — creating and modifying events, creating adaptive links with event and attendee information, etc. — through the API. See the Event API and Multiple Adaptive Links API for a complete reference of methods and payloads.

Event Ticket Composition

An event ticket is an adaptive link 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.

  1. Event ticket templates are referenced by ID in the adaptive link payload. You must provide at least one iOS or Android template.

  2. The adaptive link payload references an eventId, eventExternalId, or contains a complete event object.

  3. Each event in an event ticket adaptive link request includes an array of attendees. The endpoint generates an adaptive link for each attendee.

  4. 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

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.

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"
    }
  }
}

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.

Attendees

The attendees array appears within an individual event object when creating event ticket adaptive links. Each object in the array represents an individual attendee; each attendee gets their own adaptive link.

Example Passenger Array:

{
  "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" }
        }
     }
  ]
}

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, ranges 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.

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.

Adaptive Links for Event Tickets

Note

You must use the /links/adaptive/multiple/project/' endpoints 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.

An event ticket adaptive link is an adaptive link that generates or returns platform-appropriate passes of the eventTicket type. It is created from event ticket templates and associated with events and attendees.

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 event ticket 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 flight using the /v1/events endpoint or provided all flight information directly in an adaptive link 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/id/ {adaptiveLinkExternalId}. A POST call that specifies an existing adaptiveLinkExternalId is treated as a PUT and updates the adaptive link accordingly. You cannot do the same with the standard adaptiveLinkId. Therefore, you should expect to set external IDs for each attendee in your request.

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.