NAV Navbar
json

Introduction

Welcome to the AudienceView Professional API! You can use our API to access future event data and for creating a custom scanning application.

You can view JSON response examples in the dark area to the right.

Future Events API

This is a RESTful web service that takes in a client ID, which for [Client Name] is [Client ID] and returns a JSON string. The links below provide detail about each end point available.

For CORS access, your domain must be whitelisted. This API is accessible via HTTP or HTTPS. You must pass the AudienceView Professional Client ID in a header called "clientId".

Calendar Data

Description

Get future events for a given month week beginning and ending inclusize. If the month starts on a Wednesday, you will get Sunday through Tuesday of the previous month. If the month ends on a Wednesday, you will get Thursday through Saturday of the next month.

HTTP Requests

GET https://api.ovationtix.com/public/calendar/client(:clientId)

GET https://api.ovationtix.com/public/calendar/client(:clientId)/production(:productionId)

GET https://api.ovationtix.com/public/calendar/client(:clientId)/department(:departmentId)

clientId Is the AudienceView Professional client ID and is required. productionId Is the AudienceView Professional Production ID and is required when requesting events for a specific production. departmentId Is the AudienceView Professional Department ID and is required when requesting events for a specific department.

Example URLs

https://api.ovationtix.com/public/calendar/client(284)

https://api.ovationtix.com/public/calendar/client(284)/production(962459)

https://api.ovationtix.com/public/calendar/client(284)/department(1219)

Query Parameters

This is how the 'time' query parameter is generated

var d = new Date(2014, 11, 1, 0, 0, 0, 0);
var monthStartInMilliseconds = d.getTime();
Parameter Default Description
time null Should be set to midnight on the first day of the month being retrieved and formatted as milliseconds since epoch.
month null In conjuction with year, will provide data for the month and year specified.
year null In conjunction with month, will provide data for the month and year specified.

Response Body

PerformancesByDateDisplay Map

Response output example:

{  
    "serviceMessages":{  
        "errors":[  

        ],
        "warnings":[  

        ],
        "infoMessages":[  

        ],
        "allMessages":[  

        ]
    },
    "departmentId":null,
    "clientId":284,
    "clientName":"00-TestAccount",
    "clientActive":true,
    "errors":[  

    ],
    "warnings":[  

    ],
    "performancesByDateDisplay":{
        "2017-06-28":[{
            "performanceId":10145563,
            "performanceStart":1498669200000,
            "performanceDate":"06/28/2017",
            "performanceTime":"1:00 PM",
            "performanceTime24":"13:00:00",
            "performanceStartDate":"Wed, Jun 28, 2017 - 1:00 PM",
            "performanceSuperTitle":"Tom McNeal Far Far Away",
            "performanceSubTitle":"Far Away.......",
            "performanceNotes":"Performance specific notes",
            "availabilityCode":"A",
            "displayCode":"T",
            "productionId":962459,
            "productionName":"Far Far Away",
            "hasAvailableTickets":true,
            "tixRemaining":445,
            "customMessage":"",
            "noRemainingTicketsMessage":null,
            "shutoffHour":2.00,
            "shutoffHourMessage":null,
            "generalAdmission":true,
            "allDayEvent":false,
            "doorEntryStartDate":"01/17/2018",
            "doorEntryStartTime":"2:00 PM",
            "doorEntryEndDate":"01/17/2018",
            "doorEntryEndTime":"4:00 PM",
            "productionLogoLink":"https://web.ovationtix.com/trs/clientFile/303987",
            "productionDescription":"Some description of the entire run of the show",
            "departmentId":null,
            "departmentName":null,
            "performanceEntryTimes": [{
                "performanceEntryTimeId": 11,
                "entryTime": "14:45:00",
                "entryTimeFormatted": "2:45 PM",
                "entryTimeHour": "14",
                "entryTimeMinute": "45",
                "displaySoldOut": false
            }, {
                "performanceEntryTimeId": 12,
                "entryTime": "13:45:00",
                "entryTimeFormatted": "1:45 PM",
                "entryTimeHour": "13",
                "entryTimeMinute": "45",
                "displaySoldOut": false
            }]
        }]
    }
}
Key Value
Date Array of Performance Objects

Event Performance Object

Variable Type Nullable Description
performanceId Integer No AudienceView Professional Unique Performance Identifier
performanceStart Date No Epoch Date the performance starts (time zone agnostic)
performanceDate String No Date that the performance starts ("MM/dd/yyyy" - Java SimpleDateFormat)
performanceTime String No Time that the performance starts - ("h:mm a" - Java SimpleDateFormat)
performanceTime24 String No Time that the performance starts - ("HH:mm:ss" - Java SimpleDateFormat)
performanceStartDate String No Date and Time that the performance starts - ("EEE, MMM d, yyyy - h:mm a" - Java SimpleDateFormat)
performanceSuperTitle String Yes The super title of the performance (can be different from production supertitle)
performanceSubTitle String Yes The sub title of the performance (can be different from production subtitle)
performanceNotes String Yes Details about this specific performance of the run of the show
availabilityCode Char No See availability codes
displayCode Char No See display codes
productionId Integer No AudienceView Professional Unique Production Identifier
productionName String No Production Name as specified for display purposes
hasAvailableTickets Boolean No True if tickets for this performance are available, false otherwise.
tixRemaining Integer No Number of tickets still available for this performance (This number should NOT be displayed to consumers for security purposes).
customMessage String Yes Custom not available message. If and only if the Display Code is set to M, this message should be displayed.
noRemainingTicketsMessage String Yes If no tickets are available this is the message to display.
shutoffHour Double No Number of hours before show time that public ticket sales are turned off
shutoffHourMessage String Yes The message to display once public ticket sales are turned off
generalAdmission Boolean No General Admission flags tells you whether consumers will be delegated specific seats or if seating in each section is first come first serve. True is first come first serve. False is specific seating.
allDayEvent Boolean No If the performance does not have a start time it is an all day event
doorEntryStartDate String No If allDayEvent is true, this states when doors open for the event
doorEntryStartTime String No If allDayEvent is true, this states when doors open for the event
doorEntryEndDate String No If allDayEvent is true, this states when doors close for the event
doorEntryEndTime String No If allDayEvent is true, this states when doors close for the event
productionLogoLink String Yes The fully qualified URL to the series logo image
productionDescription String Yes The description for the entire run of the show
departmentId Integer Yes A grouping of productions
departmentName String Yes The name of a grouping of productions
performanceEntryTimes PerformanceEntryTime Yes A list of entry times for the performance

Event PerformanceEntryTime Object

Variable Type Nullable Description
performanceEntryTimeId Integer No The entry time identifier used by AudienceView Professional to display the output on the purchased ticket
entryTime String No The entry time formatted as "HH:mm:ss" - Java SimpleDateFormat
entryTimeFormatted String No The entry time formatted as "h:mm a" - Java SimpleDateFormat
entryTimeHour String No The entry time hour formmated as "H" - Java SimpleDateFormat
entryTimeMinute String No The entry time minute formatted as "m" - Java SimpleDateFormat
displaySoldOut Boolean No Whether this entry time should be displayed as sold out

Series Data

Description

Provides a list of all the available series/productions available in the future. If a series/production future performances, then it will be provided in the list returned by this call.

HTTP Requests

GET https://api.ovationtix.com/public/series/client(:clientId)

GET https://api.ovationtix.com/public/series/client(:clientId)/production(:productionId)

GET https://api.ovationtix.com/public/series/client(:clientId)/department(:departmentId)

clientId Is the AudienceView Professional client ID and is required. productionId Is the AudienceView Professional Production ID and is required when requesting events for a specific production. departmentId Is the AudienceView Professional Department ID and is required when requesting events for a specific department.

Example URLs

https://api.ovationtix.com/public/series/client(284)

https://api.ovationtix.com/public/series/client(284)/production(962459)

https://api.ovationtix.com/public/series/client(284)/department(1219)

Response Body

Series Information Object

Response output example:

{  
    "serviceMessages":{  
        "errors":[  

        ],
        "warnings":[  

        ],
        "infoMessages":[  

        ],
        "allMessages":[  

        ]
    },
    "departmentId":null,
    "clientId":284,
    "clientName":"00-TestAccount",
    "clientActive":true,
    "errors":[  

    ],
    "warnings":[  

    ],
    "seriesInformation":[{
        "productionId":942036,
        "productionName":"Rise of the Pandas",
        "productionStatus":"T",
        "productionStyle":0,
        "productionVenue":{  
            "name":"Jonas James",
            "location":"",
            "venuePhone":"",
            "transitInfo":"",
            "venueAddress":{  
                "city":"Redding",
                "country":"United States",
                "countryAbbreviation":"US",
                "line1":"55 Washington St",
                "line2":"",
                "state":"Connecticut",
                "stateAbbreviation":"CT",
                "zipcode":"06896"
            }
        },
        "hasAvailableTickets":true,
        "noRemainingMessage":"There are no tickets remaining for this event.",
        "shutoffHour":2.00,
        "shutoffHourMessage":"Web sales are closed for this event. However, tickets may still be available at the box office.",
        "seriesSuperTitle":"",
        "seriesSubTitle":"",
        "purchaseAlert":"",
        "productionDescription":"",
        "productionLogoClientFileId":263062,
        "productionLogoLink":"https://web.ovationtix.com/trs/clientFile/263062",
        "productionLogoAltName":null,
        "firstPerformanceDate":1433959200000,
        "lastPerformanceDate":1440705600000,
        "performanceIdIfOnlyOneEventAvailable":null,
        "showLinkToBuyTickets":true,
        "departmentId":null,
        "departmentName":null,
    }]
}
Variable Type Nullable Description
productionId Integer No Identifier for the series in AudienceView Professional
productionName String No The name of the series
productionStatus String No See production statuses
productionStyle Integer No Determines the color the series should have as a background. See production colors
productionVenue ProductionVenue Yes Details for the venue the series is located at
hasAvailableTickets Boolean No True if tickets for this performance are available, false otherwise.
noRemainingMessage String No The message to display if there are no tickets remaining
shutoffHour Double No 2.00
shutoffHourMessage String No The message to display if the performance is no longer available for purchase because the shutoff hour has past.
seriesSuperTitle String Yes The super title for the series
seriesSubTitle String Yes The sub title for the series
purchaseAlert String Yes A custom message to display if provided
productionDescription String Yes The description for this series
productionLogoClientFileId Integer Yes The AudienceView Professional client file identifier for this series, used in conjunction with productionLogoLink
productionLogoLink String Yes The fully qualified URL to the series logo image
productionLogoAltName String Yes The alternate name for this series. If not provided, use productionName
firstPerformanceDate Date No The first future performance available for this series
lastPerformanceDate Date No The last future performance available for this series
performanceIdIfOnlyOneEventAvailable Integer Yes If only one performance is available for the series, this provides the performance ID.
showLinkToBuyTickets Boolean No True if there is at least 1 future performance available to all or available to package holders.
departmentId Integer Yes A grouping of productions by the AudienceView Professional department
departmentName String Yes The name of a grouping of productions by the AudienceView Professional department

ProductionVenue Object

Variable Type Nullable Description
name String No The name of the venue
location String Yes A general location of the venue
venuePhone String Yes The phone number to contact the venue
transitInfo String Yes Details on how to get the venue
venueAddress VenueAddress Yes The address of the venue

VenueAddress Object

Variable Type Nullable Description
line1 String No Address line 1
line2 String No Address line 2
city String No City
state String No Full State Name
stateAbbreviation String Yes 2-digit code for the state
zipcode String No Zip code
country String No Full Country Name
countryAbbreviation String 2-digit code for the country

Events Data

Description

Provides a list of all future performances. This call will provide a comprehensive list of all future performances for the requested data.

HTTP Requests

GET https://api.ovationtix.com/public/events/client(:clientId)

GET https://api.ovationtix.com/public/events/client(:clientId)/production(:productionId)

GET https://api.ovationtix.com/public/events/client(:clientId)/department(:departmentId)

clientId Is the AudienceView Professional client ID and is required. productionId Is the AudienceView Professional Production ID and is required when requesting events for a specific production. departmentId Is the AudienceView Professional Department ID and is required when requesting events for a specific department.

Example URLs

https://api.ovationtix.com/public/events/client(284)

https://api.ovationtix.com/public/events/client(284)/production(962459)

https://api.ovationtix.com/public/events/client(284)/department(1219)

Response Body

Events Information Object

Response output example:

{
    "serviceMessages":{
        "errors":[  

        ],
        "warnings":[  

        ],
        "infoMessages":[  

        ],
        "allMessages":[  

        ]
    },
    "departmentId":null,
    "clientId":284,
    "clientName":"00-TestAccount",
    "clientActive":true,
    "errors":[  

    ],
    "warnings":[  

    ],
    "performances":[{
        "performanceId":10145563,
        "performanceStart":1498669200000,
        "performanceDate":"06/28/2017",
        "performanceTime":"1:00 PM",
        "performanceTime24":"13:00:00",
        "performanceStartDate":"Wed, Jun 28, 2017 - 1:00 PM",
        "performanceSuperTitle":"Tom McNeal Far Far Away",
        "performanceSubTitle":"Far Away.......",
        "performanceNotes":"Performance specific notes",
        "availabilityCode":"A",
        "displayCode":"T",
        "productionId":962459,
        "productionName":"Far Far Away",
        "hasAvailableTickets":true,
        "tixRemaining":445,
        "customMessage":"",
        "noRemainingTicketsMessage":null,
        "shutoffHour":2.00,
        "shutoffHourMessage":null,
        "generalAdmission":true,
        "allDayEvent":false,
        "doorEntryStartDate":"01/17/2018",
        "doorEntryStartTime":"2:00 PM",
        "doorEntryEndDate":"01/17/2018",
        "doorEntryEndTime":"4:00 PM",
        "productionLogoLink":"https://web.ovationtix.com/trs/clientFile/303987",
        "productionDescription":"Some description of the entire run of the show",
        "departmentId":null,
        "departmentName":null,
        "performanceEntryTimes": [{
            "performanceEntryTimeId": 11,
            "entryTime": "14:45:00",
            "entryTimeFormatted": "2:45 PM",
            "entryTimeHour": "14",
            "entryTimeMinute": "45",
            "displaySoldOut": false
        }, {
            "performanceEntryTimeId": 12,
            "entryTime": "13:45:00",
            "entryTimeFormatted": "1:45 PM",
            "entryTimeHour": "13",
            "entryTimeMinute": "45",
            "displaySoldOut": false
        }]
    }]
}
Variable Type Nullable Description
performanceId Integer No AudienceView Professional Unique Performance Identifier
performanceStart Date No Epoch Date the performance starts (time zone agnostic)
performanceDate String No Date that the performance starts (MM/dd/yyyy - Java SimpleDateFormat)
performanceTime String No Time that the performance starts - (h:mm a - Java SimpleDateFormat)
performanceTime24 String No Time that the performance starts - (HH:mm:ss - Java SimpleDateFormat)
performanceStartDate String No Date and Time that the performance starts - ("EEE, MMM d, yyyy - h:mm a" - Java SimpleDateFormat)
performanceSuperTitle String Yes The super title of the performance (can be different from production supertitle)
performanceSubTitle String Yes The sub title of the performance (can be different from production subtitle)
performanceNotes String Yes Details about this specific performance of the run of the show
availabilityCode Char No See availability codes
displayCode Char No See display codes
productionId Integer No AudienceView Professional Unique Production Identifier
productionName String No Production Name as specified for display purposes
hasAvailableTickets Boolean No True if tickets for this performance are available, false otherwise.
tixRemaining Integer No Number of tickets still available for this performance (This number should NOT be displayed to consumers for security purposes).
customMessage String Yes Custom not available message. If and only if the Display Code is set to M, this message should be displayed.
noRemainingTicketsMessage String Yes If no tickets are available this is the message to display.
shutoffHour Double No Number of hours before show time that public ticket sales are turned off
shutoffHourMessage String Yes The message to display once public ticket sales are turned off
generalAdmission Boolean No General Admission flags tells you whether consumers will be delegated specific seats or if seating in each section is first come first serve. True is first come first serve. False is specific seating.
allDayEvent Boolean No If the performance does not have a start time it is an all day event
doorEntryStartDate String No If allDayEvent is true, this states when doors open for the event
doorEntryStartTime String No If allDayEvent is true, this states when doors open for the event
doorEntryEndDate String No If allDayEvent is true, this states when doors close for the event
doorEntryEndTime String No If allDayEvent is true, this states when doors close for the event
productionLogoLink String Yes The fully qualified URL to the series logo image
productionDescription String Yes The description for the entire run of the show
departmentId Integer Yes A grouping of productions
departmentName String Yes The name of a grouping of productions
performanceEntryTimes PerformanceEntryTime Yes A list of entry times for the performance

Common System Codes

Event Availability Codes

Code Short Name Description
N Not Available Performance is not currently available for purchase
P Package Holders Performance can only be purchased by patrons who hold a package with rights to it
A All Performance can be purchased by anyone

Event Display Codes

Code Short Name Description
I Invisible It should not be displayed on the calendar
M Message It should be displayed with the message provided in 'customMessage'
T Normal Display normally
C Cancelled Display as cancelled
S Sold out Display as sold out

Event Production Statuses

Code Short Name Description
D Deleted This series was deleted from AudienceView Professional
U Under Construction This series is not yet ready to be disabled for sale because it is still being configured within AudienceView Professional
T Normal This series is available for public display

Event Production Colors

Code Color Hex Code
0 White #ffffff
1 Light Pink #ffe2e9
2 Light Blue #e2f1ff
3 Light Green #ddffbb
4 Light Purple #eadfff
5 Light Yellow #fff5ce
6 Dark Blue #b6c5f4
7 Light Brown #eddac7
8 Beige #ffe7d7
9 Dark Green #dcecdc

Errors

The AudienceView Professional Public API will always respond with a 200 OK and provide the error information as part of the response in fields called "errors" and "warnings."

Scanning API

Welcome to the AudienceView Professional API! You can use our API to access future event data and for creating a custom scanning application.

You can view JSON response examples in the dark area to the right.

Authentication

Description

To gain access to scanning functionality, a user must be authenticated. The user is someone whom has access to AudienceView Professional with the scanning permission.

HTTP Requests

POST https://api.ovationtix.com/public/scanning/authenticate

Request Body

This is how the request body for authentication should look

{
  "username": "${username}",
  "password": "${password}"
}
Variable Description
username This is usually the individual's email address.
password The user's password to log into AudienceView Professional.

Response Body

Authentication Response

Successful Response output example:

{  
   "accessTokenExpiration":1537219056608,
   "error":false,
   "errorMessageHTML":null,
   "errorDetails":null,
   "accessToken":"11620f64-5328-49ae-aea8-414951fdd21a",
   "passwordExpiresOn":1663460212000,
   "daysTillPasswordExpires":60
}

Failed Response output example:

{
   "accessTokenExpiration":null,
   "error":true,
   "errorMessageHTML":"<div style='font-size:1.2em;background-color:red;color:white;text-align:center;padding:5px;'>Password is expired. You must reset it by logging in via a desktop.</div>",
   "errorDetails":{  
      "errorCodeId":4,
      "errorCodeKey":"error.authentication.password_expired",
      "errorCodeName":"Password expired",
      "forceLogout":true
   },
   "accessToken":null,
   "passwordExpiresOn":null,
   "daysTillPasswordExpires":null
}
Variable Type Nullable Description
accessTokenExpiration Date Yes Milliseconds after the Epoch when the access token provided will expire. This is updated to one hour after every API call.
error Boolean No True if an error occorred. Details will be available in the Error Details Object.
errorMessageHTML String Yes An HTML string containing failure information that can be displayed to the user.
errorDetails ErrorDetails Yes See Error Details Object
accessToken String Yes A string that is used in all subsequent scanning calls to validate the user's access.
passwordExpiresOn Date Yes Milliseconds after the Epoch when this user's password will expire.
daysTillPasswordExpires Integer Yes Number of days until this user's password will expire.

Authorization

Description

All Calls to the following endpoints, must contain an "Authorization" header that follows the format "Basic base64encoded(username:accessToken)".

Variable Description
username This is usually the individual's email address.
accessToken This is the access token provided by the result of the Authentication call.

Filtering Options for Clients and Shows

Description

Provides a list of clients, series, and performances that can be scanned currently. In AudienceView Professional Ticket Scanner, this information is displayed as 3 drop downs:

  1. Client Selection
  2. Production Selection
  3. Performance Selection

The time frame is based on the client's customized configuration and is modifiable by our client services team via X minutes prior to and Y minutes after any given performance.

The identifiers in the response are used in subsequent calls to filter what is being scanned.

For example, a festival may have multiple events at the same time, but each event will have a user who only wants to scan for their event. Using the performance ID as a filter during the scan request will only take that event into consideration.

On the flip side, if you're an exhibition that has multiple AudienceView Professional performances throughout the day to help stagger entries, but you are willing to provide some flexibility to patrons. Say they buy a ticket for 11 AM, but they show up at 10 AM. You may want to use the production ID to allow them to enter early.

If you are an organization that has only 1 event per day, you only need to use the client ID to scan for the days performance.

HTTP Requests

GET https://api.ovationtix.com/public/scanning/filterOptions

Response Body

Filter Options Response

Response output example:

{  
   "accessTokenExpiration":1537220455221,
   "error":false,
   "errorMessageHTML":null,
   "errorDetails":null,
   "clients":[{
         "id":1,
         "value":"TestAccount-300",
         "productions":[{
               "productionId":3622,
               "productionName":"Spamalot",
               "performances":[{
                     "performanceId":49182,
                     "performanceStart":1537142400000
               }]
         }]
   }]
}
Variable Type Nullable Description
accessTokenExpiration Date Yes Milliseconds after the Epoch when the access token provided will expire. This is updated to one hour after every API call.
error Boolean No True if an error occorred. Details will be available in the Error Details Object.
errorMessageHTML String Yes An HTML string containing failure information that can be displayed to the user.
errorDetails ErrorDetails Yes See Error Details Object
clients ScanningClientObject Yes See Scanning Client Object

Scanning Client Object

Variable Type Nullable Description
id Integer No The AudienceView Professional identifier for a client. You will use this in subsequent calls.
value String No The name of the AudienceView Professional client.
productions Array of ProductionObject Yes See Scanning Production Object

Scanning Production Object

Variable Type Nullable Description
productionId Integer No The AudienceView Professional identifier for a series. You may use this in subsequent calls.
productionName String No The name of this series.
performances Array of PerformanceObject Yes See Scanning Performance Object

Scanning Performance Object

Variable Type Nullable Description
performanceId Integer No The AudienceView Professional identifier for a performance. You may use this in subsequent calls.
performanceStart Date No The date and time of this performance in milliseconds after the Epoch.

Validate Ticket Barcode

Description

Validate the ticket barcode against the given filter criteria. The filter criteria is the AudienceView Professional client id, series id, and/or performance id.

HTTP Requests

POST https://api.ovationtix.com/public/scanning/validateTicket

Request Body

This is how the request body for ticket validation should look

{
  "barcodeString": "${barcodeString}",
  "clientId": ${clientId},
  "productionId": ${productionId},
  "performanceId": ${performanceId}
}
Variable Nullable Description
barcodeString No The barcode string associated with the ticket
clientId No The AudienceView Professional client identifier selected by the user from the data provided in the Filtering Options for Clients and Shows API call.
productionId Yes The AudienceView Professional series identifier selected by the user from the data provided in the Filtering Options for Clients and Shows API call. This is not required. If not provided, any series within the scan time range configured within AudienceView Professional will receive a valid response.
performanceId Yes The AudienceView Professional performance identifier selected by the user from the data provided in the Filtering Options for Clients and Shows API call. This is not required. If not provided, any series within the scan time range configured within AudienceView Professional will receive a valid response.

Response Body

Scan Response Data

Successful Response output example:

{  
   "accessTokenExpiration":1537282567230,
   "error":false,
   "errorMessageHTML":null,
   "errorDetails":null,
   "name":"Walkup Walkup",
   "performance":"Spamalot: Sep 18 4:00PM Tue",
   "section":"s1",
   "seat":"A1",
   "ticketsScanned":2,
   "ticketsSold":2,
   "successMsg":"<div style='font-size:1.4em;background-color:green;color:white;padding:5px;'><div>s1: A1</div><div>Walkup Walkup</div><div>Spamalot: Sep 18 4:00PM Tue</div><div>2 scanned of 2 sold.</div></div>",
   "patron":{  
      "email":null,
      "firstName":"Walkup",
      "lastName":"Walkup",
      "billingAddress":{  
         "line1":"123 Main St",
         "line2":"Floor 123",
         "city":"New York",
         "state":"NY",
         "zipCode":"10108",
         "country":"US"
      },
      "shippingAddress":{  
         "line1":"123 Main St",
         "line2":"Floor 123",
         "city":"New York",
         "state":"NY",
         "zipCode":"10108",
         "country":"US"
      },
      "primaryPhoneNumber":{  
         "phoneNumber":"212-555-1234",
         "type":"Home"
      }
   }
}

Failed Response output example:

{  
   "accessTokenExpiration":1537280706925,
   "error":true,
   "errorMessageHTML":"<div style='font-size:1.2em;background-color:red;color:white;text-align:center;padding:5px;'><div>INVALID TICKET</div></div>",
   "errorDetails":{  
      "errorCodeId":11,
      "errorCodeKey":"error.ticket.not_valid",
      "errorCodeName":"Ticket Not Valid",
      "forceLogout":false
   },
   "name":null,
   "performance":null,
   "section":null,
   "seat":null,
   "ticketsScanned":null,
   "ticketsSold":null,
   "successMsg":null,
   "patron":null
}
Variable Type Nullable Description
name String Yes The name of the individual who purchased the tickets.
performance String Yes Name of the series and the date, time, and day of the show.
section String Yes The name of the section the seat this ticket is associated with is.
seat String Yes The row and number of the seat for this ticket.
ticketsScanned Long Yes The number of scanned tickets the order this ticket is associated with for this performance.
ticketsSold Long Yes The total number of tickets in the order this ticket is associated with for this performance.
successMsg String Yes An HTML formatted response with details about this ticket.
patron Scannable Ticket Patron Yes If the user has the "patronReporting" permission in AudienceView Professional, they will receive patron data with a successful scan. Who's Coming Plus One information will be provided if it is available. Otherwise, the patron who purchased this ticket will be provided.

Scannable Ticket Patron Response Object

Variable Type Nullable Description
email String Yes The email address of the patron associated with this ticket.
firstName String Yes The first name of the patron assiciated with this ticket.
lastName String Yes The last name of the patron associated with this ticket.
billingAddress Scannable Ticket Patron Address Yes The billing address of the patron associated with this ticket.
shippingAddress Scannable Ticket Patron Address Yes The shipping address of the patron associated with this ticket.
primaryPhoneNumber Scannable Ticket Patron Phone Number Yes The phone number of the patron associated with this ticket.

Scannable Ticket Patron Address Response Object

Variable Type Nullable Description
line1 String Yes Address line 1
line2 String Yes Address line 2
city String Yes Address City
state String Yes Address State
zipCode String Yes Address Zip Code
country String Yes Address Country

Scannable Ticket Patron Phone Number Response Object

Variable Type Nullable Description
phoneNumber String Yes Digits of Phone number
type String Yes The type of number this is. This can be home, cell, work, or fax.

Cache Valid Tickets

Description

Retrieve all valid tickets for the provided critieria. You can use this data to function in an offline state.

HTTP Requests

GET https://api.ovationtix.com/public/scanning/cache/validTickets

Request Parameters

Variable Nullable Description
clientId No The AudienceView Professional client identifier selected by the user from the data provided in the Filtering Options for Clients and Shows API call.
productionId Yes The AudienceView Professional series identifier selected by the user from the data provided in the Filtering Options for Clients and Shows API call. This is not required. If not provided, any series within the scan time range configured within AudienceView Professional will receive a valid response.
performanceId Yes The AudienceView Professional performance identifier selected by the user from the data provided in the Filtering Options for Clients and Shows API call. This is not required. If not provided, any series within the scan time range configured within AudienceView Professional will receive a valid response.

Response Body

Scan Response Data

Successful Response output example:

{  
   "accessTokenExpiration":1537395445777,
   "error":false,
   "errorMessageHTML":null,
   "errorDetails":null,
   "clientId":284,
   "productionId":null,
   "performanceId":null,
   "tickets":[{
      "ticketId":580768132,
      "performanceId":10302127,
      "productionName":"Kinky Boots",
      "performanceStartDate":1536768000000,
      "barcode":"6nwmw29eo",
      "alreadyScanned":false,
      "refundedOrVoided":false,
      "orderConsumerName":"Walkup Walkup",
      "performance":"Kinky Boots: Sep 12 12:00PM Wed",
      "section":"Test Section I",
      "seat":"A1",
      "ticketsScanned":null,
      "ticketsSold":4,
      "patron":{  
         "email":null,
         "firstName":"Walkup",
         "lastName":"Walkup",
         "billingAddress":null,
         "shippingAddress":null,
         "primaryPhoneNumber":null
      }
   },{  
      "ticketId":580768141,
      "performanceId":10302127,
      "productionName":"Kinky Boots",
      "performanceStartDate":1536768000000,
      "barcode":"aj00ymskl",
      "alreadyScanned":false,
      "refundedOrVoided":false,
      "orderConsumerName":"Walkup Walkup",
      "performance":"Kinky Boots: Sep 12 12:00PM Wed",
      "section":"Test Section I",
      "seat":"A5",
      "ticketsScanned":null,
      "ticketsSold":4,
      "patron":{  
         "email":null,
         "firstName":"Walkup",
         "lastName":"Walkup",
         "billingAddress":null,
         "shippingAddress":null,
         "primaryPhoneNumber":null
      }
   }]
}
Variable Type Nullable Description
clientId Integer No The AudienceView Professional client identifier selected by the user from the data provided in the Filtering Options for Clients and Shows API call.
productionId Integer Yes The AudienceView Professional series identifier selected by the user from the data provided in the Filtering Options for Clients and Shows API call. This is not required. If not provided, any series within the scan time range configured within AudienceView Professional will receive a valid response.
performanceId Integer Yes The AudienceView Professional performance identifier selected by the user from the data provided in the Filtering Options for Clients and Shows API call. This is not required. If not provided, any series within the scan time range configured within AudienceView Professional will receive a valid response.
tickets Array of ScannableTicket No An array of ticket scans that occurred while in offline mode.

Scannable Ticket Object

Variable Type Nullable Description
ticketId Integer No The identifier for this ticket.
performanceId Integer No The performance ID this ticket is for.
productionName String No The name of the show.
performanceStartDate Date No The time the performance starts in milliseconds after the Epoch.
barcode String No The barcode for this ticket.
alreadyScanned Boolean No If true, the ticket was scanned prior to the download of this data.
refundedOrVoided Boolean No If true, then this barcode is not valid and you can display an appropiate message to user about it being refunded or voided.
orderConsumerName String Yes The name of the individual who purchased the tickets.
performance String Yes Name of the series and the date, time, and day of the show.
section String Yes The name of the section the seat this ticket is associated with is.
seat String Yes The row and number of the seat for this ticket.
ticketsScanned Long Yes The number of scanned tickets the order this ticket is associated with for this performance.
ticketsSold Long Yes The total number of tickets in the order this ticket is associated with for this performance.
patron Scannable Ticket Patron Yes The patron associated with this ticket. This will contain +1 information when available and the purchaser in all other instances.

Sync Cached Scans

Description

This call will update AudienceView Professional with the VALID tickets scanned while the device was offline or unable to communicate with AudienceView Professional servers. If you declare a ticket as invalid, there is no need to provide that in the sync call.

If a ticket is valid, you must prepare the data in the request body to be sent when internet access is established. If you expect this to take longer than the access token's expiration, you must ensure data is not lost by needing to authenticate again.

HTTP Requests

POST https://api.ovationtix.com/public/scanning/cache/syncScans

Request Body

This is how the request body for sycn cached scans should look

{
  "clientId": ${clientId},
  "productionId": ${productionId},
  "performanceId": ${performanceId}
  "tickets": [{
    "ticketId": ${ticketId},
    "performanceId": ${performanceId},
    "barcode": "${barcodeString}",
    "scanTime": ${scanTime}
  },{
    "ticketId": ${ticketId},
    "performanceId": ${performanceId},
    "barcode": "${barcodeString}",
    "scanTime": ${scanTime}
  }]
}
Variable Type Nullable Description
clientId Integer No The AudienceView Professional client identifier selected by the user from the data provided in the Filtering Options for Clients and Shows API call.
productionId Integer Yes The AudienceView Professional series identifier selected by the user from the data provided in the Filtering Options for Clients and Shows API call. This is not required. If not provided, any series within the scan time range configured within AudienceView Professional will receive a valid response.
performanceId Integer Yes The AudienceView Professional performance identifier selected by the user from the data provided in the Filtering Options for Clients and Shows API call. This is not required. If not provided, any series within the scan time range configured within AudienceView Professional will receive a valid response.
tickets Array of SyncTicket No An array of ticket scans that occurred while in offline mode.

SyncTicket Object

Variable Type Nullable Description
ticketId Integer No The ticket identifier provided by the Cache Valid Tickets call.
performanceId Integer No The performance identifier provided by the Cache Valid Tickets call.
barcodeString String No The barcode string that matches what was provided by the Cache Valid Tickets call.
scanTime Date No The time that the ticket was scanned. This should be in milliseconds after the Epoch.

Response Body

Scan Response Data

Successful Response output example:

{
  failedBarcodes: [{
    "barcode": "CDEFG123",
    "reason": "Ticket ID not found."
  },{
    "barcode": "CDEFG124",
    "reason": "Ticket does not belong to client #1"
  },{
    "barcode": "CDEFG125",
    "reason": "Ticket does not belong to performance #1"
  },{
    "barcode": "CDEFG126",
    "reason": "Ticket is refunded or voided."
  },{
    "barcode": "CDEFG127",
    "reason": "Scan time is in the future."
  },{
    "barcode": "CDEFG128",
    "reason": "Scan time is more than 48 hours ago. We cannot process scans that old."
  }]
}
Variable Type Nullable Description
failedBarcodes Array of Sync Scan Failure No An array of barcodes that failed to insert a scan action into the system. See Sync Scan Failure

Sync Scan Failure

Variable Type Nullable Description
barcode String No The barcode string that had a discrepancy. This must be provided to the user so they can check the details in AudienceView Professional.
reason String No A text explanation for the failure.

Validate Token

Description

Ensures the token being used for the user is still valid. If it is not, the user must reauthenticate via the authentication API call.

HTTP Requests

GET https://api.ovationtix.com/public/scanning/validateToken

Response Body

Authorization Data Response

Response output example:

{  
   "accessTokenExpiration":1537283545089,
   "error":false,
   "errorMessageHTML":null,
   "errorDetails":null
}
Variable Type Nullable Description
accessTokenExpiration Date Yes Milliseconds after the Epoch when the access token provided will expire. This is updated to one hour after every API call.
error Boolean No True if an error occorred. Details will be available in the Error Details Object.
errorMessageHTML String Yes An HTML string containing failure information that can be displayed to the user.
errorDetails ErrorDetails Yes See Error Details Object

Invalidate Token

Description

Marks the token as not valid. This is essentially a log out and is preferred when the application closes instead of letting the token timeout.

HTTP Requests

DELETE https://api.ovationtix.com/public/scanning/invalidateToken

Response Status

This endpoint responds with an HTTP 200 OK and no body.

Common Scanning Objects

Scanning Error Details Object

Variable Type Nullable Description
errorCodeId Integer No See Scanning Error Codes
errorCodeKey String No An error key that you can use to internationalize failures with the API
errorCodeName String No A short name for the type of error that occurred
forceLogout Boolean No If true, the user must reauthenticate to access the API. Otherwise, this error is non-fatal to the access token.

Common Scanning Codes

Scanning Error Codes

Code Short Name Description
1 Authorization Header Invalid The authorization header was invalid or missing.
2 Authentication Failed The username/password combination was incorrect.
3 Not Authorized The user does not have the scanning permission.
4 Password Expired The user's password must be reset by logging into AudienceView Professional.
5 Token Expired The user's token expired. They must reauthenticate.
6 Token Not Valid The user's token is not valid. They must reauthenticate.
7 User Wrong Client The user is attempting to scan for a client they do not have access to.
8 Ticket Wrong Client The ticket scanned belongs to another AudienceView Professional client.
9 Ticket Wrong Series The ticket scanned is for another series.
10 TIcket Wrong Performance The ticket scanned is for another performance of this series.
11 Ticket Not Valid The ticket scanned does not have a valid barcode within AudienceView Professional.
12 Ticket Already Scanned The ticket was scanned already.
13 Ticket Voided The ticket was cancelled within the order.
14 Ticket Refunded The ticket was refunded within the order.
15 Input Missing Required Field The provided data is missing some required piece of information. This is typically a problem with your implementation.
16 Unanticipated Error Some error occurred that we did not account for when developing this API.
17 Unanticipated Error Forced Logout Some error occurred that we did nto account for when developing this API that resulting in the user's access token becoming invalidated.
json