/v1/facilities/{facility_id}/tasksAuthentication
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 POST \
--url 'https://api.staging.facily.ai/v1/facilities/<FACILITY_ID>/tasks' \
--header "Authorization: Bearer $FACILY_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
"title": "string",
"assigned_to": "00000000-0000-4000-8000-000000000001",
"assignment": {
"mode": "direct",
"user_id": "00000000-0000-4000-8000-000000000001"
},
"category": "collection",
"description": "string",
"due_date": "2026-10-29",
"lead_id": "00000000-0000-4000-8000-000000000001",
"lease_id": "00000000-0000-4000-8000-000000000001",
"priority": "normal",
"requires_photo_proof": false,
"task_type": "auction_prep",
"tenant_id": "00000000-0000-4000-8000-000000000001"
}'Parameters
facility_idpath · stringrequiredFormat: uuid
Request body
application/json · Required
assigned_tostring | nullThe staff user who owns it; null for unassigned.
Format: uuid
Show assigned_to schema
string | nullThe staff user who owns it; null for unassigned.
Variant 1: string
stringVariant 2: null
nullassignmentTaskAssignmentRequest | nullWho does the work, in the same form the assign route takes. Send this or assigned_to, not both. Omitted, the task is filed unassigned.
Show assignment schema
TaskAssignmentRequest | nullWho does the work, in the same form the assign route takes. Send this or assigned_to, not both. Omitted, the task is filed unassigned.
Variant 1: TaskAssignmentRequest
modestringrequireddirect assigns user_id; auto gives the task to the next person in its facility's rotation, and it waits when there is no one; unassigned clears the assignee.
Values: "direct", "auto", "unassigned"
user_idstring | nullThe person to assign, with mode direct only.
Format: uuid
Show user_id schema
string | nullThe person to assign, with mode direct only.
Variant 1: string
stringVariant 2: null
nullVariant 2: null
nullcategorystring | nullWhat kind of work this is. Optional when `task_type` is sent.
Values: "collection", "follow_up", "general", "inspection", "maintenance", "move_in", "move_out", "review"
Show category schema
string | nullWhat kind of work this is. Optional when `task_type` is sent.
Variant 1: string
stringValues: "collection", "follow_up", "general", "inspection", "maintenance", "move_in", "move_out", "review"
Variant 2: null
nulldescriptionstring | nullLonger detail for whoever picks the task up. At most 2,000 characters. Empty or only spaces is stored as null.
Max length: 2000
Show description schema
string | nullLonger detail for whoever picks the task up. At most 2,000 characters. Empty or only spaces is stored as null.
Variant 1: string
stringVariant 2: null
nulldue_datestring | nullBusiness date the task is due; null for no deadline, except on a task that follows up a lead, where it becomes the facility's next local day.
Format: date
Show due_date schema
string | nullBusiness date the task is due; null for no deadline, except on a task that follows up a lead, where it becomes the facility's next local day.
Variant 1: string
stringVariant 2: null
nulllead_idstring | nullThe lead the task follows up, where it follows one up.
Format: uuid
Show lead_id schema
string | nullThe lead the task follows up, where it follows one up.
Variant 1: string
stringVariant 2: null
nulllease_idstring | nullThe lease the task concerns, where it concerns one.
Format: uuid
Show lease_id schema
string | nullThe lease the task concerns, where it concerns one.
Variant 1: string
stringVariant 2: null
nullprioritystringHow urgent the task is.
Default: "normal" · Values: "low", "normal", "high", "urgent"
requires_photo_proofboolean | nullWhether completing the task needs proof photos. Omitted, the facility's default for the task's type applies. A value that differs from that default needs the task.manage permission, and turning a default of true off needs a person.
Show requires_photo_proof schema
boolean | nullWhether completing the task needs proof photos. Omitted, the facility's default for the task's type applies. A value that differs from that default needs the task.manage permission, and turning a default of true off needs a person.
Variant 1: boolean
booleanVariant 2: null
nulltask_typestring | nullThe board type of the work. Send this or `category`; both only when they agree.
Values: "auction_prep", "clean_unit", "collection", "follow_up", "inspection", "lock_check", "maintenance", "other", "overlock", "remove_overlock", "review", "unit_prep", "walkthrough", "work_order"
Show task_type schema
string | nullThe board type of the work. Send this or `category`; both only when they agree.
Variant 1: string
stringValues: "auction_prep", "clean_unit", "collection", "follow_up", "inspection", "lock_check", "maintenance", "other", "overlock", "remove_overlock", "review", "unit_prep", "walkthrough", "work_order"
Variant 2: null
nulltenant_idstring | nullThe tenant the task concerns, where it concerns one.
Format: uuid
Show tenant_id schema
string | nullThe tenant the task concerns, where it concerns one.
Variant 1: string
stringVariant 2: null
nulltitlestringrequiredWhat needs doing. Trimmed and required.
Min length: 1 · Max length: 255
unit_idstring | nullThe unit the task concerns, where it concerns one.
Format: uuid
Show unit_id schema
string | nullThe unit the task concerns, where it concerns one.
Variant 1: string
stringVariant 2: null
nullunit_numberstring | nullThe unit's number at this facility, in place of `unit_id`. Matched exactly, case and all. Empty or only spaces means no unit.
Max length: 20
Show unit_number schema
string | nullThe unit's number at this facility, in place of `unit_id`. Matched exactly, case and all. Empty or only spaces means no unit.
Variant 1: string
stringVariant 2: null
nullResponses
Expand a status to inspect its schema. Generated examples show structure and synthetic values.
201Successful Response
{
"data": {
"assignment_mode": "string",
"awaiting_proof": false,
"capabilities": {
"add_photo": false,
"assign": false,
"assign_auto": false,
"cancel": false,
"claim": false,
"comment": false,
"complete": false,
"delete": false,
"edit": false,
"edit_due_date": false,
"edit_extension": false,
"edit_proof_flag": false,
"edit_title": false,
"follow_up": false,
"hold_unit": false,
"move_to_open": false,
"override_proof": false,
"pin": false,
"record_cost": false,
"record_finding": false,
"release_hold": false,
"reopen": false,
"set_substatus": false,
"start": false,
"verify": false
},
"category": "string",
"created_at": "2026-10-29T12:00:00Z",
"created_by": "00000000-0000-4000-8000-000000000001",
"creator": {
"display_name": "string",
"id": "00000000-0000-4000-8000-000000000001"
},
"days_overdue": 0,
"due_state": "none",
"engine_case_closed": false,
"engine_managed": false,
"facility_id": "00000000-0000-4000-8000-000000000001",
"facility_name": "string",
"has_pinned_note": false,
"has_proof_override": false,
"id": "00000000-0000-4000-8000-000000000001",
"is_escalated": false,
"kind": "string",
"priority": "string",
"proof_photo_count": 0,
"reopen_count": 0,
"requires_photo_proof": false,
"source": "string",
"status": "string",
"task_type": "string",
"title": "string",
"updated_at": "2026-10-29T12:00:00Z"
},
"meta": {
"request_id": "string"
}
}application/json
dataTaskCreatedResponserequiredWhat a create answers: the new row, and a hint when the work may already be filed.
Show data schema
assigned_tostring | nullThe staff user who owns it; null for unassigned.
Format: uuid
Show assigned_to schema
string | nullThe staff user who owns it; null for unassigned.
Variant 1: string
stringVariant 2: null
nullassigneePersonResponse | nullWho the task is assigned to; null when nobody is.
Show assignee schema
PersonResponse | nullWho the task is assigned to; null when nobody is.
Variant 1: PersonResponse
display_namestringrequiredThe name to show for the user.
idstringrequiredThe user's id.
Format: uuid
Variant 2: null
nullassignment_modestringrequireddirect, or auto. Auto means the rotation owns the task: either it gave the task to its assignee, or the task is waiting for the rotation with no assignee. Claiming it, assigning it to a person, unassigning it and changing the assignee all store direct.
awaiting_proofbooleanrequiredTrue when the task is open, needs proof photos, and holds fewer than its facility asks for.
capabilitiesTaskCapabilitiesResponserequiredWhat the caller may do with a task now, one flag per action.
Show capabilities schema
add_photobooleanrequiredTrue when the caller may add a photo to it now.
assignbooleanrequiredTrue when the caller may assign it now.
assign_autobooleanrequiredTrue when the caller may give it to the rotation now.
cancelbooleanrequiredTrue when the caller may cancel it now.
claimbooleanrequiredTrue when the caller may claim it now.
commentbooleanrequiredTrue when the caller may comment on it now.
completebooleanrequiredTrue when the caller may complete it now.
deletebooleanrequiredTrue when the caller may delete it now.
editbooleanrequiredTrue when the caller may edit it now.
edit_due_datebooleanrequiredTrue when the caller may change its due date now.
edit_extensionbooleanrequiredTrue when the caller may edit the work order's own fields, or an inspection's totals and summary note, now. False on a plain task.
edit_proof_flagbooleanrequiredTrue when the caller may change whether it needs proof photos now.
edit_titlebooleanrequiredTrue when the caller may change its title now.
follow_upbooleanrequiredTrue when the caller may open follow-up work from one of the inspection's findings now, which a completed inspection still allows. False on any other kind.
hold_unitbooleanrequiredTrue when the caller may take the work order's unit out of service now. False on any other kind.
move_to_openbooleanrequiredTrue when the caller may move it back to open now.
override_proofbooleanrequiredTrue when the caller may complete it without its proof photos, giving a reason now.
pinbooleanrequiredTrue when the caller may write its pinned note now.
record_costbooleanrequiredTrue when the caller may record the work order's actual cost and resolution note now, which a completed work order still accepts. False on any other kind.
record_findingbooleanrequiredTrue when the caller may record or remove the inspection's findings now. False on any other kind.
release_holdbooleanrequiredTrue when the caller may release the unit the work order holds now, in any status. False on any other kind.
reopenbooleanrequiredTrue when the caller may reopen it now.
set_substatusbooleanrequiredTrue when the caller may move the work order to waiting on vendor, blocked or in progress now. False on any other kind.
startbooleanrequiredTrue when the caller may start the task now.
verifybooleanrequiredTrue when the caller may verify the completed work order now. False on any other kind.
case_closed_onstring | nullFor a delinquency engine task whose case has closed, the date it closed at the task's facility; null otherwise.
Format: date
Show case_closed_on schema
string | nullFor a delinquency engine task whose case has closed, the date it closed at the task's facility; null otherwise.
Variant 1: string
stringVariant 2: null
nullcase_lease_idstring | nullFor a delinquency engine task, the lease of its delinquency case; null otherwise.
Format: uuid
Show case_lease_id schema
string | nullFor a delinquency engine task, the lease of its delinquency case; null otherwise.
Variant 1: string
stringVariant 2: null
nullcategorystringrequiredWhat kind of work this is, including the engine-only categories.
completed_atstring | nullWhen it was completed; null while it is open.
Format: date-time
Show completed_at schema
string | nullWhen it was completed; null while it is open.
Variant 1: string
stringVariant 2: null
nullcompleted_bystring | nullWho completed it.
Format: uuid
Show completed_by schema
string | nullWho completed it.
Variant 1: string
stringVariant 2: null
nullcreated_atstringrequiredWhen the task was filed.
Format: date-time
created_bystringrequiredThe actor the row is attributed to.
Format: uuid
creatorPersonResponserequiredA user, as a task or a thread entry names one.
Show creator schema
display_namestringrequiredThe name to show for the user.
idstringrequiredThe user's id.
Format: uuid
days_overdueintegerrequiredDays past the due date at the task's facility; 0 unless due_state is overdue.
days_until_dueinteger | null0 when due today, the days ahead when upcoming, null otherwise.
Show days_until_due schema
integer | null0 when due today, the days ahead when upcoming, null otherwise.
Variant 1: integer
integerVariant 2: null
nulldescriptionstring | nullLonger detail, where there is any.
Show description schema
string | nullLonger detail, where there is any.
Variant 1: string
stringVariant 2: null
nulldue_datestring | nullBusiness date the task is due.
Format: date
Show due_date schema
string | nullBusiness date the task is due.
Variant 1: string
stringVariant 2: null
nulldue_statestringrequiredWhere the task stands against its due date at its facility: overdue, today or upcoming, or none when it has no due date, is closed, or belongs to a delinquency case that has closed.
Values: "none", "upcoming", "today", "overdue"
engine_case_closedbooleanrequiredTrue for an open delinquency engine task whose case has closed, other than a lock removal. Such a task counts only as open.
engine_managedbooleanrequiredTrue for a task the delinquency engine filed.
extensionTaskExtensionResponse | nullA work order's or an inspection's number and display status; null on a plain task.
Show extension schema
TaskExtensionResponse | nullA work order's or an inspection's number and display status; null on a plain task.
Variant 1: TaskExtensionResponse
display_statusstringrequiredThe status the kind's own list shows.
numberstringrequiredThe number a person reads, such as WO-0042 or INS-0007.
Variant 2: null
nullfacility_idstringrequiredThe facility the task belongs to.
Format: uuid
facility_namestringrequiredThe name of the task's facility.
has_pinned_notebooleanrequiredTrue when the task has a pinned note. The note is on the task's detail.
has_proof_overridebooleanrequiredTrue when the task was completed without its proof photos, with a recorded reason.
idstringrequiredUnique identifier for this task.
Format: uuid
is_escalatedbooleanrequiredTrue when the task is overdue by more than its facility's escalation threshold and escalation is on.
kindstringrequiredtask, work_order or inspection. It never changes.
leadTaskLeadResponse | nullThe lead the task follows up; null when it follows none up.
Show lead schema
TaskLeadResponse | nullThe lead the task follows up; null when it follows none up.
Variant 1: TaskLeadResponse
idstringrequiredThe lead's id.
Format: uuid
namestringrequiredThe lead's first and last name.
Variant 2: null
nulllead_idstring | nullThe lead the task follows up.
Format: uuid
Show lead_id schema
string | nullThe lead the task follows up.
Variant 1: string
stringVariant 2: null
nulllease_idstring | nullThe lease the task concerns.
Format: uuid
Show lease_id schema
string | nullThe lease the task concerns.
Variant 1: string
stringVariant 2: null
nullpinned_note_bystring | nullWho wrote the pinned note, where there is one.
Format: uuid
Show pinned_note_by schema
string | nullWho wrote the pinned note, where there is one.
Variant 1: string
stringVariant 2: null
nullprioritystringrequiredlow, normal, high or urgent.
proof_photo_countintegerrequiredHow many confirmed proof photos it holds. On a work order, its after photos count too.
reopen_countintegerrequiredHow many times it has been reopened.
requires_photo_proofbooleanrequiredTrue when completing it needs proof photos.
similar_open_task_idstring | nullAnother open task of the same type on the same unit, where there is one. A hint only: the create is never refused for it.
Format: uuid
Show similar_open_task_id schema
string | nullAnother open task of the same type on the same unit, where there is one. A hint only: the create is never refused for it.
Variant 1: string
stringVariant 2: null
nullsourcestringrequiredWhat filed it: manual for staff, delinquency for the delinquency engine, access_sync for the access sync, inspection for follow-up work opened from an inspection finding.
source_reference_idstring | nullThe row the source points at -- the delinquency case, for a delinquency task; for an access sync task, the facility's access sync state (a pause, a lost tenant scope) or the unit link (a unit stuck for a day, a mismatch, a tenant finding); for follow-up work opened from an inspection finding, the inspection.
Format: uuid
Show source_reference_id schema
string | nullThe row the source points at -- the delinquency case, for a delinquency task; for an access sync task, the facility's access sync state (a pause, a lost tenant scope) or the unit link (a unit stuck for a day, a mismatch, a tenant finding); for follow-up work opened from an inspection finding, the inspection.
Variant 1: string
stringVariant 2: null
nullstatusstringrequiredopen, in_progress, completed or cancelled.
task_typestringrequiredThe board type. A task stored without one reads the type its category and title give it.
template_idstring | nullThe recurring template that filed it, where one did.
Format: uuid
Show template_id schema
string | nullThe recurring template that filed it, where one did.
Variant 1: string
stringVariant 2: null
nulltenantTaskTenantResponse | nullThe tenant the task concerns; null when it concerns none.
Show tenant schema
TaskTenantResponse | nullThe tenant the task concerns; null when it concerns none.
Variant 1: TaskTenantResponse
idstringrequiredThe tenant's id.
Format: uuid
namestringrequiredThe tenant's name: the company for a business tenant, otherwise first and last name.
Variant 2: null
nulltenant_idstring | nullThe tenant the task concerns.
Format: uuid
Show tenant_id schema
string | nullThe tenant the task concerns.
Variant 1: string
stringVariant 2: null
nulltitlestringrequiredWhat needs doing.
unitTaskUnitResponse | nullThe unit the task concerns; null when it concerns none. A deleted unit is still shown, flagged.
Show unit schema
TaskUnitResponse | nullThe unit the task concerns; null when it concerns none. A deleted unit is still shown, flagged.
Variant 1: TaskUnitResponse
idstringrequiredThe unit's id.
Format: uuid
is_deletedbooleanrequiredTrue when the unit has been deleted.
unit_numberstringrequiredThe unit's number at its facility.
Variant 2: null
nullunit_idstring | nullThe unit the task concerns.
Format: uuid
Show unit_id schema
string | nullThe unit the task concerns.
Variant 1: string
stringVariant 2: null
nullupdated_atstringrequiredWhen it last changed.
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