GuideReference

Data Model

Pencil Spaces offers a sophisticated and flexible data model designed to accommodate a wide variety of use cases. Whether you’re building a marketplace integration or using our administration workflows to run your tutoring company, our API allows you to do everything that you can do in the app, in code.

This reference guide outlines the core data model entities and their relationships to help you integrate with Pencil Spaces.

InstitutionsCopied!

The Institution entity represents your organization or company within Pencil Spaces. If you have API access, you have an Institution Admin role in your institution. An institution can own and manage all the entities listed in our data model, including Spaces, Users, or Events.

SitesCopied!

If enabled, Sites are “sub-institutions” with your institution representing, for example, a school. If Sites are enabled, Institution Admins have access to data across all sites. All other users, however, must be tagged to a set of sites. Moreover, Spaces and Events must always be tagged to a site when they are created, to avoid issues with data protection.

UsersCopied!

Users represent individuals affiliated with an institution. Each user has a unique email address (our primary key for users) and a role that defines their level of access and permissions in your institution.

RolesCopied!

Roles grant users in your Space permissions to create Spaces, manage settings, and access data. We allow the following roles:

  • Institution Admins: Access to edit all settings, invite other users, and have visibility of all institution data

  • Site Admins: Access to all data within their assigned sites

  • Teachers: Access to create Spaces and join Spaces as host (configurable)

  • Student: No special access

Role permissions are customizable via Settings, allowing you to tailor them to your specific operational needs.

EventsCopied!

Events symbolize a planned activity within an institution, which can take place either online or offline. Online events must be linked to a specific Space.

People can be added to an event in two roles: Attendee or Organizer. If applicable, organizers are automatically granted host permissions to the Space associated with the event. Organizers also have access to various event editing capabilities, depending on the configuration settings for your institution.

Events form the basis for our attendance system. Once an event has concluded, most event properties become immutable to preserve the accuracy of attendance records. Moreover, multiple events cannot be hosted in the same Space at once.

AttendanceCopied!

The Attendance entity tracks participation by people for each event. Each attendance record pairs a user with an event, with status such as Present, Late, and Absent. Notes can be attached to attendance records to provide additional context, and statuses for online events are automatically updated when users join the associated Space.

When an event is in progress, hosts and event organizers can change attendance records (except their own). Once the event concludes, however, only admins can change event records.

SpacesCopied!

A Space represents a persistent virtual workspace within Pencil Spaces. Spaces are tagged to your institution. Unlike video calls, Spaces are persistent, allowing users to re-enter the same workspace as needed whenever they’d like.

Spaces can be set to either public or private, determining their visibility and accessibility. Users in a Space do not necessarily have to part of your institution. You’re free to share a Space link to a public Space, and any user with access to the link can join.

PermissionsCopied!

Ownership and access rights of users within a Space are structured as follows:

  • [Automatically assigned as host] Admin: Users who are admins of the institution associated with the Space. These users cannot be removed from the Space once they’ve joined it.

  • [Automatically assigned as host] Owner: The original creator of the Space, who holds permanent ownership and cannot be removed.

  • Hosts: Users granted elevated privileges to manage calls and participants. Hosts can remove or change the roles of other non-admin non-owner hosts.

  • Participants: Users with limited permissions, typically restricted to joining calls and editing boards.

RoomsCopied!

Within each Space, multiple rooms can be created to facilitate breakout sessions and focused discussions.

By default, every Space includes a single room called a Main Rooms . Additional rooms can be dynamically generated as the need arises, offering flexibility during collaborative sessions.

SessionsCopied!

A Session is automatically created whenever at least one user is present within a Space. That is to say, sessions will be generated in cases where a user is reviewing content by themselves, as well as for multi-user discussions.

Sessions are ended automatically after five minutes of inactivity or when all Space users exit the Space. You also have the option to manually end sessions through the endOngoingSession API endpoint.

In cases where a session in a Space spans multiple rooms, the session will contain information individually for each room as well as aggregated information summed across each room.

It is important to note that sessions are an independent of events. They may overlap with events, but there’s no guarantee that a 1:1 relationship exists between sessions and events.

RecordingsCopied!

A Recording captures audio and video content from a specific Space and Room during a defined period of time while a call is active.

Recordings may span across multiple sessions or events, offering a comprehensive archive of activities. These recordings operate as independent entities, capable of capturing overrun meetings or cross-session content. Programmatic management of recordings is available through the API, providing developers with fine-grained control.

Custom attributesCopied!

Spaces, Events, and Users can be tagged with data fields that are unique to your institution. For example, if you wanted to target a user with Subject: Geography and Grade: 5, you can do-so via custom attributes.

Custom attributes can be assigned to a user via API and can be used to filter Spaces, Events, or Users via the filter panel.