/v1/periods/{period_id}Authentication
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 PATCH \
--url 'https://api.staging.facily.ai/v1/periods/<PERIOD_ID>' \
--header "Authorization: Bearer $FACILY_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
"status": "open",
"reason": "string"
}'Parameters
period_idpath · stringrequiredFormat: uuid
Request body
application/json · Required
reasonstring | nullShow reason schema
string | nullVariant 1: string
stringVariant 2: null
nullstatusstringrequiredValues: "open", "soft_closed", "hard_closed"
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"
}
}application/json
dataPeriodCloseResponserequiredShow 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_idstringrequired400Validation 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