Facilitron Public API Overview

The Facilitron Public API provides access to properties, facilities, and events data for organizations (e.g. school districts). This API enables third-party partners to query S&R events data in near real-time through a secure, scalable interface.

Getting Started

To begin using the Facilitron Public API:

1. Request API Credentials: Contact [email protected] to request an API User ID and API Key.
2. Determine Access Scope: API access is granted at the parent level (e.g. district), with access to all children (e.g. schools) within that parent.
3. Review Documentation: Familiarize yourself with the available endpoints and data restrictions.
4. Test Your Integration: Start with small date ranges and limited queries while testing.

Authentication

All API calls require authentication using:

• API Key: Security token (passed in Authorization header)

Example:

Code
 
curl --location --request GET 'https://api.external.facilitron.com/properties' \
--header 'Authorization: Bearer YOUR_API_KEY'

Note: API keys do not expire but can be revoked by Facilitron administrators if misused or compromised. If you suspect your credentials have been compromised, contact support immediately.

Data Hierarchy

The Facilitron API is organized around a hierarchical data structure:

1. Properties (Locations)

   • Parents: Organizations that may include children (e.g. school districts with schools)
     • Contains references to all child properties in its properties array
   • Children: Organizations that have a parent (e.g. specific schools)
     • Belong to a parent property (e.g. district property)
     • Contain no child properties (empty properties array)

2. Facilities

   • Each property (whether parent or child) can have multiple facilities
   • Examples: gymnasiums, auditoriums, fields, classrooms, cafeterias
   • Each facility belongs to exactly one property

3. Events

   • Each event (reservation) is associated with a property
   • Events can span multiple facilities within that property
   • Events can span multiple days and each day can have multiple timeslots if of type "reservation"
   • Events have various types (e.g. "reservation", "maintenance-block")
   • Each event has a status (e.g. "Approved", "Pending", "Cancelled", "Declined")

4. Timeslots

   • Each event contains one or more timeslots
   • Timeslots specify when a particular facility is reserved
   • Each timeslot references a specific facility
   • Timeslots include start and end date times
   • Timeslots may have specific activity names within the overall event

This hierarchy allows you to navigate from a parent organization (e.g. district) down to individual timeslots, with each level providing more specific information about property usage.

API Usage Flow

A typical usage pattern follows these steps:

1. Get Properties: Retrieve all properties (e.g. parents and children) that you have access to using /properties if you don't already know the property ID you want to work with.

2. Select Property: Determine which property you want to work with and note its _id for use in subsequent API calls.

3. Choose Access Level: Decide whether to work with events at the property level or facility level.

   • Property Level: Good for getting all events across a property, but can be slower and will possibly return a lot of data.
   • Facility Level: Recommended when there are many events or when you only need events for specific facilities.

4. Access Events:

   • If working at the property level:
     • Call v1/property/{property_id}/events with your chosen property ID.
   • If working at the facility level:
     • First, get all facilities for your chosen property using v1/property/{property_id}/facilities.
     • Note the _id of each facility you're interested in.
     • Then, retrieve events for each specific facility using v1/facility/{facility_id}/events.

5. Optional: For detailed information about a specific event, use /event/{event_type}/{event_id} once you have the event ID from earlier calls.

For high-volume properties, working at the facility level can significantly improve performance and reduce the data volume returned by each API call.

Data Restrictions

• Event data is only available for up to 1 year from the query date
• A single API call can request a maximum date range of 31 days
• Past date information is not available
• API usage is limited to a quota of queries per 24-hour period

Implementation Details

The API is implemented using serverless AWS Lambda functions with the following characteristics:

• Read Operations: GET endpoints have a 5-second timeout
• Write Operations: POST and PATCH endpoints have a 35-second timeout
• Memory Allocation: Each Lambda function is allocated 256MB of memory
• Runtime: Node.js 22.x runtime environment
• Logging: JSON-formatted logs with INFO level detail
• Monitoring: DataDog integration for observability and performance tracking

Performance Considerations

• API keys are rate-limited to prevent excessive usage
• MongoDB database queries are optimized for performance
• Events are indexed by date range for faster retrieval
• Lambda cold starts may cause occasional initial request delays
• Event endpoints with large date ranges may experience longer response times

Response Format

All API responses follow a consistent structure:

For successful responses:

Code
 
{
   "message": "Human-readable result message",
   "message_code": "Specific code (e.g. A007, EV001)",
   "invocation_id": "Unique request identifier",
   "SOME_DATA_FIELD": { /* Response data specific to the endpoint, like properties, facilities, events, etc. */ }
}

For error responses:

Code
 
{
   "message": "Human-readable error description",
   "message_code": "Specific code (e.g. PR001, SY001)",
   "invocation_id": "Unique request identifier"
}

Pagination and Filtering

The API does not currently support pagination for large result sets. Instead, use date range filtering to limit the volume of data returned. For events, consider:

• Using smaller date ranges (1-7 days) for high-activity facilities
• Filtering by event_types to narrow results
• Making separate calls by facility rather than property-wide queries when possible

For properties with many facilities, all facilities are returned in a single response. Please plan accordingly if you're working with large school districts.

Data Types and Formats

• Dates: All dates use ISO 8601 format (YYYY-MM-DD)
• Date-Times: All date-times use ISO 8601 format (YYYY-MM-DD'T'HH:MM) in the property owner's timezone
• IDs: Alphanumeric strings of varying length
• Status Values: Common values include "Approved", "Pending", "Cancelled", "Declined"
• Event Types: Common values include "reservation" (Coming soon: "maintenance-block")
• Rate Categories: Common values include "Internal", "External", "District Internal"

Dates and Timezones

The Facilitron API handles all dates and times in the property owner's local timezone:

• Property Timezone: Each property includes a timezone field (e.g. "America/Los_Angeles", "America/New_York")
• Date Format: Simple dates use ISO 8601 format (YYYY-MM-DD)
• Time Format: Date-times use ISO 8601 format (YYYY-MM-DD'T'HH:MM)
• No UTC Conversion: The API doesn't convert times to UTC - all times are in the local timezone of the property
• Input Parameters: Date parameters (like start_date and end_date) should be provided in the property's timezone
• Response Data: All date-times in responses are returned in the property's timezone

Timezone Handling Best Practices

When working with the API from different timezones:

1. Store Property Timezone: Always store the timezone value from property responses
2. Convert for Display: Convert times to the end-user's timezone only for display purposes
3. API Requests: Use the property's timezone when constructing date ranges for API requests
4. Date Arithmetic: Be careful with date calculations across timezone boundaries
5. Event Spans: Remember that a single event may span multiple dates in the property's timezone

Example of accessing the property timezone:

Code
 
{
   "property": {
      "_id": "67d3ca78934e4730d41310bd2",
      "name": "Example High School",
      "timezone": "America/Los_Angeles",
      // ...other property fields...
   }
}

Data Restrictions

• Event data is only available for up to 1 year from the query date (with the exception being that if an event falls within your date range, the API will return all timeslots for that event, both in the past and for more than one year)
• A single API call can request a maximum date range of 31 days
• Past date information is not available (see above as an exception)
• API usage is limited to a quota of queries per 24-hour period
• Any fields where no data exists will be returned as null

Rate Limiting

The API enforces rate limits to ensure system stability:

• Default Quota: 15,000 requests per 24-hour period per API User ID
• Default Rate Limit: 120 requests per minute per API User ID
• Quota Increases: Available upon request with justification
• Status Code: 429 (Too Many Requests) is returned when quota is exceeded, with a simplified response structure
• Recovery: Quotas reset at midnight UTC

Best practices for managing rate limits:

• Cache frequently accessed data when possible
• Implement exponential backoff for retry attempts
• Request data only when necessary rather than polling

Implementation Details

The API is implemented using serverless AWS Lambda functions with the following characteristics:

• Read Operations: GET endpoints have a 30-second timeout
• Write Operations: POST and PATCH endpoints have a 30-second timeout (Coming soon)
• Logging: JSON-formatted logs with INFO level detail
• Monitoring: observability and performance tracking of all calls

Performance Considerations

• API keys are rate-limited to prevent excessive usage
• Lambda cold starts may cause occasional initial request delays
• Event endpoints with large date ranges may experience longer response times

Error Codes

The API uses specific error code categories:

• PR###: Property-related errors (e.g. PR001: Property not found)
• FC###: Facility-related errors (e.g. FC001: Facility not found)
• EV###: Event-related errors (e.g. EV002: Time slot not found)
• SY###: System-related errors (e.g. SY001: Validation failed, including invalid date ranges)
• AU###: Authentication errors (e.g. AU002: Unable to authenticate)
• A###: Success codes (e.g. A007: Properties retrieved successfully)

Error Handling

The API implements comprehensive error handling:

• Validation Errors: Return 400 Bad Request with specific error message
• Authentication Errors: Return 401 Unauthorized when API keys are missing or invalid (follows HTTP Problem Details format)
• Not Found Errors: Return 404 Not Found when resources don't exist
• Rate Limiting: Return 429 Too Many Requests when quotas are exceeded (note: these responses have a simplified structure with only a message field)
• Server Errors: Return 500 Internal Server Error for unexpected issues
• Timeouts: Return 503 Service Unavailable for operations exceeding time limits

For detailed error handling information, see the Error Handling Guide.

API Endpoints

Get Properties

Retrieve all properties available to the authenticated user.

Endpoint: GET /v1/properties

Implementation Notes:

• Lambda function: external-generic-api-get-all-properties
• Returns parent locations (e.g. district offices) at position 0, followed by child locations (e.g. school properties)

Example Request:

Code
 
curl --location --request GET 'https://api.external.facilitron.com/v1/properties' \
--header 'Authorization: Bearer YOUR_API_KEY'

Example Response:

Code
 
{
   "message": "Properties retrieved successfully – The property details have been successfully retrieved.",
   "message_code": "A007",
   "invocation_id": "302215af-612e-4fc5-92ec-285ed0c19feb",
   "properties": [
      {
         "_id": "67d3d98234e4730d41310bd2",
         "u_id": "139d71e8662595e3ba37",
         "name": "Example High School District",
         "address": "123 Example str.",
         "city": "Example city",
         "state": "CA",
         "zip": "00000",
         "timezone": "America/Los_Angeles",
         "properties": ["67d3ca78934e4730d41310bd9", "67d3cb01934e4730d41310be0"]
      },
      {
         "_id": "67d3ca78934e4730d41310bd9",
         "u_id": "283f71c5237595e3ba42",
         "name": "Example High School",
         "address": "123 Example str.",
         "city": "Example city",
         "state": "CA",
         "zip": "00000",
         "timezone": "America/Los_Angeles",
         "properties": []
      }
   ]
}

View detailed documentation →

Get Property by ID

Retrieve details for a specific property by ID.

Endpoint: GET /v1/property/{property_id}

Implementation Notes:

• Lambda function: external-generic-api-get-property-by-id
• Verifies API user has access to the requested property
• Parent locations (e.g. district offices) include a properties array with child property IDs

View detailed documentation →

Get Facilities

Retrieve all facilities for a specific property.

Endpoint: GET /v1/property/{property_id}/facilities

Implementation Notes:

• Lambda function: external-generic-api-get-facilities-by-property-id
• Returns only active facilities (status = 0)
• Includes both searchable and non-searchable facilities
• Excludes virtual facilities, which are organizational containers used to group other facilities (e.g. classrooms within a school)

View detailed documentation →

Get Events by Property

Retrieve events for a specific property, filtered by date range and event types.

Endpoint: GET /v1/property/{property_id}/events

Implementation Notes:

• Date range maximum: 31 days
• Returns events across all facilities for the property
• Returns all time slots for events, even those beyond the requested date range

View detailed documentation →

Get Events by Facility

Retrieve events for a specific facility

Endpoint: GET /v1/facility/{facility_id}/events

Implementation Notes:

• Date range maximum: 31 days
• Returns all time slots for events, even those beyond the requested date range
• Supports filtering by comma-separated event_types

View detailed documentation →

Get Event by ID

Retrieve a specific event by its ID and type.

Endpoint: GET /v1/event/{event_type}/{event_id}

Implementation Notes:

• Supports lookup by Facilitron ID or external system ID
• Returns all time slots associated with the event

View detailed documentation →

Write Operations (Coming Soon)

The following endpoints are available for internal use only:

Create Internal Event

• Endpoint: POST /event
• Timeout: 30 seconds

Cancel Internal Event

• Endpoint: PATCH /event/{event_type}/{event_id}
• Timeout: 30 seconds

Change Timeslot of Internal Event

• Endpoint: PATCH /event/{event_type}/{event_id}/timeslot
• Timeout: 30 seconds

Frequently Asked Questions

General Questions

Q: Is there a sandbox or test environment available?
A: No, there is no separate sandbox environment. However, you can test with a limited set of API calls to verify your integration.

Q: Do API credentials expire?
A: No, API credentials do not expire but can be revoked by administrators if misused.

Q: How are API updates communicated?
A: Facilitron will notify all API users via email before significant changes.

Technical Questions

Q: How should I handle timezone differences?
A: All date-times are returned in the property owner's timezone, which is specified in the property details.

Q: What's the best way to efficiently retrieve events?
A: Use the smallest possible date range and specific event types to limit data volume.

Q: Can I increase my API rate limit?
A: Yes, contact [email protected] with your use case to request a rate limit increase.

Q: Is there a way to receive event updates rather than polling?
A: Currently, the API only supports polling. Webhook notifications may be added in future versions.

Q: How should I handle 503 Service Unavailable errors?
A: Implement exponential backoff and retry the request a few seconds later.

API Versioning

The current API version is v1. Versioning is included in the URL path. Facilitron follows semantic versioning principles:

• Major Version Changes: Breaking changes that require client modifications
• Minor Version Changes: New features added in a backward-compatible manner
• Patch Version Changes: Bug fixes and non-breaking improvements

Facilitron will provide at least 90 days notice before deprecating any API version.

Need Help?

For questions, issues, or support, contact [email protected] with the following information:

1. Your API User ID (never include your API Key in emails)
2. Detailed description of your issue
3. Any error messages, including invocation_id values
4. Date and time of errors
5. Request details (endpoint, parameters)