/v1/facilities/{facility_id}/access/rosterAuthentication
Bearer API key or Facily session, subject to permissions and facility scope.
Authentication and scopeRequest example
Replace bracketed path values with real IDs from your environment. The body, where shown, is generated from the schema and uses illustrative values.
curl --request GET \
--url 'https://api.staging.facily.ai/v1/facilities/<FACILITY_ID>/access/roster' \
--header "Authorization: Bearer $FACILY_API_KEY"Try a request
Staging · read-onlyExplore your organization with a read-only request to staging.
Parameters
facility_idpath · stringrequiredFormat: uuid
Responses
Expand a status to inspect its schema. Generated examples show structure and synthetic values.
200Successful Response
{
"data": [
{
"denied_reasons": [
"string"
],
"links": [
{
"holds": [
{
"code": "string",
"message": "string"
}
],
"provider": "string",
"tenant_warnings": [
{
"code": "string",
"message": "string"
}
],
"warnings": [
{
"code": "string",
"message": "string"
}
],
"denied_since": "2026-10-29T12:00:00Z",
"last_error": {
"code": "string",
"message": "string"
},
"last_pushed_at": "2026-10-29T12:00:00Z",
"link_status": "string",
"sync_status": "string",
"tenant_link_status": "string",
"vacated_at": "2026-10-29T12:00:00Z"
}
],
"occupied": false,
"open_items": [
{
"id": "00000000-0000-4000-8000-000000000001",
"kind": "string",
"provider": "string",
"worker_raised": false,
"resolutions": [
"string"
]
}
],
"unit_id": "00000000-0000-4000-8000-000000000001",
"unit_number": "string",
"lease_id": "00000000-0000-4000-8000-000000000001",
"move_in_date": "2026-10-29",
"tenant_id": "00000000-0000-4000-8000-000000000001",
"tenant_name": "string"
}
],
"meta": {
"request_id": "string"
},
"pagination": {
"has_more": false,
"limit": 0,
"cursor": "string",
"total_count": 0
},
"metrics": {
"cards": {},
"computed_at": "2026-10-29T12:00:00Z",
"is_stale": false,
"scope": "facility"
}
}application/json
dataAccessRosterRowResponse[]requiredShow data schema
denied_reasonsstring[]requiredEvery reason access is denied; empty when it is not.
Show denied_reasons schema
stringlease_idstring | nullThat lease.
Format: uuid
Show lease_id schema
string | nullThat lease.
Variant 1: string
stringVariant 2: null
nulllinksAccessRosterLinkResponse[]requiredThe unit's sync with each provider.
Show links schema
denied_sincestring | nullWhen the provider confirmed it holds the unit denied.
Format: date-time
Show denied_since schema
string | nullWhen the provider confirmed it holds the unit denied.
Variant 1: string
stringVariant 2: null
nullholdsAccessCodeResponse[]requiredWork deliberately held, and why.
Show holds schema
codestringrequiredThe code, for example tenant_unlinked or credential_rejected.
messagestringrequiredWhat the code means, in a sentence to show staff.
last_errorAccessCodeResponse | nullWhy the last attempt did not finish.
Show last_error schema
AccessCodeResponse | nullWhy the last attempt did not finish.
Variant 1: AccessCodeResponse
codestringrequiredThe code, for example tenant_unlinked or credential_rejected.
messagestringrequiredWhat the code means, in a sentence to show staff.
Variant 2: null
nulllast_pushed_atstring | nullWhen Facily last sent a change for the unit.
Format: date-time
Show last_pushed_at schema
string | nullWhen Facily last sent a change for the unit.
Variant 1: string
stringVariant 2: null
nulllink_statusstring | nulllinked, unlinked or excluded; null when the provider has no record of the unit.
Show link_status schema
string | nulllinked, unlinked or excluded; null when the provider has no record of the unit.
Variant 1: string
stringVariant 2: null
nullproviderstringrequiredThe provider.
sync_statusstring | nullsynced, pending, failed, blocked or held, once linked.
Show sync_status schema
string | nullsynced, pending, failed, blocked or held, once linked.
Variant 1: string
stringVariant 2: null
nulltenant_link_statusstring | nullThe tenant's link: new, linked or needs_review.
Show tenant_link_status schema
string | nullThe tenant's link: new, linked or needs_review.
Variant 1: string
stringVariant 2: null
nulltenant_warningsAccessCodeResponse[]requiredWarnings about the tenant's account.
Show tenant_warnings schema
codestringrequiredThe code, for example tenant_unlinked or credential_rejected.
messagestringrequiredWhat the code means, in a sentence to show staff.
vacated_atstring | nullOn a vacant unit: when the provider last confirmed it vacated the unit, while a phone may still hold keys for it; null otherwise. Such a unit is listed for that reason alone.
Format: date-time
Show vacated_at schema
string | nullOn a vacant unit: when the provider last confirmed it vacated the unit, while a phone may still hold keys for it; null otherwise. Such a unit is listed for that reason alone.
Variant 1: string
stringVariant 2: null
nullwarningsAccessCodeResponse[]requiredWarnings about the unit.
Show warnings schema
codestringrequiredThe code, for example tenant_unlinked or credential_rejected.
messagestringrequiredWhat the code means, in a sentence to show staff.
move_in_datestring | nullThe move-in date.
Format: date
Show move_in_date schema
string | nullThe move-in date.
Variant 1: string
stringVariant 2: null
nulloccupiedbooleanrequiredTrue while an active lease holds the unit.
open_itemsAccessOpenItemResponse[]requiredOpen findings about the unit or its tenant.
Show open_items schema
idstringrequiredThe finding.
Format: uuid
kindstringrequiredWhat kind of finding it is.
providerstringrequiredThe provider it concerns.
resolutionsstring[]What can be decided on this finding here: share_identity, separate_identity or vacate_confirmed. Empty when Facily staff decide it.
Show resolutions schema
stringworker_raisedbooleanrequiredTrue when the sync engine raised it after lock sync started; false for a finding from linking.
tenant_idstring | nullIts tenant.
Format: uuid
Show tenant_id schema
string | nullIts tenant.
Variant 1: string
stringVariant 2: null
nulltenant_namestring | nullTheir name; null without permission to read tenants.
Show tenant_name schema
string | nullTheir name; null without permission to read tenants.
Variant 1: string
stringVariant 2: null
nullunit_idstringrequiredThe unit.
Format: uuid
unit_numberstringrequiredIts number.
metaMetarequiredEnvelope metadata. Every response carries one.
Show meta schema
request_idstringrequiredmetricsEmbeddedMetrics | nullShow metrics schema
EmbeddedMetrics | nullVariant 1: EmbeddedMetrics
cardsobjectrequiredcomputed_atstring | nullrequiredFormat: date-time
Show computed_at schema
string | nullVariant 1: string
stringVariant 2: null
nullis_stalebooleanrequiredscopestringrequiredValues: "facility", "portfolio"
Variant 2: null
nullpaginationPaginationBlockrequiredPagination metadata for list responses.
Show pagination schema
cursorstring | nullShow cursor schema
string | nullVariant 1: string
stringVariant 2: null
nullhas_morebooleanrequiredlimitintegerrequiredtotal_countinteger | nullShow total_count schema
integer | nullVariant 1: integer
integerVariant 2: null
null400Validation error
{
"error": {
"code": "string",
"message": "string",
"details": {}
},
"meta": {
"request_id": "string"
}
}application/json
errorErrorBodyrequiredThe shape of error.* in an error response.
Show error schema
codestringrequireddetailsobject | nullShow details schema
object | nullVariant 1: object
objectVariant 2: null
nullmessagestringrequiredmetaMetarequiredEnvelope metadata. Every response carries one.
Show meta schema
request_idstringrequired401Unauthenticated
{
"error": {
"code": "string",
"message": "string",
"details": {}
},
"meta": {
"request_id": "string"
}
}application/json
errorErrorBodyrequiredThe shape of error.* in an error response.
Show error schema
codestringrequireddetailsobject | nullShow details schema
object | nullVariant 1: object
objectVariant 2: null
nullmessagestringrequiredmetaMetarequiredEnvelope metadata. Every response carries one.
Show meta schema
request_idstringrequired403Permission denied
{
"error": {
"code": "string",
"message": "string",
"details": {}
},
"meta": {
"request_id": "string"
}
}application/json
errorErrorBodyrequiredThe shape of error.* in an error response.
Show error schema
codestringrequireddetailsobject | nullShow details schema
object | nullVariant 1: object
objectVariant 2: null
nullmessagestringrequiredmetaMetarequiredEnvelope metadata. Every response carries one.
Show meta schema
request_idstringrequired404Not found
{
"error": {
"code": "string",
"message": "string",
"details": {}
},
"meta": {
"request_id": "string"
}
}application/json
errorErrorBodyrequiredThe shape of error.* in an error response.
Show error schema
codestringrequireddetailsobject | nullShow details schema
object | nullVariant 1: object
objectVariant 2: null
nullmessagestringrequiredmetaMetarequiredEnvelope metadata. Every response carries one.
Show meta schema
request_idstringrequired409Business logic error
{
"error": {
"code": "string",
"message": "string",
"details": {}
},
"meta": {
"request_id": "string"
}
}application/json
errorErrorBodyrequiredThe shape of error.* in an error response.
Show error schema
codestringrequireddetailsobject | nullShow details schema
object | nullVariant 1: object
objectVariant 2: null
nullmessagestringrequiredmetaMetarequiredEnvelope metadata. Every response carries one.
Show meta schema
request_idstringrequired503Temporary failure
{
"error": {
"code": "string",
"message": "string",
"details": {}
},
"meta": {
"request_id": "string"
}
}application/json
errorErrorBodyrequiredThe shape of error.* in an error response.
Show error schema
codestringrequireddetailsobject | nullShow details schema
object | nullVariant 1: object
objectVariant 2: null
nullmessagestringrequiredmetaMetarequiredEnvelope metadata. Every response carries one.
Show meta schema
request_idstringrequired