Mazévo has a built-in API (application programming interface) available to all customers who use the system.
API Calls
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.
- 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, if the building is closed all day, the 'closedAllDay' field will be false. 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
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.
- 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.
- 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, ContactID (primary contact only). Parameters: EventID
GetEvents 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.
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 organization called Basket Weavers Club 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. Passing OrganizationID = 0 will return all organizations. Passing OrganizationTypeID will return all organizations of that type. Passing ExternalID will return all organizations with that externalID.
- AddOrganizations (Post) - Adds one or more organizations. 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 email of the contact 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 prior to an invoice being created; thus, a deposit is tied to the event.
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, it is recommended to create a different key for each integration.
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": []
}