Resident Management API - Overview

The Resident Management API allows Eleven partners and customers or third-party systems to manage resident data in Site Manager programmatically. Using the Resident management API eliminates the need for property staff to manually enter data in the Site Manager graphical user interface (GUI) and can be used with Integrated Mode in Site Manager.

If you want to start interacting with the Resident Management API immediately, navigate to the API Reference page and then download the Resident Management Postman Collection we have created.

Change Log

Base URL

All API requests must use the following base URL:

https://api.11os.com/v2

Request Body Objects

All request body objects must use the media type header Content-Type: application/json.

Responses

The Resident Management API returns JSON objects in all responses. For example, the Get /team/{TeamId}/site/{SiteId}/resident/{ResidentId} endpoint returns an individual resident account that looks like this:

Status: 200

Successful operation

{
    "Error": null,
    "Residents": [
        {
            "ActivationDate": "2021-11-05T14:10:22",
            "ActivationDateUTC": "2021-11-05T21:10:22.844348+00:00",
            "Building": "Hudson",
            "DeactivationDate": "2022-11-06T11:00:00",
            "DeactivationDateUTC": "2022-11-06T19:00:00+00:00",
            "Email": "cwilson@email.com",
            "FirstName": "Chris",
            "Floor": "1",
            "LastName": "Wilson",
            "Mobile": null,
            "OnboardedAt": "2021-11-05T21:10:28",
            "Phone": "543-678-9012",
            "ResidentId": "94adae3b-9eb8-4f1a-a64c-9065caba22c8",
            "SSID": "Wraeclast Heights",
            "ServiceAreaNumber": "OD-808-78",
            "Status": [
                "current",
                "pending"
            ],
            "UUID": "94adae3b-9eb8-4f1a-a64c-9065caba22c8",
            "Unit": "105"
        }
    ]
}

Pagination

Currently, the Resident Management API does not support pagination.

Organizational Schema

Site Manager is organized into a hierarchical structure of teams, sites, and residents.

Teams consist of sites, which then contain residents.

To access and manage resident data, you have to obtain the TeamId from the team and SiteId from the site where you want to manage residents. When managing individual residents, a ResidentId is also required.

PAN Mappings

Site Manager uses Personal Area Network (PAN) mappings to configure each resident's unit for internet access. PAN mappings link ElevenOS to the on-premises network hardware creating the configuration for each unit.

Like the Site Manager Organizational Schema, PAN mappings are organized into a hierarchical structure where Buildings consist of Floors, which then contain Units. The Building and Floor values are optional, and PAN Mapings must include Units - except for MDU SSO site types. PAN mapping configurations can have:

• multiple Buildings with Units and no Floors,
• multiple Floors with Units and no Buildings,
• multiple Units with no Buildings or Floors,
• or only Buildings without Floors or Units (MDU SSO).

It is also important to note that each Site Manager MDU site type may use PAN mappings differently and require different PAN mapping values. The differences between how each MDU site type uses PAN Mappings are based on the site's network topology, authorization service, or identity provider (IDP).

Network Topologies

There are two network topologies that MDU site types can use:

• Centralized - Centrally managed Wireless LAN Controller broadcasting a single site-wide SSID.
• Distributed - Individually managed gateway and access point (AP) with a unique SSID per unit or Building.

Authorization Services

MDU PPK-C Sites where the controller broadcasts a single site-wide SSID can use an external authorization service to manage passphrases per SSID/resident. The use of an authorization service allows you to generate multiple pre-shared keys for a single site-wide SSID. Some examples of authorization services are below:

• Eleven Personal Pass Key (EKMS) - Eleven's in-house authorization service.
• Dynamic Pre-Shared Key (DPSK) - Ruckus Cloudpath authorization service.
• Easy Pre-Shared Key (EPSK) - Cisco authorization service.

Identity Providers (IDP)

The MDU SSO site type uses an external IDP to authorize residents through Single-Sign-On (SSO).

PAN Mapping Values

Table-1 below shows each PAN Mapping value listed below is required unless otherwise noted:

Example Response

Below is an example response from the /team/{{TeamId}}/site/{{SiteId}}/mappings endpoint from a PPK-C site. In this example, there is one Building named Hudson, one Floor named 1, and multiple unique Units 100-103. Using any values outside of the ones returned in this response would result in an error.

Status: 200

Successful operation

{
    "Error": null,
    "Mappings": [
        {
            "Building": "Hudson",
            "Floor": "1",
            "Passphrase": null,
            "Ssid": "Wraeclast Heights",
            "Unit": "100",
            "Vlan": 401
        },
        {
            "Building": "Hudson",
            "Floor": "1",
            "Passphrase": null,
            "Ssid": "Wraeclast Heights",
            "Unit": "101",
            "Vlan": 402
        },
        {
            "Building": "Hudson",
            "Floor": "1",
            "Passphrase": null,
            "Ssid": "Wraeclast Heights",
            "Unit": "102",
            "Vlan": 403
        },
        {
            "Building": "Hudson",
            "Floor": "1",
            "Passphrase": null,
            "Ssid": "Wraeclast Heights",
            "Unit": "103",
            "Vlan": 404
        }
    ]
}

Date and Time

You can schedule residents to onboard immediately or in the future. To onboard residents immediately, set the ActivationDateUTC to today's date. When you schedule a resident's onboarding date in the future, ElevenOS will trigger the onboarding process specified in the ActivationDateUTC value. You can choose to set the DeactivationDateUTC value to a specific date or leave it empty, indicating no date of service deactivation. Also, note that only one resident can occupy a unit on any given date or date range. So, if you choose to enter no Access End date for a unit, no residents can be allocated to that unit until you terminate and purge the current resident.

We recommend using the following default activation and deactivate times. These values can be adjusted to your liking, however.

• Activation Time: 6:00 am local time
• Deactivation Time: 11:59:59 pm local time

All times must use Coordinated Universal Time (UTC) formatting. Use the following UTC format for all time values:

YYYY-MM-DDThh:mm:ss.000Z

Example UTC:

2021-11-09T05:19:18.490939+00:00

Dates of Service Interactions

There are some interactions to remember about the activation and deactivation dates of service for a resident:

• The Activation Date cannot be blank and must contain a value.
• The Activation Date must come before the Deactivation Date.
• If the Deactivation Date is empty, the resident's service will never deactivate unless you manually terminate or enter a Deactivation Date.
• If you add a resident with Activation and Deactivation Dates in the past, Site Manager adds the resident with the specified Activation Date and removes the Deactivation Date.
• If you change the Activation Date from the current date or earlier to a future date, the resident's status changes from Current/Pending to Scheduled.
• If you change the Deactivation Date of a current resident to a past date, then the Deactivation Date becomes empty, and the resident's status remains unchanged. Therefore, the only way to terminate a resident is with the endpoints to Terminate or Terminate and Purge.

Errors

In the event errors occur, the below sections explain some error scenarios and what to do when encountering them.

HTTP Status Codes

The Resident Management API returns HTTP status codes that indicate the call was successful or an error occurred.

Bulk Job Status Emails

The Resident Management API uses jobs for importing and performing bulk actions on multiple residents at once. The endpoints you use to import numerous residents and perform bulk actions on residents always send a job completion email to the account making API requests. This email details where and why any errors occur during a job.

Related Links

• Resident Management API - Quick Start Guide
• Resident Management API - Access and Permissions
• Resident Management API - Postman Collection