/v1/facilities/{facility_id}/tenantsAuthentication
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>/tenants' \
--header "Authorization: Bearer $FACILY_API_KEY"Try a request
Staging · read-onlyExplore your organization with a read-only request to staging.
Parameters
facility_idpath · string | stringrequiredFormat: uuid
cursorquery · string | nulllimitquery · integerDefault: 50 · Minimum: 1 · Maximum: 200
pagequery · integer | null1-based page number, for a numbered pager. Mutually exclusive with `cursor`.
Minimum: 1
sortquery · string | nullValues: "last_name", "created_at", "total_balance", "tenant_number"
orderquery · stringDefault: "asc" · Values: "asc", "desc"
searchquery · string | nullstatusquery · string[] | nullhas_balancequery · boolean | nullis_businessquery · boolean | nullmetricsquery · booleanEmbed the cached KPI metrics block in the response.
Default: false
Responses
Expand a status to inspect its schema. Generated examples show structure and synthetic values.
200Successful Response
{
"data": [
{
"communication_preferences": {
"email_suppressed": false,
"invoice_delivery": "string",
"marketing_sms_opt_in_evidence_id": "00000000-0000-4000-8000-000000000001",
"marketing_sms_opt_in_recorded_by": "00000000-0000-4000-8000-000000000001",
"marketing_sms_opt_in_source": "string",
"marketing_sms_opted_in_at": "2026-10-29T12:00:00Z",
"marketing_sms_revoked_at": "2026-10-29T12:00:00Z",
"preferred_channels": [
"string"
],
"sms_opt_in_evidence_id": "00000000-0000-4000-8000-000000000001",
"sms_opt_in_recorded_by": "00000000-0000-4000-8000-000000000001",
"sms_opt_in_source": "storedge_import",
"sms_opted_in_at": "2026-10-29T12:00:00Z"
},
"created_at": "2026-10-29T12:00:00Z",
"delinquency_exempt": false,
"facility_id": "00000000-0000-4000-8000-000000000001",
"first_name": "string",
"id": "00000000-0000-4000-8000-000000000001",
"is_business": false,
"last_name": "string",
"leases": [
{
"id": "00000000-0000-4000-8000-000000000001",
"lease_number": "string",
"next_billing_date": "2026-10-29",
"rate": "<VALUE_MATCHING_PATTERN>",
"start_date": "2026-10-29",
"status": "string",
"tenant_id": "00000000-0000-4000-8000-000000000001",
"tenant_name": "string",
"unit_number": "string",
"insurance_plan": {
"coverage_amount": "<VALUE_MATCHING_PATTERN>",
"id": "00000000-0000-4000-8000-000000000001",
"monthly_premium": "<VALUE_MATCHING_PATTERN>",
"name": "string"
}
}
],
"portal_enabled": false,
"status": "string",
"system_tags": [
"string"
],
"tags": [
{
"facility_id": "00000000-0000-4000-8000-000000000001",
"id": "00000000-0000-4000-8000-000000000001",
"name": "string",
"color": "string"
}
],
"tax_exempt": false,
"tenant_number": "string",
"total_balance": "<VALUE_MATCHING_PATTERN>",
"updated_at": "2026-10-29T12:00:00Z"
}
],
"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
dataTenantResponse[]requiredShow data schema
communication_preferencesTenantCommunicationPreferencesrequiredHow one tenant has agreed to be contacted (design 6.4).
Show communication_preferences schema
email_suppressedbooleanDefault: false
invoice_deliverystring | nullShow invoice_delivery schema
string | nullVariant 1: string
stringVariant 2: null
nullmarketing_sms_opt_in_evidence_idstring | nullFormat: uuid
Show marketing_sms_opt_in_evidence_id schema
string | nullVariant 1: string
stringVariant 2: null
nullmarketing_sms_opt_in_recorded_bystring | nullFormat: uuid
Show marketing_sms_opt_in_recorded_by schema
string | nullVariant 1: string
stringVariant 2: null
nullmarketing_sms_opt_in_sourcestring | nullShow marketing_sms_opt_in_source schema
string | nullVariant 1: string
stringVariant 2: null
nullmarketing_sms_opted_in_atstring | nullFormat: date-time
Show marketing_sms_opted_in_at schema
string | nullVariant 1: string
stringVariant 2: null
nullmarketing_sms_revoked_atstring | nullFormat: date-time
Show marketing_sms_revoked_at schema
string | nullVariant 1: string
stringVariant 2: null
nullpreferred_channelsstring[]Show preferred_channels schema
stringsms_opt_in_evidence_idstring | nullFormat: uuid
Show sms_opt_in_evidence_id schema
string | nullVariant 1: string
stringVariant 2: null
nullsms_opt_in_recorded_bystring | nullFormat: uuid
Show sms_opt_in_recorded_by schema
string | nullVariant 1: string
stringVariant 2: null
nullsms_opt_in_sourcestring | nullValues: "storedge_import", "staff_in_person", "staff_phone", "signed_document", "inbound_sms_start", "web_form", "partner"
Show sms_opt_in_source schema
string | nullVariant 1: string
stringValues: "storedge_import", "staff_in_person", "staff_phone", "signed_document", "inbound_sms_start", "web_form", "partner"
Variant 2: null
nullsms_opted_in_atstring | nullFormat: date-time
Show sms_opted_in_at schema
string | nullVariant 1: string
stringVariant 2: null
nullsms_opted_outbooleanDefault: false
company_namestring | nullLegal business name. Present only when is_business is true.
Show company_name schema
string | nullLegal business name. Present only when is_business is true.
Variant 1: string
stringVariant 2: null
nullcreated_atstringrequiredWhen the tenant record was created.
Format: date-time
delinquency_exemptbooleanrequiredTrue when staff have held this tenant out of the delinquency engine: no fees, no escalation, no notices.
emailstring | nullPrimary email address, used for billing and notices.
Show email schema
string | nullPrimary email address, used for billing and notices.
Variant 1: string
stringVariant 2: null
nullfacility_idstringrequiredThe facility this tenant belongs to. A person renting at two sites is two tenant records.
Format: uuid
first_namestringrequiredGiven name. For a business tenant this is the contact person.
idstringrequiredUnique identifier for this tenant.
Format: uuid
is_businessbooleanrequiredTrue when the tenant is an organization rather than an individual.
last_namestringrequiredFamily name. For a business tenant this is the contact person.
leasesLeaseCompactResponse[]requiredThe tenant's leases, so a listing can show what they rent without a second call.
Show leases schema
idstringrequiredUnique identifier for the lease.
Format: uuid
insurance_planInsurancePlanCompactResponse | nullThe protection plan this lease is enrolled on, or null when the tenant carries their own policy or none.
Show insurance_plan schema
InsurancePlanCompactResponse | nullThe protection plan this lease is enrolled on, or null when the tenant carries their own policy or none.
Variant 1: InsurancePlanCompactResponse
coverage_amountstringrequiredPattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
idstringrequiredFormat: uuid
monthly_premiumstringrequiredPattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
namestringrequiredVariant 2: null
nulllease_numberstringrequiredOperator-facing lease reference, unique within the facility.
next_billing_datestringrequiredBusiness date rent is next charged.
Format: date
ratestringrequiredCurrent monthly rent charged under this lease.
Pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
start_datestringrequiredBusiness date the lease began.
Format: date
statusstringrequiredLifecycle state of the lease.
tenant_idstringrequiredThe tenant renting under this lease.
Format: uuid
tenant_namestringrequiredThe tenant's display name, denormalized so a listing needs no second call.
unit_numberstringrequiredLabel of the unit this lease occupies.
middle_initialstring | nullMiddle initial, where recorded.
Show middle_initial schema
string | nullMiddle initial, where recorded.
Variant 1: string
stringVariant 2: null
nullphonestring | nullPrimary telephone number.
Show phone schema
string | nullPrimary telephone number.
Variant 1: string
stringVariant 2: null
nullportal_enabledbooleanrequiredWhether the tenant can sign in to the self-service portal.
statusstringrequiredLifecycle state of the tenant relationship, for example active, former, or lead.
system_tagsstring[]requiredLabels the platform derives automatically, such as delinquency state. Not operator-editable.
Show system_tags schema
stringtagsTagResponse[]requiredOperator-defined labels applied manually.
Show tags schema
colorstring | nullColour used to render the tag, as a hex code.
Show color schema
string | nullColour used to render the tag, as a hex code.
Variant 1: string
stringVariant 2: null
nullfacility_idstringrequiredThe facility this tag is defined for.
Format: uuid
idstringrequiredUnique identifier for this tag.
Format: uuid
namestringrequiredDisplay label of the tag.
tax_exemptbooleanrequiredTrue when the tenant is exempt from sales tax on rent.
tax_exempt_idstring | nullThe exemption certificate number substantiating tax_exempt.
Show tax_exempt_id schema
string | nullThe exemption certificate number substantiating tax_exempt.
Variant 1: string
stringVariant 2: null
nulltenant_numberstringrequiredOperator-facing tenant reference, unique within the facility.
total_balancestringrequiredSum owed across all of this tenant's leases. Positive means money is owed; negative is a credit.
Pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
updated_atstringrequiredWhen the tenant record was last modified.
Format: date-time
vehicle_descriptionstring | nullDescription of a stored vehicle, where the facility rents parking.
Show vehicle_description schema
string | nullDescription of a stored vehicle, where the facility rents parking.
Variant 1: string
stringVariant 2: null
nullvehicle_license_platestring | nullRegistration plate of a stored vehicle.
Show vehicle_license_plate schema
string | nullRegistration plate of a stored vehicle.
Variant 1: string
stringVariant 2: null
nullvehicle_license_statestring | nullIssuing state or province of the vehicle registration.
Show vehicle_license_state schema
string | nullIssuing state or province of the vehicle registration.
Variant 1: string
stringVariant 2: null
nullmetaMetarequiredEnvelope 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