In order to gain access to the rest API, the following requirements must be met :

1. At least one web sales listener enabled in the Director.
   • The web listener is the process that responds to the API request.
   • Web sales are not required to be enabled to the outside world - but if you do online tickets sales, you need to be aware that extensive use may require additional web listener processes.
2. The person needing REST API access must be set up as an employee in the database - this means only specified employees can have access.
   • and have the checkbox REST API: enable access via url on the employee access tab
   • the employee does not neccessarily have to be able to log into Theatre Manager desktop, but they:
     • must have an employee record
     • must not be resigned
   • can have any user level from:
     • no access to normal access, or
     • you can set the user to API only which means they cannot log into TM but can use the REST api.
   • Permissions in the Employee Data tab to indicate which data can be accessed via the REST api.
3. Have logged into the online web sales site and created an account, which requires:
   • at least one email address associated with their patron account (multiple emails for an employee are ok)
   • and a password that allows them log into the web store
4. A workstation, browser, or toolset that is capable of connecting using TLS 1.2 or later for security. If you can't connect, try latest firefox, chrome and/or on windows 10 or some smart phone.
5. (optional) Consider requiring complex passwords via a setting in system preferences. online - which will also affect your regular patrons as well.

   Note: At this time, the web store password is probably different than the employee's Theatre Manager login account since they can set it themselves online. We recommend informing staff who are given access to the REST API to use complex passwords (or if you wish, make it mandatory). Since most people will not the API enabled for their employee account, they would be largely unaffected.

There are two likely ways you may wish to log into the REST API:

• As a human using a browser or other program to view data. You will be prompted for a user id and password as per the help page.
• From a program which submits requests and manages the data that returns. Current options are HTTP Basic Authentication or JWT

When you see the window below, you have successfully accessed the API. This shows a list of the endpoints -- which is a URL that:

• will give you specific information that relates to the link. eg there is a patron end point that provides information about the patron and a ticket end point that focuses on ticket information
• can be modified to only select specific columns
• can have a sort order provided and data will return in that order
• can have a query provided to only select data that you want
• can also show some associated data (eg ticket date can show the patron, event and performance it is for

The end points are show in this manner so that they are discoverable. This means you can follow any one of them and see what kind of information it provides and can discover where it will lead.

	Remember to replace 127.0.0.1 in the example urls https://127.0.0.1/api/v1 with your web site URL (eg tickets.yourvenue.org)
	https://127.0.0.1/api/v1 will give you the top level endpoints for the entire schema.

 

Key columns in the top level endpoint list

Column	Purpose
type	This is one of meta - which indicates that type of URL will describe something - i.e. meta data data - the url will show actual data from the database
endpoint	This is the endpoint name that can be added to the base url of the API to show the data. They are generally self describing and are case-sensitive. For example, the endpoint carts will provide a list of shopping carts when added to the URL such as https://127.0.0.1/api/v1/carts
data_url	The data_url is provided so that you can easily click on the endpoint and see data from the database, if you are permitted to see that data within the Theatre Manger database as an employee. For the carts endpoint, the data_url is the same as above, i.e. https://127.0.0.1/api/v1/carts
pages_url	When the word pages is added to the data_url, the API will send the data back as pages of information with a default 25 lines of data per page. You can use next and previous to page through the data. For example https://127.0.0.1/api/v1/carts/pages You can navigate directly to a page of information by adding a ?page=x parameter (other parameters are discussed later). For example: https://127.0.0.1/api/v1/carts/pages?page=2
schema_url	If the word schema is added to the data_url, the API will provide a description of the columns in the particular endpoint. Using the carts endpoint as an example, the URL will be: https://127.0.0.1/api/v1/carts/schema Example of schema descriptions for Carts:
apps	Shows the version of the applications supported by the current TM server https://127.0.0.1/api/v1/apps

There is no specific API call to access images at this time where you can pull them down to a program.

However, if you would like the images that are on web pages, please refer to Accessing Images. With this you can show images that are in Theatre Manager on other web pages just be referring to them with the Theatre Manager build in URL.

If you are going to use those images in a front end marketing web site (eg wordpress or what have you), then we also suggest creating an image cache that is refreshed periodically to help lower the actual traffic to the commerce part of the web site.

The default output format for the REST API is in a human readable and navigable html format. That is not always the easiest for a web developer to deal with in a program, so the API offers a number of output formats that can be viewed using https://127.0.0.1/api/v1/extensions which produces a list like the one to the right.

Some example output formats are below and they may be supplemented as need be:

• csv - comma delimited values
• html - output from the database viewable in html format (the default)
• json - data is delivered in json format, probably the best for programming
• xls/xlsx - data is sent in excel spreadsheet format, probably best for subsequent analysis by end users
• xml - also a programmer based format

 

Using one of the other output formats

It is very easy to use one of the other output formats. For example, to request that the output be in json format, simply add .json to the url.

After logging in to the REST API, try the following examples to get the sample page above in different formats:

• https://127.0.0.1/api/v1/extensions.json
• https://127.0.0.1/api/v1/extensions.xls (note, this will download a spreadsheet)
• https://127.0.0.1/api/v1/extensions.xml

This applies to all URL's in the REST API - using carts for example:

• https://127.0.0.1/api/v1/carts/pages.json
• https://127.0.0.1/api/v1/carts/pages.json?page=3
• https://127.0.0.1/api/v1/carts/pages.xml

The output from the REST API can be sorted by any field in ascending or descending order, whether you display it or not, by adding a sort= parameter to the api.

You can:

• add multiple sort fields, separated by a '+' as long as the fields are recognized for the endpoint
• sort in descending order by prefacing the field name with a '-'.

 

Examples of sorting data are:

• https://127.0.0.1/api/v1/patrons?sort=company - sort patron data by company
• https://127.0.0.1/api/v1/patrons?sort=-company - sort patron data by company in DESCENDING order
• https://127.0.0.1/api/v1/patrons?sort=last_name+first_name - sort patron data by last name, then first name
• https://127.0.0.1/api/v1/patrons?sort=last_name+-first_name - sort patron data by last name, then first name in DESCENDING order
• https://127.0.0.1/api/v1/events?sort=year+title+-first_performance_date - sort event data by year, title and then first performance date in DESCENDING order

There are multiple ways to search for data from the database. You can retrieve data using:

• the Unique iD which allows you to access a specific record in any table using it's unique ID number.
• A Query which can contain multiple search parameters which provide restrictions that limit the rows of data that are returned.
• the page=xx parameter to provide a limited subset of data of approximately 25 lines. The data does not come back in any particular order unless a sort parameter is also given.

You can select specific columns by adding only= to the parameter line. The names of the fields for the particular endpoint must be known and these can be determined by looking at the columns returned for a particular record or page of records.

Each column you want to see in your output is separated with a + (plus sign)

Examples:

• https://127.0.0.1/api/v1/patrons?only=first_name+last_name+company - show first, last and company from the patron table
• https://127.0.0.1/api/v1/events?only=id+year+title+total_sold+sales_notes - show id, year, title, total_sold (to all performances) and sales notes from the event

The endpoints of the REST API specify a particular table from the database that you want to access. Some of those tables are related to other information - tickets are connected to the patrons that bought them, the event that it is for, and the performance time that the patron purchased. You can add in some fo that additional table connections by specifying them.

The starting place is finding what data is related to a particular endpoint using the related feature. The following shows:

• https://127.0.0.1/api/v1/patrons/related - relationships to any patron record
• https://127.0.0.1/api/v1/patrons/51/related - relationships for a specific patron record (#51) which can be followed to see data for that patron.
• https://127.0.0.1/api/v1/marketing/related - relationships for a particular marketing record for the patron so that you can retrieve things like the primary email address, phone, or physical address

Once you know which data is related, you can start to include that data onto the URL. In a one to many relationship, you normally start with the child or collection record.

Examples are:

• https://127.0.0.1/api/v1/performances?q=perform_datetime:2016-01-01..2016-12-31&include=event
  In addition to data from the performance endpoint there is now data from the event endpoint on the end of each row of data.
• https://127.0.0.1/api/v1/performances?q=perform_datetime:2017-01-01..2017-12-31&only=event.title+event.show_code+series_code+perform_datetime
  Shows event title, show code, series code and performance date/times for performances between 2017-01-01 and 2017-12-31
• https://127.0.0.1/api/v1/performances?q=perform_datetime:>2016-01-01&only=event.title+event.show_code+series_code+perform_datetime+venue.name+venue.address_line_one+venue.city
  Shows events title, show code, series code and performance date time for performances after 2016-01-01 and adds the name, address and city of the venue from that relationship
• https://127.0.0.1/api/v1/performances.csv?q=perform_datetime:>2016-01-01&only=event.title+event.show_code+series_code+perform_datetime+venue.name+venue.address_line_one+venue.city
  Same as above, except in CSV format
• https://127.0.0.1/api/v1/performances.json?q=perform_datetime:>2016-01-01&only=event.title+event.show_code+series_code+perform_datetime+venue.name+venue.address_line_one+venue.city
  Same as above, except in JSON format
• https://127.0.0.1/api/v1/marketing?only=patron.first_name+patron.last_name+patron.company+primary_email.contents+primary_address.address_line_one+primary_address.city
  Show patron names and the primary address and email.

You can summarize the data based on fields which requires a group= parameter followed by an agg= parameters indicating the fields you want to summarize by and how you want to summarize them. For example:

group=round(date_bought,1,month):purchase_date&agg=count+sum(total_cost)+avg(total_cost)

The group= allows you to summarize by text, number, boolean and date fields. You can also provide a function to summarize by parts of a date field.

Examples of the group= clause:

• group=last_name - group patrons for summary by last name
• group=company+last_name - group patrons for summarization by company and last name
• group=date_bought - group the tickets by ticket the date they were bought - which may be of limited use as it contains time stamp
• group=round(date_bought,1,month):purchase_date - group the tickets by date bought, but rounded to monthly increments. You can change a date grouping to be rounded to any interval, like 10 minute intervals

Examples of the agg= clause:

Query Breakdown:

Params are broken up by the ampersand &

• Only sold tickets: q=-date_bought:null
• Group by the purchase month: group=round(date_bought, 1, month)
• Name it purchase_date
• For each group aggregate the count of tickets, the total cost of tickets, and the average cost of each ticket: agg=count+sum(total_cost)+avg(total_cost)

Examples

• https://127.0.0.1/api/v1/tickets?q=-date_bought:null&group=round(date_bought,1,month):purchase_date&agg=count+sum(total_cost)+avg(total_cost)
  retrieve all sold tickets (date bought is not empty) and aggregate the count, total cost, average cost into groupings of date_bought, rounded by month

The full syntax of the REST API for is shown below. This summarizes how to use it within Theatre Manager. The following conventions are used:

• [ item ] - means that this part of the syntax is optional
• [item, ....] - means that the item can be repeated
• item1 | item2 - means you can use either Item1 or Item2 in the syntax

https://RestServerURL/api/v1 [/endpoint]

Putting it all together

the following examples show some of the power of the api to get exactly what you want.

• https://127.0.0.1/api/v1/patrons?only=first_name+last_name+company&sort=last_name+first_name
  retrieve first, last and company fields from the patrons endpoint and sort by last name, then first name
• https://127.0.0.1/api/v1/patrons?only=first_name+last_name+company&sort=last_name+first_name&q=-last_name:smith
  retrieve only first, last and company from the patrons endpoint and sort by last name, then first name. use a query to eliminate any patron with the last name smith from the list.
• https://127.0.0.1/api/v1/patrons?only=first_name+last_name+company&sort=last_name&q=last_name:smith
  retrieve first, last and company from the patrons endpoint, sort by last name. use a query to eliminate any patron with the last name smith from the list.
• https://127.0.0.1/api/v1/patrons?only=first_name+last_name+company&sort=last_name&q=last_name:smith
  retrieve first, last and company from the patrons endpoint, sort by last name only searching for people called 'smith' and exporting as JSON format
• https://127.0.0.1/api/v1/carts?q=status_id:4&only=date_checkout+order_id+patron_id+total_cost+order_notes&sort=-date_checkout
  get a list of all checked out shopping carts (status_id=4) and sort them in descending order by checkout date

This page shows some fun queries to illustrate what might be possible using the basics of the REST API to illustrate some powerful combinations. MOre examples may be added as people looks for solutions.

A List of Ticket for an event

This shows a list of tickets purchased for an event, the people who bought it and the order total.

• The endpoint is tickets since we need to be looking for tickets, since patrons, performances, events and orders are all related to the purchased ticket https: //127.0.0.1/api/v1/tickets?
• The query is : patron >0, order >0 and event 61 or q=patron_id:>0+order_id:>0+event_id:[61]
• the fields are: event title, series, date, patron id, name, order total and balance

  only=event.title+performance.series_code+performance.perform_datetime+patron.id+patron.first_name+patron.last_name+patron.formal_name+order.id+order.total_amount+order.balance

• Full REST API query

  https://127.0.0.1/api/v1/tickets?q=patron_id:>0+order_id:>0+event_id:[61]&only=event.title+performance.series_code+performance.perform_datetime+patron.id+patron.first_name+patron.last_name+patron.formal_name+order.id+order.total_amount+order.balance

A List of orders for an event

This is a summary of people buying tickets for an event - the purchasers are grouped by order.

• The endpoint is tickets since we need to be looking for tickets, since patrons, performances, events and orders are all related to the purchased ticket

  https: //127.0.0.1/api/v1/tickets?

• The query is : patron >0, order >0 and event 61 or q=patron_id:>0+order_id:>0+event_id:[61]
• the fields that are grouped are: event title, series, date, patron id, name, order id, somewhat similar to the above query

  group=event.title+performance.series_code+performance.perform_datetime+patron.id+patron.first_name+patron.last_name+patron.formal_name+order_id

• however, some data that is repeated can best be shown if it is aggregated such as:
  • sum of ticket quantity and total cost (since this is per ticket values)
  • minimum of total amount and order balance (we use the minimum to get the value once per order)
  agg=sum(quantity):ticket_count+sum(total_cost):ticket_total+min(order.total_amount):order_total+min(order.balance):order_balance
• Full REST API query is:

  https://127.0.0.1/api/v1/tickets?q=patron_id:>0+order_id:>0+event_id:[61]&group=event.title+performance.series_code+performance.perform_datetime+patron.id+patron.first_name+patron.last_name+patron.formal_name+order_id&agg=sum(quantity):ticket_count+sum(total_cost):ticket_total+min(order.total_amount):order_total+min(order.balance):order_balance

 

Primary phone numbers for a patron with locations

• Full REST API query is:

  https://127.0.0.1/api/v1/marketing?only=patron.id+patron.first_name+patron.last_name+primary_email_link.location.description+primary_email.contents+primary_phone_link.location.description+primary_phone.contents&q=-primary_email.contents:null+-primary_phone.contents:null

There are some options for extracting calendar information from Theatre Manager in the form of a calendar download or a subscribe-able calendar. These currently include:

• All events that are currently in the future
• Events that a patron has purchased tickets to - which is restricted to the patron who purchased the tickets
• Volunteer/Staff Activities that a patron has been assigned to

ICS files are convenient ways to share calendar information and can be done in two ways: sending the ICS file containing calendar data to people Subscribing to a calendar file - which means that as the calendar information changes in the database, the person who subscribed to the calendar will see the changed calendar data if they are connected to the server. they may need to set the refresh setting in their calendar.

Subscribing to External Calendars

The following links may assist you to link or subscribe to a Theatre Manager ICS calendar using you calendar. IF the links are not correct or ut of date, please use Google to search for Subscribing to calendars with ... to see if it helps.

• Apple's iCal
• Google Calendar or this link
• Microsoft Outlook

Wikipedia publishes a list of calendar applications with ICS support. This might be helpful getting started with calendar integration.

The subscriber to a calendar may have to set the refresh time in the calendar - See iCal example