Introduction

Welcome to the Matrix Booking API. You can use our API to get data about bookings, visitors, locations and resources.

The server URL for the Matrix Booking API is https://app.matrixbooking.com/api/v1. In various places throughout this documentation, for brevity and readability, we refer to API endpoints without the server URL, such as GET /availability?...

You can view example data and calls in the area to the right. These examples always show the complete URL, which includes the server URL.

Authentication

User credentials

Calling the API as a specific user

curl "https://app.matrixbooking.com/api/v1/user/current"
  -H "Authorization: Basic encoded_credentials"

Make sure to replace encoded_credentials with the Base64 encoded user and password.

Matrix Booking also supports passing user-specific credentials via HTTP Basic authentication. This can be used when an API call should run with the permissions and access level of a particular user.

The client sends HTTP requests with an Authorization header that contains the word Basic followed by a space, and a Base64-encoded string derived from the username and password separated by a colon, as per standard HTTP Basic authentication.

Whilst any Matrix Booking user and password can be used, for system-to-system integration we recommend that you use a System/API user, which can be created by someone who is a Matrix Booking administrator for your organisation.

Common Concepts

API data is JSON encoded with UTF-8. All calls must be made using HTTPS.

Query parameters

Query parameter values must be URL encoded.

Where a query parameter supports multiple values, each value for the query parameter must be specified as a separate key/value pair. For example, if we wanted to call the availability check API and request that both location and booking data be returned, then the include query parameter would be specified twice:

GET /availability?...&include=locations&include=bookings

Dates and times

Dates and times are passed in ISO 8601 format. For example, 12:27 PM on 23 March 2019 would be passed as 2019-03-23T12:27:00. Generally date/time values are local values, passed without a time zone or UTC offset. See also Working with Time Zones below.

Where date/time values are passed as query parameters, the following special values are also supported: today, tomorrow and tomorrow_plus_n, where n is a number of days. Additionally, for ranges, the end date/time may be set to eod, meaning the end of day of the specified start date/time.

For example, a call to check availability for all of the day after tomorrow might appear as:

GET /availability?...&f=tomorrow_plus_1&t=eod

Working with time zones

Matrix Booking tenants can choose to enable support for multiple time zones. Where this is not enabled, date and time values will be local to the time zone of the organisation. This time zone is returned to the API caller in the X-Time-Zone response header.

Where tenants have enabled support for multiple time zones, it is possible for the API caller to specify the time zone of dates and times by setting the X-Time-Zone request header. The value must be an IANA time zone, such as Europe/London or America/New_York.

Example

Suppose a resource located in London is booked from 10:30 AM to 2:30 PM local time on 23 March 2019. If multiple time zones support is not enabled then an API call returning data for this booking will return the start time as 2019-03-23T10:30:00 and the end time as 2019-03-23T14:30:00, with the X-Time-Zone response header set to Europe/London.

If instead, multiple time zones support is enabled and the caller sets the request header X-Time-Zone to Australia/Sydney, then the example booking's start time would be returned as 2019-03-23T21:30:00 and the end time as 2019-03-24T01:30:00, as Sydney is 11 hours ahead of London time on the date of the booking.

Booking Categories

Matrix Booking supports booking of many types of resources, most commonly desks and meeting rooms. In Matrix Booking terminology, the type of resource is known as a booking category. Certain API calls require the booking category to be specified, such as when checking resource availability.

Note that the internal id of a booking category varies from one Matrix Booking tenant to another.

Booking category model

Example booking category object

{
  "id": 123,
  "nameSingle": "Meeting Room",
  "namePlural": "Meeting Rooms",
  "shortNameSingle": "Room",
  "shortNamePlural": "Rooms"
}

A booking category may contain the following fields:

Get booking categories

An example returning all booking categories.

curl "https://app.matrixbooking.com/api/v1/category"
  -H "Authorization: Basic encoded_credentials"

The above command returns a JSON list structured like this:

[
  {
    "id": 123,
    "nameSingle": "Meeting Room",
    "...": "..."
  },
  {
    "id": 456,
    "name": "Desk",
    "...": "..."
  }
]

This API returns the list of booking categories configured for your organisation. The booking categories are returned in the order preferred by your organisation.

HTTP request

GET https://app.matrixbooking.com/api/v1/category

Locations and Resources

Location hierarchy

The location hierarchy represents all locations and resources that have been setup for your Matrix Booking implementation, from optional high-level geographic regions to buildings and floors down to individual rooms, desks and other resources.

From an API perspective, each resource is technically a location, regardless of whether it represents a room, desk, piece of equipment or other bookable resource. Each may have a parent location, which can be used to determine the hierarchy of locations. Additionally, the location hierarchy employs a nested set model and thus each location object has a left and a right value, which can be used to determine its position within the overall hierarchy, including where it appears amongst siblings.

Example location hierarchy

Location model

Example location object

{
  "id": 1001,
  "kind": "BUILDING",
  "name": "Macquarie House",
  "left": 1,
  "right": 14,
  "locations": [
    {
      "id": 1002,
      "parentId": 1001,
      "kind": "FLOOR",
      "name": "1st Floor",
      "shortQualifier": "Macquarie House",
      "longQualifier": "Macquarie House",
      "left": 2,
      "right": 7,
      "locations": [
        {
          "id": 1003,
          "parentId": 1002,
          "kind": "ROOM",
          "name": "Room 101",
          "shortQualifier": "Macquarie House",
          "longQualifier": "1st Floor, Macquarie House",
          "left": 3,
          "right": 4,
          "isBookable": true,
          "bookingCategoryId": 123
        },
        {
          "id": 1004,
          "parentId": 1002,
          "kind": "ROOM",
          "name": "Room 102",
          "shortQualifier": "Macquarie House",
          "longQualifier": "1st Floor, Macquarie House",
          "left": 5,
          "right": 6,
          "isBookable": true,
          "bookingCategoryId": 123
        }
      ]
    }
  ]
}

A location may contain the following fields:

Get locations

An example returning all floors of a particular building with id 1001

curl "https://app.matrixbooking.com/api/v1/location?kind=FLOOR&l=1001"
  -H "Authorization: Basic encoded_credentials"

The above command returns a JSON list structured like this:

[
  {
    "id": 1002,
    "kind": "FLOOR",
    "name": "1st Floor",
    "...": "..."
  },
  {
    "id": 1005,
    "kind": "FLOOR",
    "name": "2nd Floor",
    "...": "..."
  }
]

A flexible API that returns a list of locations matching the query parameters. Examples include:

• All buildings – GET /location?kind=BUILDING
• All floors within a particular building – GET /location?kind=FLOOR&l=1001
• The hierarchy outline for a particular booking category – GET /location?bc=123&select=higher&include=nested
• All resources for a particular booking category – GET /location?bc=123

HTTP request

GET https://app.matrixbooking.com/api/v1/location

Query parameters

COMING SOON

Get a specific location

curl "https://app.matrixbooking.com/api/v1/location/123"
  -H "Authorization: Basic encoded_credentials"

This API retrieves a specific location.

HTTP request

GET https://app.matrixbooking.com/api/v1/location/<id>

URL parameters

Bookings

Booking model

Example booking object, including attendee and person sub-objects

{
  "id": 111,
  "locationId": 222,
  "timeFrom": "2019-03-23T10:00:00",
  "timeTo": "2019-03-23T14:00:00",
  "status": "CONFIRMED",
  "statusReason": "APPROVED",
  "hasStarted": false,
  "hasEnded": false,
  "label": "Important meeting",
  "notes": "Agenda notes...",
  "organisation": {
    "id": 333,
    "name": "Example Inc."
  },
  "owner": {
    "id": 444,
    "name": "Theo Owner",
    "email": "theo.owner@example.com"
  },
  "bookedBy": {
    "id": 555,
    "name": "Anne Booker",
    "email": "anne.booker@example.com"
  },
  "attendeeCount": 3,
  "ownerIsAttendee": true,
  "attendees": [
    {
      "person": {
        "id": 777,
        "kind": "INTERNAL",
        "firstName": "Peter",
        "lastName": "Staff",
        "name": "Peter Staff",
        "email": "peter.staff@example.com"
      },
      "isVisitor": false
    },
    {
      "person": {
        "id": 888,
        "kind": "EXTERNAL",
        "firstName": "Anne",
        "lastName": "Visitor",
        "name": "Anne Visitor",
        "company": "Brocklehurst Motors",
        "email": "anne.visitor@brocklehurstmotors.co.uk"
      },
      "isVisitor": true
    }
  ],
  "audit": {
    "created": {
      "when": "2019-03-06T13:56:03.963",
      "eventType": "CREATED_FOR_APPROVAL",
      "eventUser": {
        "id": 555,
        "name": "Anne Booker",
        "email": "anne.booker@example.com"
      },
      "statement": "created this booking, subject to approval"
    },
    "approved": {
      "when": "2019-03-07T08:32:54.247",
      "eventType": "APPROVED",
      "eventUser": {
        "id": 999,
        "name": "Phillip Approver",
        "email": "phillip.approver@example.com"
      },
      "statement": "approved this booking"
    }
  },
  "history": [
    {
      "when": "2019-03-06T13:56:03.963",
      "eventType": "CREATED_FOR_APPROVAL",
      "eventUser": {
        "id": 555,
        "name": "Anne Booker",
        "email": "anne.booker@example.com"
      },
      "statement": "created this booking, subject to approval"
    },
    {
      "when": "2019-03-06T14:45:32.237",
      "eventType": "TIME_CHANGED",
      "eventUser": {
        "id": 555,
        "name": "Anne Booker",
        "email": "anne.booker@example.com"
      },
      "statement": "updated the time of this booking"
    },
    {
      "when": "2019-03-07T08:32:54.247",
      "eventType": "APPROVED",
      "eventUser": {
        "id": 999,
        "name": "Phillip Approver",
        "email": "phillip.approver@example.com"
      },
      "statement": "approved this booking"
    }
  ]
}

A booking may contain the following fields:

An attendee may contain the following fields:

A person may contain the following fields:

A history record may contain the following fields:

Get bookings

An example returning tentative room bookings for tomorrow, but not desk bookings.

curl "https://app.matrixbooking.com/api/v1/booking?bc=123&status=TENTATIVE&f=tomorrow&t=eod"
  -H "Authorization: Basic encoded_credentials"

The above command returns a JSON list structured like this:

[
  {
    "id": 123,
    "label": "An example booking",
    "...": "..."
  },
  {
    "id": 456,
    "label": "Another example booking",
    "...": "..."
  }
]

Note that when requesting location data also, with query parameter include=locations, the response body changes from a JSON list to a JSON object with nested booking, location and ancestor location lists.

{
  "bookings": [],
  "locations": [],
  "ancestorLocations": []
}

This API returns a list of bookings matching the query parameters.

HTTP request

GET https://app.matrixbooking.com/api/v1/booking

Query parameters

Get a specific booking

curl "https://app.matrixbooking.com/api/v1/booking/123"
  -H "Authorization: Basic encoded_credentials"

This API retrieves a specific booking.

HTTP request

GET https://app.matrixbooking.com/api/v1/booking/<id>

URL and query parameters

Cancel a specific booking

curl "https://app.matrixbooking.com/api/v1/booking/123"
  -X DELETE
  -H "Authorization: Basic encoded_credentials"

This endpoint cancels a specific booking. If the booking is already in progress, then booking will be ended early instead. It is not possible to cancel a booking that has already ended, meaning that its end time is in the past.

HTTP request

DELETE https://app.matrixbooking.com/api/v1/booking/{id}

URL parameters

Get a summary of bookings

An example returning a summary of bookings for a particular booking category by building and month.

curl "https://app.matrixbooking.com/api/v1/booking/summary?bc=123&f=2020-10-01&t
=2020-12-31&l=1001&sa=LOCATION&sa=TIMESLOT&slk=BUILDING&stg=MONTH"
  -H "Authorization: Basic encoded_credentials"

The above command returns a JSON list structured like this:

[
  {
    "key": {
      "location": {
        "id": 1001,
        "kind": "BUILDING",
        "name": "Macquarie House",
        "...": "..."
      },
      "timeslot": "2020-10-01"
    },
    "count": 5,
    "minutes": 180
  },
  {
    "key": {
      "location": {
        "id": 1001,
        "kind": "BUILDING",
        "name": "Macquarie House",
        "...": "..."
      },
      "timeslot": "2020-11-01"
    },
    "count": 3,
    "minutes": 90
  },
  { 
    "...": "..."
  }
]

This API returns a set of bookings summaries for each combination of summary key, as requested by the caller.

HTTP request

GET https://app.matrixbooking.com/api/v1/booking/summary

Query parameters

Summary model

Each summary record is comprised of a key and the count of corresponding bookings for that key combination, as well as the cumulative minutes of those bookings. Note that values for a particular key field will only appear if relevant to the requested summary.

A summary key may contain the following fields:

Visitors

The Matrix Booking visitor list generally includes people who are external to your organisation who have been invited to a meeting or have been explicitly added as visiting someone, independent of booking a room. It is also possible for internal staff to be added to the visitor list, particularly when booking a desk or building pass, so that they too go through the visitor check-in process.

The main data model relating to visitors is the Visit. A visit represents a combination of the person visiting, the location that they are visiting and the date of the visit. The location that is being visited is referred to as the visit location, though can be more commonly thought of as a reception.

Visit model

Example visit object

{
  "id": 11111,
  "date": "2020-10-15",
  "when": "2020-10-15T10:30:00",
  "guest": {
    "id": 22222,
    "name": "Anne Visitor",
    "email": "anne@example.com"
  },
  "host": {
    "id": 33333,
    "name": "Sally Staff-Member",
    "email": "sally@your-organisation.com"
  },
  "location": {
    "id": 1001,
    "kind": "BUILDING",
    "name": "Macquarie House"
  }
}

A visit may contain the following fields:

A person may contain the following fields:

Get visit locations

An example returning all visit locations.

curl "https://app.matrixbooking.com/api/v1/visitor/locations"
  -H "Authorization: Basic encoded_credentials"

The above command returns a JSON object with an embedded list like this:

{
  "locations": [
    {
      "id": 1001,
      "kind": "BUILDING",
      "name": "Macquarie House",
      "...": "..."
    },
    {
      "id": 2002,
      "kind": "BUILDING",
      "name": "Bathurst Place",
      "...": "..."
    }
  ]
}

This API returns the list of visit locations that have been configured for your organisation.

HTTP request

GET https://app.matrixbooking.com/api/v1/visitor/locations

Get visits

An example returning visits between two dates at a particular location.

curl "https://app.matrixbooking.com/api/v1/visitor?f=2020-10-12&t=2020-10-18&l=1001"
  -H "Authorization: Basic encoded_credentials"

The above command returns a JSON list structured like this:

[
  {
    "id": 11111,
    "date": "2020-10-15",
    "when": "2020-10-15T10:30:00",
    "guest": {
      "id": 22222,
      "name": "Anne Visitor",
      "email": "anne@example.com"
    },
    "host": {
      "id": 33333,
      "name": "Sally Staff-Member",
      "email": "sally@your-organisation.com"
    },
    "location": {
      "id": 1001,
      "kind": "BUILDING",
      "name": "Macquarie House"
    }
  }
]

This API returns a list of visits between two local dates. The list can be optionally restricted to specific visit locations (receptions).

HTTP request

GET https://app.matrixbooking.com/api/v1/visitor

Query parameters

Get a summary of visits

An example returning a summary of visits by day of week and visit location.

curl "https://app.matrixbooking.com/api/v1/visitor/summary?f=2020-10-12&t
=2020-10-18&sa=TIMESLOT&sa=LOCATION&stg=DAY_OF_WEEK"
  -H "Authorization: Basic encoded_credentials"

The above command returns a JSON list structured like this:

[
  {
    "key": {
      "location": {
        "id": 1001,
        "kind": "BUILDING",
        "name": "Macquarie House",
        "...": "..."
      },
      "timeslot": "Monday"
    },
    "count": 3
  },
  {
    "key": {
      "location": {
        "id": 1001,
        "kind": "BUILDING",
        "name": "Macquarie House",
        "...": "..."
      },
      "timeslot": "Tuesday"
    },
    "count": 5
  },
  { 
    "...": "..."
  }
]

This API returns a set of visit summaries for each combination of summary key, as requested by the caller. Dates are local to visit location (reception).

HTTP request

GET https://app.matrixbooking.com/api/v1/visitor/summary

Query parameters

Summary model

Each summary record is comprised of a key and the count of corresponding visit records for that key combination. Note that values for a particular key field will only appear if relevant to the requested summary.

A summary key may contain the following fields:

Errors

The Matrix Booking API uses the following HTTP status codes to indicate errors: