Mazévo has a built-in API (application programming interface) available to all customers who use the system.
Internal Record ID Calls
The following calls are used to retrieve internal record IDs. The IDs returned by these calls will be used with other calls to filter the results. All results for all calls are returned in JSON.
Most of these calls only need to be called once for the programmer to get the ID of a record that can be passed into other calls. For example, the Buildings call will return the ID and name for all buildings in the system. The ID of a building will never change, so once you, as the programmer, have the value, you really don't need to use the call again.
- Buildings (Get) - Returns a list of Buildings.
- Rooms (Post) - Returns a list of Rooms. Available Filters: BuildingID
- RoomTypes (Get) - Returns a list of Room Types.
- ServiceProviders (Get) - Returns a list of Service Providers.
- Resources (Get) - Returns a list of Resources. Available Filters: ServiceProviderID
- ResourceGroupings (Get) - Returns a list of Resource Groups. Resource Groups are used to categorize resources.
- Statuses (Get) - Returns a list of Statuses.
- EventTypes (Get) - Returns a list of Event Types.
- BuildingHours (Post) - Returns the opening and closing time for a specific building for a selected date. Additionally, the 'closedAllDay' field will be false if the building is closed all day. Parameters: Building ID, Date
- OrgTypes (Get) - Returns a list of organization types.
- GetContact (Get) - Returns a single contact. Parameter: ContactID
- InvoicingDepartments (Get) - Returns a list of invoicing departments
- EventQuestions (Get) - Returns a list of event questions, including all of the details of the question definition.
The following calls are licensed separately for managing the resources of an external service provider:
- ExternalServiceProviders (Get) - Returns a list of External Service Providers.
- ExternalResources (Get) - Returns a list of External Resources.
- AddExternalResource (Post) - Adds a single external resource record. The description is required.
- UpdateExternalResource (Post) - Updates a single external resource record.
- GetEventswithExternalResources (Post) - Returns a list of bookings and their associated external resources.
- Parameters: Start Date/Time, End Date/Time.
- Available Filters: BuildingIds, RoomIDs, EventTypeIDs, StatusIDs.
- Optional Parameter: minDateChanged. Only bookings with critical changes (date, time, status, room) after this date/time will be returned when using this optional parameter.
Event Data Calls
The following calls return event-related data. For each call, different parameters and filters are available.
- GetEvents( Post) - Returns a list of events (bookings) based on the filters passed into the call.
- Parameters: Start Date/Time, End Date/Time - Optional if passing in BookingIds.
- Available Filters: BuildingIds, RoomIDs, EventTypeIDs, StatusIDs, ResourceIDs, ContactID, OrganizationID, BookingIDs.
- Optional Parameter: minDateChanged. When using this optional parameter, only bookings with critical changes (date, time, status, room) after this date/time will be returned.
- Optional Parameter: includeEventCoordinators (True/False). If True, event coordinators will be returned with the call. If not specified on the call, it defaults to false.
- Notes: If you don't pass in a filter for statuses, only statuses that book space will be returned (i.e., canceled bookings will not be returned).
- You need to pass in a list of status IDs to return canceled bookings or bookings with non-book space statuses.
- For bookings with an associated room diagram (link or file), the call returns hasDiagram True.
- GetResourceDetails( Post) - Returns a list of resources requested for each booking. Parameters: BookingIDs, ResourceIds (optional). Resource IDs are used to limit the results to specific resources. If no resource IDs are passed in, all resources for each booking are returned.
- GetEventsWithResourceDetails(Post) - Returns a list of bookings and their associated resources. Parameters: BookingIDs.
- TodaysEvents (Post) - Returns a list of the events (bookings) for a specific room for the current day. This call is used for room signage applications. Parameters: RoomID
- EventInfo (Post) - Returns the Event Name, Organization, OrganizationID, ContactName, and ContactID (primary contact only). Parameters: EventID
- RoomDiagram (Get) - Returns the URL or base64 string for the booking's room diagram. IsLink is returned as a true/false value. If IsLink is true, the filename is the full URL to the image. If IsLink is false, the file element will contact a base64 string that contains the image.
- GetEventsbyQuestion (Post) - Returns a list of bookings within the date range with the selected question tied to the event.
- Parameters: Start Date/Time, End Date/Time, EventQuestionID.
- GetEventswithEventQuestions (Post) - Returns a list of bookings within the date range and all questions and answers tied to the event.
- Parameters: Start Date/Time, End Date/Time, EventQuestionID.
- Available Filters: BuildingIds, EventTypeIDs, StatusIDs.
- Optional Parameter: minDateChanged. Only bookings with critical changes (date, time, status, room) or changes to the event question answers after this date/time will be returned when using this optional parameter.
Academic Calls
The following call is used to load academic courses into Mazévo(these calls are in the PublicCourses directory):
- ImportTerm (Post) - Used to upload academic course data for an entire term. Sending a parameter of ingoreUnmatchedRooms = True will discard courses that are not matched to Mazevo buildings and rooms.
- Term (Get) - Returns a list of Terms.
- FinalExams (Post)- Returns each course's final exam date/time/location.
Parameters: TermID. - Rooms (Get) - Returns a list of academic buildings, room codes, and the associated building and room IDs from Mazevo. Parameters: TermID, BuildingID. Calling this endpoint without passing in TermID or BuildingID will return all building and room records. If you pass in a TermID, the list of buildings and rooms will be limited to the ones referenced in that term.
Organization & Contact Calls
The following calls are used to manage Organizations, Contacts, and Organization/Contact relations (these calls are in the PublicMembership directory):
- Organizations (Post) - Used to upload a list of organizations. This call sends a list of student organizations to Mazévo.
- Contacts (Post) - Used to upload a list of contacts. This would be a list of all students associated with one or more organizations. Each contact would appear on this list one time.
- OrgMembership (Post) - Used to tie organizations and contacts together.
When using Organizations, Contacts, and OrgMembership calls, you must push up all records for each call, not just new or changed records. Mazévo will add new records, update existing records, and disable (or delete if never used) records. Each record will need to have a unique ID that is passed into the call. For example, the Basket Weavers Club organization always has the same ID, 1001, passed to the call.
The following calls are used to add or change organizations, contacts, and the organization/contact relationships (these calls are in the PublicOrganization directory):
- Organizations (Post) - Returns a list of organizations. Available Filters: OrganizationID, OrganizationTypeID, ExternalID, IncludeDisabled. Passing OrganizationID = 0 will return all active organizations. Passing OrganizationTypeID will return all organizations of that type. Passing ExternalID will return all organizations with that externalID. By default, the call only returns non-disabled (active) organizations. To include disabled records, use the parameter IncludeDisabled (true/false).
- AddOrganizations (Post) - Adds one or more organizations. A name is required. Duplicate organization names will not be added. The call returns the entire data set, including the organization ID for each new organization.
- UpdateOrganizations (Post) - Updates one or more organizations. Duplicate organization names will not be updated. All data elements, including organizationID, are required.
- Contacts (Post) - Returns a list of contacts. Available Filters: ContactID, Email, FirstName, LastName, OrganizationID, ExternalID. Using Email, FirstName, or LastName will return only exact matches (no partial string searching). Passing in ContactID will return a single record. Passing in OrganizationID will return all contacts associated with that organization. Passing ExternalID will return all contacts that match the value passed. Passing ContactID = 0 with no other filters will return all contacts.
- AddContacts (Post) - Adds one or more contacts. First name, last name, and email required. The call returns the entire data set, including the ID assigned to the new contacts.
- UpdateContacts (Post) - Updates one or more contacts. All fields are required to be passed.
- AddAssociation (Post) - Associates a list of contacts and organizations, passed in as a pair (Contact, Organization).
- RemoveAssociation (Post) - Removes a contact/organization association. The contact and organization will not be updated, just the relationship.
If a contact is added or updated and the contact's email matches that of a user record, the contact will be tied to the user record if the user is not already associated with another contact record.
Invoicing and Payment Calls
The following calls are used to retrieve invoice data and to create payment and deposit entries.
InvoicingDepartments, AddDeposit, AddPayment, and Invoice are in the PublicInvoicing directory.
- Invoice (Post) - Used to return the invoice information for a single invoice number.
- AddPayment (Post) - Add a payment to an existing invoice.
- AddDeposit (Post) - Used to upload a deposit tied to an event. Deposits are payments received before an invoice is created; thus, a deposit is tied to the event.
User and Security Calls
The following calls are used to retrieve and update user accounts. The calls in this section are licensed separately from all other calls. The calls are in the PublicUser directory.
- SecurityPolicies (Get) - Returns a list of all security policy records.
- GetRequester (Post) - Returns a single user's email, first name, last name, phone, and security policy ID. Parameters: email.
- UpdateRequesterSecurity (Post) - Used to update a single user's security policy. Parameters: email, newSecurityPolicyID.
- UpdateRequester (Post) - Used to update a single user's account details. Parameters: email, newFirstName, newLastName, newPhoneNumber, newSecurityPolicyID. The email address can not be changed with this call.
- NewRequesters (Get) - Returns a list of new user accounts created by SSO.
Create Booking Calls
The following calls manage a contact's bookings (create and cancel). The calls in this section are licensed separately from all other calls. The calls are in the PublicRequest directory.
- APIVersion (Get) - Returns the current version of the API. This is primarily used to test connectivity to the Mazevo API endpoint.
- Authenticate (Post) - Returns a security token passed into other public request calls. Parameters: contact email, security policy ID. The token expires after 10 minutes. This call can also create a new contact by passing in the following optional parameters: firstName, lastName, and autoCreateContact. Auto Create contact is a true/false parameter; if set to true, it will attempt to create a new contact record using the email and name parameters. The call returns a token and the contact ID of the new contact.
- GetMyRooms (Get) - Returns a list of buildings and rooms tied to the security policy. Parameters: token (from Authenticate call passed as bearer token).
- GetMyBookings (Post) - Returns a list of bookings for the contact. Parameters: token (from Authenticate call passed as bearer token), Optional Parameters: Start Date/Time, End Date/Time. If the start and end date/times are passed in, the call returns the bookings for the contact within that date range. Otherwise, it returns only current and future bookings.
- CreateBooking (Post) - Creates a booking and associated event record. Parameters: token (from Authenticate call passed as bearer token), EventName, RoomID, Attendance, StartDateTime, EndDateTime.
- CancelBooking (Get) - Cancels a single booking, setting the status to the appropriate status in the security policy. Parameters: token (from Authenticate call passed as bearer token), BookingID.
API Keys
Global administrators create API keys for integrations using Mazévo's public API calls. You should create a different key for each integration if you are creating multiple integrations with Mazévo. For API Keys created after October 31, 2024, you will select which calls can be made using the API key. If you use the key and call an unauthorized endpoint, the system will return a 401 error.
Once the key is created, the unique string is no longer visible, so copy the key to a safe place. If you lose the key, you must delete it and create a new one.
1) To create a new API key, navigate to API Keys found under the system menu:
2) Press Create API Key.
3) Enter a name/use for the API Key.
4) Select the calls that this key can use.
5) Press Create, and the API key will be displayed.
6) Press Copy to copy the key to your clipboard. Immediately save this private key in a document for retrieval. Once you close this window, the key will no longer be visible again.
7) Confirm that you have saved the key by pressing Yes.
API URL
The API URL is displayed at the top of the API Keys screen.
API Documentation
Examples of passing in data to an API call
1) Parameters to return data for all event types and buildings with ids 1 and 3 within the date range.
{
"start": "2020-11-01T14:00:00-06:00",
"end": "2020-11-04T15:30:00-06:00",
"buildingIds": [1,3],
"eventTypeIds": []
}
2) Parameters to return data for all buildings and all event types within the date range:
{
"start": "2020-11-01T14:00:00-06:00",
"end": "2020-11-04T15:30:00-06:00",
"buildingIds": [],
"eventTypeIds": []
}