/v1/facilities/{facility_id}/unit-groupsAuthentication
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>/unit-groups' \
--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: "name", "created_at"
orderquery · stringDefault: "asc" · Values: "asc", "desc"
Responses
Expand a status to inspect its schema. Generated examples show structure and synthetic values.
200Successful Response
{
"data": [
{
"created_at": "2026-10-29T12:00:00Z",
"facility_id": "00000000-0000-4000-8000-000000000001",
"id": "00000000-0000-4000-8000-000000000001",
"name": "string",
"updated_at": "2026-10-29T12:00:00Z",
"active_rules": [
{
"id": "00000000-0000-4000-8000-000000000001",
"name": "string"
}
],
"code": "string",
"description": "string",
"effective_standard_rate": "<VALUE_MATCHING_PATTERN>",
"effective_web_rate": "<VALUE_MATCHING_PATTERN>",
"feature_ids": [
"00000000-0000-4000-8000-000000000001"
],
"feature_names": [
"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
dataapi__facilities__schemas__UnitGroupResponse[]requiredShow data schema
active_rulesActiveRuleRef[]Pricing rules applying to this group now.
Show active_rules schema
idstringrequiredFormat: uuid
namestringrequiredcodestring | nullShort operator-assigned code for the group.
Show code schema
string | nullShort operator-assigned code for the group.
Variant 1: string
stringVariant 2: null
nullcreated_atstringrequiredWhen the group was created.
Format: date-time
descriptionstring | nullLonger description of what the group covers.
Show description schema
string | nullLonger description of what the group covers.
Variant 1: string
stringVariant 2: null
nulleffective_standard_ratestring | nullThe street rate a unit of this group quotes when it has no rate of its own.
Pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
Show effective_standard_rate schema
string | nullThe street rate a unit of this group quotes when it has no rate of its own.
Variant 1: string
stringVariant 2: null
nulleffective_web_ratestring | nullThe online rate a unit of this group quotes when it has no rate of its own.
Pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
Show effective_web_rate schema
string | nullThe online rate a unit of this group quotes when it has no rate of its own.
Variant 1: string
stringVariant 2: null
nullfacility_idstringrequiredThe facility this group belongs to.
Format: uuid
feature_idsstring[]The group's characteristics.
Show feature_ids schema
stringfeature_namesstring[]Names of the group's characteristics.
Show feature_names schema
stringfloorinteger | nullFloor the group's units are on, when it has one.
Show floor schema
integer | nullFloor the group's units are on, when it has one.
Variant 1: integer
integerVariant 2: null
nullidstringrequiredUnique identifier for this unit group.
Format: uuid
managedbooleanTrue when pricing rules set the effective street rate.
Default: false
managed_ratestring | nullStreet rate set by pricing rules; null when no rule applies.
Pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
Show managed_rate schema
string | nullStreet rate set by pricing rules; null when no rule applies.
Variant 1: string
stringVariant 2: null
nullmanaged_web_discountstring | nullPercentage points pricing rules add to the online discount; null when none applies.
Pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
Show managed_web_discount schema
string | nullPercentage points pricing rules add to the online discount; null when none applies.
Variant 1: string
stringVariant 2: null
nullmax_ratestring | nullCeiling: no pricing rule moves the street rate above it.
Pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
Show max_rate schema
string | nullCeiling: no pricing rule moves the street rate above it.
Variant 1: string
stringVariant 2: null
nullmin_ratestring | nullFloor: no pricing rule moves the street rate below it.
Pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
Show min_rate schema
string | nullFloor: no pricing rule moves the street rate below it.
Variant 1: string
stringVariant 2: null
nullnamestringrequiredDisplay name of the group.
occupancyUnitGroupOccupancy | nullCounts of units in this group by occupancy state.
Show occupancy schema
UnitGroupOccupancy | nullCounts of units in this group by occupancy state.
Variant 1: UnitGroupOccupancy
availableintegerUnits available to rent now.
Default: 0
occupiedintegerUnits currently rented.
Default: 0
reservedintegerUnits held under a reservation.
Default: 0
rule_pctstring | nullThe occupancy pricing rules use, as a percentage: occupied or overlocked units among rentable units not in maintenance. Null when the group has no such units.
Pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
Show rule_pct schema
string | nullThe occupancy pricing rules use, as a percentage: occupied or overlocked units among rentable units not in maintenance. Null when the group has no such units.
Variant 1: string
Variant 2: null
totalintegerTotal units in the group.
Default: 0
Variant 2: null
nulloverridden_unit_countintegerUnits in this group that carry a rate of their own.
Default: 0
rates_changed_atstring | nullWhen the group's effective street or online rate last changed.
Format: date-time
Show rates_changed_at schema
string | nullWhen the group's effective street or online rate last changed.
Variant 1: string
stringVariant 2: null
nullsizeGroupSizeResponse | nullThe footprint every dimensioned unit of the group shares; null when they differ.
Show size schema
GroupSizeResponse | nullThe footprint every dimensioned unit of the group shares; null when they differ.
Variant 1: GroupSizeResponse
depth_feetstringrequiredPattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
width_feetstringrequiredPattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
Variant 2: null
nullstandard_ratestring | nullBase street rate the operator set; units with no rate of their own start from it.
Pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
Show standard_rate schema
string | nullBase street rate the operator set; units with no rate of their own start from it.
Variant 1: string
stringVariant 2: null
nullupdated_atstringrequiredWhen the group was last modified.
Format: date-time
web_managedbooleanTrue when a pricing rule adjusts the effective online rate.
Default: false
web_ratestring | nullBase online rate the operator set, optional.
Pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
Show web_rate schema
string | nullBase online rate the operator set, optional.
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