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
- 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.
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 Available Filters: BuildingIds, RoomIDs, EventTypeIDs, StatusIDs, ResourceIDs, Optional Parameter: minDateChanged. 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). To return canceled bookings, you need to pass in a list of status IDs. For bookings with an associated room diagram (link or file), the call returns hasDiagram True. This call has an optional parameter, Minimum Date Changed. Only bookings with critical changes (date, time, status, room) after this date/time will be returned when using this optional parameter.
- 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.
Academic Calls
The following call is used to load academic courses into Mazévo:
- ImportTerm (Post) - Used to upload academic course data for an entire 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 would be used to send 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 that are 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 will always have 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) - Used to upload a payment tied 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 are used to 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, 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 (Get) - Returns a list of bookings for the contact. Parameters: token (from Authenticate call passed as bearer token).
- 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 that will be used for integrations using Mazévo's public API calls. If you are creating multiple integrations with Mazévo, creating a different key for each integration is recommended.
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 will need to delete the key and create a new key.
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) Press Create, and the API key will be displayed.
5) 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.
6) 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": []
}