Skip to content
FacilydevelopersDashboard
Build with Facily
DocsREST APIsList Access Roster
Search the full API reference Esc to close

List Access Roster

Access control · REST API reference

Get support
GET/v1/facilities/{facility_id}/access/roster
Every occupied unit, plus every vacant unit with something to sync, with its access state.

Authentication

Bearer API key or Facily session, subject to permissions and facility scope.

Authentication and scope

Request 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
curl --request GET \
  --url 'https://api.staging.facily.ai/v1/facilities/<FACILITY_ID>/access/roster' \
  --header "Authorization: Bearer $FACILY_API_KEY"
An example for building your request, not an executed call. Check required fields, allowed values, and environment configuration before sending.

Try a request

Staging · read-only

Explore your organization with a read-only request to staging.

Kept in this tab only. Sent directly to api.staging.facily.ai.

GET

Replace the {placeholders} in the path with your resource IDs.

Response
Your response will appear here.

Parameters

facility_idpath · stringrequired

Format: uuid

Responses

Expand a status to inspect its schema. Generated examples show structure and synthetic values.

200Successful Response
JSON · generated example
{
  "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[]required
Show data schema
denied_reasonsstring[]required

Every reason access is denied; empty when it is not.

Show denied_reasons schema
string
lease_idstring | null

That lease.

Format: uuid

Show lease_id schema
string | null

That lease.

Variant 1: string
string
Variant 2: null
null
linksAccessRosterLinkResponse[]required

The unit's sync with each provider.

Show links schema
denied_sincestring | null

When the provider confirmed it holds the unit denied.

Format: date-time

Show denied_since schema
string | null

When the provider confirmed it holds the unit denied.

Variant 1: string
string
Variant 2: null
null
holdsAccessCodeResponse[]required

Work deliberately held, and why.

Show holds schema
codestringrequired

The code, for example tenant_unlinked or credential_rejected.

messagestringrequired

What the code means, in a sentence to show staff.

last_errorAccessCodeResponse | null

Why the last attempt did not finish.

Show last_error schema
AccessCodeResponse | null

Why the last attempt did not finish.

Variant 1: AccessCodeResponse
codestringrequired

The code, for example tenant_unlinked or credential_rejected.

messagestringrequired

What the code means, in a sentence to show staff.

Variant 2: null
null
last_pushed_atstring | null

When Facily last sent a change for the unit.

Format: date-time

Show last_pushed_at schema
string | null

When Facily last sent a change for the unit.

Variant 1: string
string
Variant 2: null
null
link_statusstring | null

linked, unlinked or excluded; null when the provider has no record of the unit.

Show link_status schema
string | null

linked, unlinked or excluded; null when the provider has no record of the unit.

Variant 1: string
string
Variant 2: null
null
providerstringrequired

The provider.

sync_statusstring | null

synced, pending, failed, blocked or held, once linked.

Show sync_status schema
string | null

synced, pending, failed, blocked or held, once linked.

Variant 1: string
string
Variant 2: null
null
tenant_link_statusstring | null

The tenant's link: new, linked or needs_review.

Show tenant_link_status schema
string | null

The tenant's link: new, linked or needs_review.

Variant 1: string
string
Variant 2: null
null
tenant_warningsAccessCodeResponse[]required

Warnings about the tenant's account.

Show tenant_warnings schema
codestringrequired

The code, for example tenant_unlinked or credential_rejected.

messagestringrequired

What the code means, in a sentence to show staff.

vacated_atstring | null

On 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 | null

On 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
string
Variant 2: null
null
warningsAccessCodeResponse[]required

Warnings about the unit.

Show warnings schema
codestringrequired

The code, for example tenant_unlinked or credential_rejected.

messagestringrequired

What the code means, in a sentence to show staff.

move_in_datestring | null

The move-in date.

Format: date

Show move_in_date schema
string | null

The move-in date.

Variant 1: string
string
Variant 2: null
null
occupiedbooleanrequired

True while an active lease holds the unit.

open_itemsAccessOpenItemResponse[]required

Open findings about the unit or its tenant.

Show open_items schema
idstringrequired

The finding.

Format: uuid

kindstringrequired

What kind of finding it is.

providerstringrequired

The 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
string
worker_raisedbooleanrequired

True when the sync engine raised it after lock sync started; false for a finding from linking.

tenant_idstring | null

Its tenant.

Format: uuid

Show tenant_id schema
string | null

Its tenant.

Variant 1: string
string
Variant 2: null
null
tenant_namestring | null

Their name; null without permission to read tenants.

Show tenant_name schema
string | null

Their name; null without permission to read tenants.

Variant 1: string
string
Variant 2: null
null
unit_idstringrequired

The unit.

Format: uuid

unit_numberstringrequired

Its number.

metaMetarequired

Envelope metadata. Every response carries one.

Show meta schema
request_idstringrequired
metricsEmbeddedMetrics | null
Show metrics schema
EmbeddedMetrics | null
Variant 1: EmbeddedMetrics
cardsobjectrequired
computed_atstring | nullrequired

Format: date-time

Show computed_at schema
string | null
Variant 1: string
string
Variant 2: null
null
is_stalebooleanrequired
scopestringrequired

Values: "facility", "portfolio"

Variant 2: null
null
paginationPaginationBlockrequired

Pagination metadata for list responses.

Show pagination schema
cursorstring | null
Show cursor schema
string | null
Variant 1: string
string
Variant 2: null
null
has_morebooleanrequired
limitintegerrequired
total_countinteger | null
Show total_count schema
integer | null
Variant 1: integer
integer
Variant 2: null
null
400Validation error
JSON · generated example
{
  "error": {
    "code": "string",
    "message": "string",
    "details": {}
  },
  "meta": {
    "request_id": "string"
  }
}

application/json

errorErrorBodyrequired

The shape of error.* in an error response.

Show error schema
codestringrequired
detailsobject | null
Show details schema
object | null
Variant 1: object
object
Variant 2: null
null
messagestringrequired
metaMetarequired

Envelope metadata. Every response carries one.

Show meta schema
request_idstringrequired
401Unauthenticated
JSON · generated example
{
  "error": {
    "code": "string",
    "message": "string",
    "details": {}
  },
  "meta": {
    "request_id": "string"
  }
}

application/json

errorErrorBodyrequired

The shape of error.* in an error response.

Show error schema
codestringrequired
detailsobject | null
Show details schema
object | null
Variant 1: object
object
Variant 2: null
null
messagestringrequired
metaMetarequired

Envelope metadata. Every response carries one.

Show meta schema
request_idstringrequired
403Permission denied
JSON · generated example
{
  "error": {
    "code": "string",
    "message": "string",
    "details": {}
  },
  "meta": {
    "request_id": "string"
  }
}

application/json

errorErrorBodyrequired

The shape of error.* in an error response.

Show error schema
codestringrequired
detailsobject | null
Show details schema
object | null
Variant 1: object
object
Variant 2: null
null
messagestringrequired
metaMetarequired

Envelope metadata. Every response carries one.

Show meta schema
request_idstringrequired
404Not found
JSON · generated example
{
  "error": {
    "code": "string",
    "message": "string",
    "details": {}
  },
  "meta": {
    "request_id": "string"
  }
}

application/json

errorErrorBodyrequired

The shape of error.* in an error response.

Show error schema
codestringrequired
detailsobject | null
Show details schema
object | null
Variant 1: object
object
Variant 2: null
null
messagestringrequired
metaMetarequired

Envelope metadata. Every response carries one.

Show meta schema
request_idstringrequired
409Business logic error
JSON · generated example
{
  "error": {
    "code": "string",
    "message": "string",
    "details": {}
  },
  "meta": {
    "request_id": "string"
  }
}

application/json

errorErrorBodyrequired

The shape of error.* in an error response.

Show error schema
codestringrequired
detailsobject | null
Show details schema
object | null
Variant 1: object
object
Variant 2: null
null
messagestringrequired
metaMetarequired

Envelope metadata. Every response carries one.

Show meta schema
request_idstringrequired
503Temporary failure
JSON · generated example
{
  "error": {
    "code": "string",
    "message": "string",
    "details": {}
  },
  "meta": {
    "request_id": "string"
  }
}

application/json

errorErrorBodyrequired

The shape of error.* in an error response.

Show error schema
codestringrequired
detailsobject | null
Show details schema
object | null
Variant 1: object
object
Variant 2: null
null
messagestringrequired
metaMetarequired

Envelope metadata. Every response carries one.

Show meta schema
request_idstringrequired
Build something that works beautifully.

Facily API · Contract v1.200 · Reviewed October 29, 2026

List Access Roster | Facily Developers