/v1/facilities/{facility_id}/periodsAuthentication
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>/periods' \
--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": [
{
"created_at": "2026-10-29T12:00:00Z",
"facility_id": "00000000-0000-4000-8000-000000000001",
"hard_closed_at": "2026-10-29T12:00:00Z",
"hard_closed_by": "00000000-0000-4000-8000-000000000001",
"id": "00000000-0000-4000-8000-000000000001",
"notes": "string",
"period_end": "2026-10-29",
"period_start": "2026-10-29",
"soft_closed_at": "2026-10-29T12:00:00Z",
"soft_closed_by": "00000000-0000-4000-8000-000000000001",
"status": "open",
"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
dataPeriodCloseResponse[]requiredShow data schema
created_atstringrequiredWhen the period record was created.
Format: date-time
facility_idstringrequiredThe facility the period belongs to.
Format: uuid
hard_closed_atstring | nullrequiredWhen the period was hard closed. After a hard close no further entries may be posted into it.
Format: date-time
Show hard_closed_at schema
string | nullWhen the period was hard closed. After a hard close no further entries may be posted into it.
Variant 1: string
stringVariant 2: null
nullhard_closed_bystring | nullrequiredThe user who hard closed the period.
Format: uuid
Show hard_closed_by schema
string | nullThe user who hard closed the period.
Variant 1: string
stringVariant 2: null
nullidstringrequiredUnique identifier for this accounting period.
Format: uuid
notesstring | nullrequiredNotes recorded during the close, such as an explanation of an adjustment.
Show notes schema
string | nullNotes recorded during the close, such as an explanation of an adjustment.
Variant 1: string
stringVariant 2: null
nullperiod_endstringrequiredLast business date in the period.
Format: date
period_startstringrequiredFirst business date in the period.
Format: date
soft_closed_atstring | nullrequiredWhen the period was soft closed. A soft close signals that routine work is finished while still allowing corrections.
Format: date-time
Show soft_closed_at schema
string | nullWhen the period was soft closed. A soft close signals that routine work is finished while still allowing corrections.
Variant 1: string
stringVariant 2: null
nullsoft_closed_bystring | nullrequiredThe user who soft closed the period.
Format: uuid
Show soft_closed_by schema
string | nullThe user who soft closed the period.
Variant 1: string
stringVariant 2: null
nullstatusstringrequiredWhether the period is open, soft closed, or hard closed.
Values: "open", "soft_closed", "hard_closed"
updated_atstringrequiredWhen the period record was last modified.
Format: date-time
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