/v1/tasks/{task_id}/assignAuthentication
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/tasks/<TASK_ID>/assign' \
--header "Authorization: Bearer $FACILY_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
"mode": "direct",
"user_id": "00000000-0000-4000-8000-000000000001"
}'Parameters
task_idpath · stringrequiredFormat: uuid
Request body
application/json · Required
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
nullResponses
Expand a status to inspect its schema. Generated examples show structure and synthetic values.
200Successful 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",
"photo_limit_per_type": 0,
"priority": "string",
"proof_min_photos": 0,
"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
dataTaskDetailResponserequiredOne task in full: the row, when it was first started, its pinned note, the record of a completion without proof photos, its facility's photo figures and, for a work order or an inspection, the kind's own fields in full.
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.
extensionWorkOrderExtensionResponse | InspectionExtensionResponse | nullA work order's or an inspection's own fields in full; null on a plain task.
Show extension schema
WorkOrderExtensionResponse | InspectionExtensionResponse | nullA work order's or an inspection's own fields in full; null on a plain task.
Variant 1: WorkOrderExtensionResponse
actual_coststring | nullrequiredThe recorded cost, as a decimal string; null until one is recorded. Null is not zero.
Pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
Show actual_cost schema
string | nullThe recorded cost, as a decimal string; null until one is recorded. Null is not zero.
Variant 1: string
Variant 2: null
categorystringrequiredThe trade the work needs: doors, electrical, access, building, elevator, pest_control, hvac, security, paving, locks, plumbing, roofing, cleaning, maintenance or other.
display_statusstringrequiredopen, in_progress, waiting_on_vendor, blocked, complete, verified or cancelled.
Values: "open", "in_progress", "waiting_on_vendor", "blocked", "complete", "verified", "cancelled"
estimated_coststring | nullrequiredThe estimate, as a decimal string; null when none was given. Null is not zero.
Pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
Show estimated_cost schema
string | nullThe estimate, as a decimal string; null when none was given. Null is not zero.
Variant 1: string
Variant 2: null
held_unit_idstring | nullrequiredThe unit this work order holds out of service; null when it holds none.
Format: uuid
Show held_unit_id schema
string | nullThe unit this work order holds out of service; null when it holds none.
Variant 1: string
Variant 2: null
location_notestring | nullrequiredWhere the work is when it is not on a unit, such as Gate 2; null for none.
Show location_note schema
string | nullWhere the work is when it is not on a unit, such as Gate 2; null for none.
Variant 1: string
Variant 2: null
numberstringrequiredThe number a person reads, such as WO-0042 or INS-0007.
resolution_notestring | nullrequiredHow the work was resolved; null for none.
Show resolution_note schema
string | nullHow the work was resolved; null for none.
Variant 1: string
Variant 2: null
substatusstring | nullrequiredwaiting_on_vendor or blocked while the work order is in progress and stopped; null otherwise.
Values: "waiting_on_vendor", "blocked"
Show substatus schema
string | nullwaiting_on_vendor or blocked while the work order is in progress and stopped; null otherwise.
Variant 1: string
Variant 2: null
unit_held_atstring | nullrequiredWhen the last hold began; null when it never held one.
Format: date-time
Show unit_held_at schema
string | nullWhen the last hold began; null when it never held one.
Variant 1: string
Variant 2: null
unit_prior_statusstring | nullrequiredThe unit's status when the last hold began, available or maintenance; null when it never held one.
Show unit_prior_status schema
string | nullThe unit's status when the last hold began, available or maintenance; null when it never held one.
Variant 1: string
Variant 2: null
unit_released_atstring | nullrequiredWhen the last hold ended; null while it holds the unit or when it never held one.
Format: date-time
Show unit_released_at schema
string | nullWhen the last hold ended; null while it holds the unit or when it never held one.
Variant 1: string
Variant 2: null
vendorstring | nullrequiredWho does the work, as typed; null for none.
Show vendor schema
string | nullWho does the work, as typed; null for none.
Variant 1: string
Variant 2: null
verified_atstring | nullrequiredWhen the completed work order was verified; null when it is not.
Format: date-time
Show verified_at schema
string | nullWhen the completed work order was verified; null when it is not.
Variant 1: string
Variant 2: null
verified_byPersonResponse | nullrequiredWho verified it; null when it is not verified.
Show verified_by schema
PersonResponse | nullWho verified it; null when it is not verified.
Variant 1: PersonResponse
Variant 2: null
Variant 2: InspectionExtensionResponse
display_statusstringrequiredscheduled, in_progress, completed or cancelled.
Values: "scheduled", "in_progress", "completed", "cancelled"
inspection_kindstringrequiredThe kind of round: lock_audit, fire_life_safety, pest_control, lighting_safety, walkthrough, move_out or general.
issues_found_countintegerrequiredHow many of them had an issue.
numberstringrequiredThe number a person reads, such as WO-0042 or INS-0007.
summary_notestring | nullrequiredThe round's summary note; null for none.
Show summary_note schema
string | nullThe round's summary note; null for none.
Variant 1: string
Variant 2: null
unit_groupInspectionUnitGroupResponse | nullrequiredThe part of the facility the round covers; null for the whole facility.
Show unit_group schema
InspectionUnitGroupResponse | nullThe part of the facility the round covers; null for the whole facility.
Variant 1: InspectionUnitGroupResponse
Variant 2: null
units_inspected_countintegerrequiredHow many units the round inspected.
Variant 3: 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
nullphoto_limit_per_typeintegerrequiredThe most photos of one type a task may hold at its facility.
pinned_notePinnedNoteResponse | nullThe pinned note with its author and time; null when there is none.
Show pinned_note schema
PinnedNoteResponse | nullThe pinned note with its author and time; null when there is none.
Variant 1: PinnedNoteResponse
authorPersonResponserequiredA user, as a task or a thread entry names one.
Show author schema
display_namestringrequiredThe name to show for the user.
idstringrequiredThe user's id.
Format: uuid
bodystringrequiredThe note's text.
updated_atstringrequiredWhen the note was last written.
Format: date-time
Variant 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_min_photosintegerrequiredHow many proof photos a task needs at its facility. On a work order, its after photos count toward it.
proof_overrideTaskProofOverrideResponse | nullThe record of a completion without proof photos; null when there is none.
Show proof_override schema
TaskProofOverrideResponse | nullThe record of a completion without proof photos; null when there is none.
Variant 1: TaskProofOverrideResponse
atstringrequiredWhen it was recorded.
Format: date-time
byPersonResponserequiredA user, as a task or a thread entry names one.
Show by schema
display_namestringrequiredThe name to show for the user.
idstringrequiredThe user's id.
Format: uuid
reasonstringrequiredWhy the task was completed without its proof photos.
Variant 2: null
nullproof_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.
sourcestringrequiredWhat 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
nullstarted_atstring | nullWhen it was first started; null if it never was.
Format: date-time
Show started_at schema
string | nullWhen it was first started; null if it never was.
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