Overview

This article lists the public API endpoints in the Maptician Hybrid Office and Occupancy Management Application. These endpoints enable programmatic access to manage reservations, occupants, seats, locations, presence tracking, and other features in your Maptician environment.

Reservations

GET /ext/v1/reservations/seats

• Retrieve seat reservations within a time range based on filters.

GET /ext/v1/reservations/rooms

• Retrieve room reservations within a time range based on filters.

GET /ext/v1/reservations/user/{userID}

• Retrieve a list of reservations for the selected Occupant that occur within a provided timeframe, and optionally that occur at a specific location. Returns both seat and room reservations.

DELETE /ext/v1/reservations/user/{userID}

• Delete an Occupant's reservations (if any) that occur within a provided timeframe, and optionally that occur at a specific location.
• Deletes both seat and room reservations.

POST /ext/v1/reservations/user/{userID}/seat/{seatID}

• Create a Maptician reservation for the user specified by the userID parameter, at the seat location specified by the seatID parameter.
• The start and end times for this reservation are provided through either the body or a query string.

Occupants

GET /ext/v1/occupants/global/

• Return an array of Occupant entries reflecting the currently active occupants in the current environment.

GET /ext/v1/occupants/user/{userID}/delegates/

• Retrieve the Occupant's delegation permissions in JSON format. Users can be permitted to reserve seats and rooms "on behalf of" other occupants.

PUT /ext/v1/occupants/user/{userID}/delegates/

• Update the reservation permissions for a user within the organization. Replaces the existing reservation permissions with the new permissions specified in the request body.

Seats

GET /ext/v1/seats/

• Retrieve all active seats. Provides a comprehensive list of all the "Active" seats in Maptician, returning an array of seat objects with detailed information about individual seats such as their current status, location, and configuration.

GET /ext/v1/seats/{seatID}/

• Retrieve detailed information about a specific seat by providing the seat's unique identifier (seatID). Includes data like seat name, status, assignability, and location details.

Seat Assignments

GET /ext/v1/assignments/seats/

• Retrieve a list of seat assignments based on selected filters like time range, office location, and others. You can specify various details such as which map or user details to include, and whether to exclude certain information. To look up assignment(s) by their assignmentID, specify the assignmentID through the assignments parameter.

POST /ext/v1/assignments/seats/

• Create a permanent seat assignment, ensuring efficient space management within the organization. The seat must be in an "active" state, must be designated with a usage type that is "assignable", and there must not be any pre-existing assignments for the seat.

DELETE /ext/v1/assignments/seats/{assignmentID}

• End a specific seat assignment using the provided assignment ID. This operation will terminate the assignment permanently, and the seat will be available for new assignments.

Locations

GET /ext/v1/locations/global/

• Return an array of Location entries that represent individual locations where Occupants can be associated. Locations can be further subdivided into floors and suites through the use of those fields describing a map. Maps must be associated with a Location.

POST /ext/v1/locations/

• Create a new Location within the Maptician Environment. This Location can be associated with Occupants, Maps, and other Maptician entities.

GET /ext/v1/locations/location/{officeID}/

• Retrieve a Location from the Maptician Environment.

PATCH /ext/v1/locations/location/{officeID}/

• Update a Location within the Maptician Environment.

DELETE /ext/v1/locations/location/{officeID}/

• Remove a Location within the Maptician Environment.

Prescreen Surveys

GET /ext/v1/prescreen/completed_prescreen_surveys

• Retrieve Prescreen Survey results for completed (and optionally declined) surveys which were completed/declined during a lookback period from the current date/time.

Profile Images

GET /ext/v1/occupants/profile-images/{userID}/

• Return an Occupant's current profile image url and whether it has been modified from default/blank.

POST /ext/v1/occupants/profile-images/{userID}/

• Set an Occupant's profile image based on a provided external url location. The api will retrieve the image, crop to 140x140px, compress the resulting file, and host it within Maptician's environment. The final URL of the Maptician-hosted profile image is returned.
• Cropping occurs from the center point of the image file.

POST /ext/v1/occupants/profile-images/{userID}/form-bin

• Set an Occupant's profile image based on an image binary file being included as part of a multi-part form data body object. The binary file should be added to the property "profile" on the form data.

POST /ext/v1/occupants/profile-images/{userID}/bin

• Set an Occupant's profile image based on an image binary file being included in the request body.

POST /ext/v1/occupants/profile-images/{userID}/clear

• Clear an Occupant's profile image, resetting it to the default/blank state.

Authentication Tokens

POST /ext/v1/auth/tokens/check

• Check the general validity of a Maptician JWT API authentication token.

POST /ext/v1/auth/tokens/create

• Create a new Maptician API Authentication Token.

POST /ext/v1/auth/tokens/rotate

• Revoke a token and create a new one to help facilitate more automated token management. The old token will be deactivated immediately.

DELETE /ext/v1/auth/tokens/revoke

• Immediately revoke the API access for the API Authentication Token provided in the request body.

IP Address Access Events

POST /ext/v1/ip/access_event

• Submit an IP Access Event, representing an Occupant accessing a system or network from a public IP Address. Only a single user identifier needs to be provided (email / userID / employeeID / externalId / name) to be valid.

POST /ext/v1/ip/access_events

• Submit an array of IP Access Events (representing Occupants accessing a system or network from public IP Addresses). Only a single user identifier needs to be provided for each entry (email / userID / employeeID / externalId / name) to be valid.

Presence

POST /ext/v1/presence/presence_entry

• Set the real-time presence status of an Occupant within your Maptician environment. The presence can only be set for the current point in time, and cannot be set for past or future times. Generally intended to be the receiving endpoint for a connection to an access control system, network monitor, or other source of real-time presence data.

POST /ext/v1/presence/checkout

• Clear an Occupant's current presence status (i.e., checks the Occupant out). This sets the user's presence state to clear. You must identify the Occupant using one of the supported identifiers.

POST /ext/v1/presence/presence_entries

• Create or update presence states for multiple Occupants in a single request. The request body can either be an object with an entries array, or a single entry object.

POST /ext/v1/presence/time_bounded

• Create one or more presence entries characterized by each data entry having a start and an end time. These entries are intended to allow for the time-bound presence entries resulting from entrance and exit-controlled systems or other detailed presence tracking methods.

POST /ext/v1/presence/entry_times

• Create one or more presence entries characterized by each data entry having a start date/time entry, but not an exit entry. Since we do not have end times associated with this data, the end time of the presence entries is assumed to be the end of each day or a configurable end-of-day time.

POST /ext/v1/presence/dates_only

• Create one or more presence entries characterized by each data entry having a start date only. These entries are intended to allow for presence entries to be created from data sources that only provide an entry date. The duration of the entry is the entire date indicated (unless restricted based on start and end time configurations).

POST /ext/v1/presence/leave_dates

• Create one or more presence entries characterized by each data entry having a start and an end time. These entries are intended to allow for time-bound presence entries for dates during which occupants will be on leave or otherwise not working.

POST /ext/v1/presence/present_and_reserve

• Mark an occupant as present and reserve their owned seat. Intended to be used in conjunction with a "restricted reservable" or "owned reservable" hotel seating strategy. If the user has a reservable seat where they are specifically marked as a permitted reserver, they will be booked for that seat for the day (or the rest of the day) if that seat is available.

Map Export

GET /ext/v1/maps/{mapID}/html/

• Return an HTML page consisting of a non-live copy of the current version of the specified map.

GET /ext/v1/maps/{mapID}/svg/

• Return an SVG file of a non-live copy of the current version of the specified map.

GET /ext/v1/maps/{mapID}/png/

• Return a PNG file of a non-live copy of the current version of the specified map. Note that this export currently does not support the "Seat" layer.

GET /ext/v1/maps/{mapID}/webp/

• Return a WebP file of a non-live copy of the current version of the specified map. Note that this export currently does not support the "Seat" layer.