API V2 Route: Residencies

Last updated: October 5, 2026

General Details:

Endpoint	`/api/v2/residencies`and `/api/v2/residencies/<id>`
Headers	`Authorization: <JWT>`
HTTP Methods	`GET`
Request Body Format	`N/A`
Response Body Format	`JSON`
Required Scopes	`RESIDENCIES_GET`

Supported Request Filters:

These filters should be query parts in the URL string and follow the standard pattern of <baseUrl>?<key>=<filter>&...

Field Name	Filter Type	Notes
`status`	string	See table for acceptable values
`dateAssigned`	date or Date Filter	An ISO date string or a complex Date Filter can be utilized
`dateStart`	date or Date Filter	An ISO date string or a complex Date Filter can be utilized
`dateEnd`	date or Date Filter	An ISO date string or a complex Date Filter can be utilized
`dateMovedIn`	date or Date Filter	An ISO date string or a complex Date Filter can be utilized
`dateMovedOut`	date or Date Filter	An ISO date string or a complex Date Filter can be utilized
`lastDateUpdate`	date or Date Filter	An ISO date string or a complex Date Filter can be utilized
`cycle`	number	Numerical id of target cycle

Supported Residency Statuses:

`ASSIGNED`	The residency has been assigned through selection or an admin
`CANCELLED`	The residency has been cancelled by an admin
`TRANSFERRED`	This residency's student has transferred to another location
`INCOMING`	Residency start date has passed, but no move-in has been recorded
`CURRENT`	Student has a move-in date, and is currently residing in this space
`MOVED_OUT`	Student has been marked as having moved out
`OVERSTAY`	Student has not moved-out, but the end date of the Residency has passed

API Response:

Field Name	Data Type	Notes
id	string	Globally unique identifier
inventory	object	Object representing the full inventory path of the residency, consisting of BuildingThin, SuiteThin, RoomThin, BedThin
dateAssigned	date string	ISO date string
dateStart	date string	ISO date string
dateEnd	date string	ISO date string
dateMovedIn	date string	ISO date string
dateMovedOut	date string	ISO date string
status	string	Current status of the Residency
profile	ProfileThin	Student for which the residency is tied to
cycle	CycleThin	Cycle in which the residency is for

Example Response:

{
    "entities": [
        {
            "id": "86",
            "inventory": {
                "building": {
                    "id": "7",
                    "name": "Red Tower",
                    "externalCode":"RT01" },
                "suite": {
                    "id": "56",
                    "name": "Suite 2",
                    "externalCode":"" },
                "room": {
                    "id": "395",
                    "name": "201",
                    "externalCode":"201" },
                "bed": {
                    "id": "7435",
                    "name": "B",
                    "externalCode":"" }
            },
            "dateAssigned": "2025-08-30T18:11:23.357Z",
            "dateStart": "2025-09-30T08:00:00.000Z",
            "dateEnd": "2025-12-10T23:59:59.999Z",
            "dateMovedIn": "2025-09-28T08:45:00.559Z",
            "dateMovedOut": "2025-12-08T23:59:59.999Z",
            "status","MOVED_OUT"
            "profile": {
                "id": "4697",
                "name": "Braden Grute",
                "sisId": "B0011879"
            },
            "cycle": {
                "id": "9",
                "name": "Fall Semester Returning",
                "externalTermCode": "FA2026"
            },
        }
    ],
    "metaData": {
        "agentId": "ab5f95b2-303a-403b-85fd-ab1d0cd8093c",
        "rateLimits": {
            "tenant": {
                "limit": 50,
                "remaining": 49,
                "reset": 1759520782000
            },
            "agent": {
                "limit": 10,
                "remaining": 9,
                "reset": 1759520783000
            }
        },
        "pagination": {
            "offset": 0,
            "limit": 1000
        }
    }
}