Skip to content
FacilydevelopersDashboard
Build with Facily
DocsREST APIsCreate Work Order
Search the full API reference Esc to close

Create Work Order

Tasks · REST API reference

Get support
POST/v1/facilities/{facility_id}/work-orders
File one work order, attributed to the caller. Answers 201 with the new row.

Authentication

Bearer API key or Facily session, subject to permissions and facility scope.

Authentication and scope

Request 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
curl --request POST \
  --url 'https://api.staging.facily.ai/v1/facilities/<FACILITY_ID>/work-orders' \
  --header "Authorization: Bearer $FACILY_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "category": "doors",
  "title": "string",
  "assignment": {
    "mode": "direct",
    "user_id": "00000000-0000-4000-8000-000000000001"
  },
  "description": "string",
  "due_date": "2026-10-29",
  "estimated_cost": 0,
  "hold_unit": false,
  "location_note": "string",
  "priority": "normal",
  "requires_photo_proof": false,
  "unit_id": "00000000-0000-4000-8000-000000000001",
  "unit_number": "string"
}'
An example for building your request, not an executed call. Check required fields, allowed values, and environment configuration before sending.

Parameters

facility_idpath · stringrequired

Format: uuid

Request body

application/json · Required

assignmentTaskAssignmentRequest | null

Who does the work, in the form the task assign route takes. Omitted, the work order is filed unassigned.

Show assignment schema
TaskAssignmentRequest | null

Who does the work, in the form the task assign route takes. Omitted, the work order is filed unassigned.

Variant 1: TaskAssignmentRequest
modestringrequired

direct 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 | null

The person to assign, with mode direct only.

Format: uuid

Show user_id schema
string | null

The person to assign, with mode direct only.

Variant 1: string
string
Variant 2: null
null
Variant 2: null
null
categorystringrequired

The trade the work needs: doors, electrical, access, building, elevator, pest_control, hvac, security, paving, locks, plumbing, roofing, cleaning, maintenance or other.

Values: "doors", "electrical", "access", "building", "elevator", "pest_control", "hvac", "security", "paving", "locks", "plumbing", "roofing", "cleaning", "maintenance", "other"

descriptionstring | null

Longer detail for whoever picks the work order up. At most 2,000 characters. Empty or only spaces is stored as null.

Max length: 2000

Show description schema
string | null

Longer detail for whoever picks the work order up. At most 2,000 characters. Empty or only spaces is stored as null.

Variant 1: string
string
Variant 2: null
null
due_datestring | null

Business date the work order is due; null for no deadline.

Format: date

Show due_date schema
string | null

Business date the work order is due; null for no deadline.

Variant 1: string
string
Variant 2: null
null
estimated_costnumber | string | null

The estimate, as a decimal string: zero or more, at most 99999999.99, with at most two decimal places. Null for none; null is not zero.

Minimum: 0 · Pattern: ^(?!^[-+.]*$)[+-]?0*(?:\d{0,8}|(?=[\d.]{1,11}0*$)\d{0,8}\.\d{0,2}0*$)

Show estimated_cost schema
number | string | null

The estimate, as a decimal string: zero or more, at most 99999999.99, with at most two decimal places. Null for none; null is not zero.

Variant 1: number
number
Variant 2: string
string
Variant 3: null
null
hold_unitboolean

True takes the unit out of service for this work order as it is filed. It needs a unit and the unit.write permission at this facility, and the unit must be available, or in maintenance with no work order holding it. A hold that is refused fails the whole request: nothing is filed.

Default: false

location_notestring | null

Where the work is when it is not on a unit, such as Gate 2. At most 120 characters. Empty or only spaces is stored as null.

Max length: 120

Show location_note schema
string | null

Where the work is when it is not on a unit, such as Gate 2. At most 120 characters. Empty or only spaces is stored as null.

Variant 1: string
string
Variant 2: null
null
prioritystring

How urgent the work order is.

Default: "normal" · Values: "low", "normal", "high", "urgent"

requires_photo_proofboolean | null

Whether completing the work order needs proof photos; its after photos count toward them. Omitted, the facility's default for work orders 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 | null

Whether completing the work order needs proof photos; its after photos count toward them. Omitted, the facility's default for work orders 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
boolean
Variant 2: null
null
titlestringrequired

What needs doing. Trimmed and required.

Min length: 1 · Max length: 255

unit_idstring | null

The unit the work is on, where it is on one. It cannot be added or changed later.

Format: uuid

Show unit_id schema
string | null

The unit the work is on, where it is on one. It cannot be added or changed later.

Variant 1: string
string
Variant 2: null
null
unit_numberstring | null

The 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 | null

The 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
string
Variant 2: null
null
vendorstring | null

Who does the work, as typed. At most 120 characters. Empty or only spaces is stored as null.

Max length: 120

Show vendor schema
string | null

Who does the work, as typed. At most 120 characters. Empty or only spaces is stored as null.

Variant 1: string
string
Variant 2: null
null

Responses

Expand a status to inspect its schema. Generated examples show structure and synthetic values.

201Successful Response
JSON · generated example
{
  "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,
    "extension": {
      "category": "string",
      "display_status": "open",
      "estimated_cost": "<VALUE_MATCHING_PATTERN>",
      "location_note": "string",
      "number": "string",
      "vendor": "string"
    },
    "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

dataWorkOrderResponserequired

One work order on its own list: the task row, with the fields the work order table reads.

Show data schema
assigned_tostring | null

The staff user who owns it; null for unassigned.

Format: uuid

Show assigned_to schema
string | null

The staff user who owns it; null for unassigned.

Variant 1: string
string
Variant 2: null
null
assigneePersonResponse | null

Who the task is assigned to; null when nobody is.

Show assignee schema
PersonResponse | null

Who the task is assigned to; null when nobody is.

Variant 1: PersonResponse
display_namestringrequired

The name to show for the user.

idstringrequired

The user's id.

Format: uuid

Variant 2: null
null
assignment_modestringrequired

direct, 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_proofbooleanrequired

True when the task is open, needs proof photos, and holds fewer than its facility asks for.

capabilitiesTaskCapabilitiesResponserequired

What the caller may do with a task now, one flag per action.

Show capabilities schema
add_photobooleanrequired

True when the caller may add a photo to it now.

assignbooleanrequired

True when the caller may assign it now.

assign_autobooleanrequired

True when the caller may give it to the rotation now.

cancelbooleanrequired

True when the caller may cancel it now.

claimbooleanrequired

True when the caller may claim it now.

commentbooleanrequired

True when the caller may comment on it now.

completebooleanrequired

True when the caller may complete it now.

deletebooleanrequired

True when the caller may delete it now.

editbooleanrequired

True when the caller may edit it now.

edit_due_datebooleanrequired

True when the caller may change its due date now.

edit_extensionbooleanrequired

True 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_flagbooleanrequired

True when the caller may change whether it needs proof photos now.

edit_titlebooleanrequired

True when the caller may change its title now.

follow_upbooleanrequired

True 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_unitbooleanrequired

True when the caller may take the work order's unit out of service now. False on any other kind.

move_to_openbooleanrequired

True when the caller may move it back to open now.

override_proofbooleanrequired

True when the caller may complete it without its proof photos, giving a reason now.

pinbooleanrequired

True when the caller may write its pinned note now.

record_costbooleanrequired

True 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_findingbooleanrequired

True when the caller may record or remove the inspection's findings now. False on any other kind.

release_holdbooleanrequired

True when the caller may release the unit the work order holds now, in any status. False on any other kind.

reopenbooleanrequired

True when the caller may reopen it now.

set_substatusbooleanrequired

True when the caller may move the work order to waiting on vendor, blocked or in progress now. False on any other kind.

startbooleanrequired

True when the caller may start the task now.

verifybooleanrequired

True when the caller may verify the completed work order now. False on any other kind.

case_closed_onstring | null

For 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 | null

For a delinquency engine task whose case has closed, the date it closed at the task's facility; null otherwise.

Variant 1: string
string
Variant 2: null
null
case_lease_idstring | null

For a delinquency engine task, the lease of its delinquency case; null otherwise.

Format: uuid

Show case_lease_id schema
string | null

For a delinquency engine task, the lease of its delinquency case; null otherwise.

Variant 1: string
string
Variant 2: null
null
categorystringrequired

What kind of work this is, including the engine-only categories.

completed_atstring | null

When it was completed; null while it is open.

Format: date-time

Show completed_at schema
string | null

When it was completed; null while it is open.

Variant 1: string
string
Variant 2: null
null
completed_bystring | null

Who completed it.

Format: uuid

Show completed_by schema
string | null

Who completed it.

Variant 1: string
string
Variant 2: null
null
created_atstringrequired

When the task was filed.

Format: date-time

created_bystringrequired

The actor the row is attributed to.

Format: uuid

creatorPersonResponserequired

A user, as a task or a thread entry names one.

Show creator schema
display_namestringrequired

The name to show for the user.

idstringrequired

The user's id.

Format: uuid

days_overdueintegerrequired

Days past the due date at the task's facility; 0 unless due_state is overdue.

days_until_dueinteger | null

0 when due today, the days ahead when upcoming, null otherwise.

Show days_until_due schema
integer | null

0 when due today, the days ahead when upcoming, null otherwise.

Variant 1: integer
integer
Variant 2: null
null
descriptionstring | null

Longer detail, where there is any.

Show description schema
string | null

Longer detail, where there is any.

Variant 1: string
string
Variant 2: null
null
due_datestring | null

Business date the task is due.

Format: date

Show due_date schema
string | null

Business date the task is due.

Variant 1: string
string
Variant 2: null
null
due_statestringrequired

Where 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_closedbooleanrequired

True for an open delinquency engine task whose case has closed, other than a lock removal. Such a task counts only as open.

engine_managedbooleanrequired

True for a task the delinquency engine filed.

extensionWorkOrderListExtensionResponserequired

What a work order's row carries on the work order list.

Show extension schema
categorystringrequired

The trade the work needs: doors, electrical, access, building, elevator, pest_control, hvac, security, paving, locks, plumbing, roofing, cleaning, maintenance or other.

display_statusstringrequired

open, in_progress, waiting_on_vendor, blocked, complete, verified or cancelled.

Values: "open", "in_progress", "waiting_on_vendor", "blocked", "complete", "verified", "cancelled"

estimated_coststring | nullrequired

The estimate, as a decimal string; null when none was given. Null is not zero.

Pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$

Show estimated_cost schema
string | null

The estimate, as a decimal string; null when none was given. Null is not zero.

Variant 1: string
string
Variant 2: null
null
location_notestring | nullrequired

Where the work is when it is not on a unit, such as Gate 2; null for none.

Show location_note schema
string | null

Where the work is when it is not on a unit, such as Gate 2; null for none.

Variant 1: string
string
Variant 2: null
null
numberstringrequired

The number a person reads, such as WO-0042 or INS-0007.

vendorstring | nullrequired

Who does the work, as typed; null for none.

Show vendor schema
string | null

Who does the work, as typed; null for none.

Variant 1: string
string
Variant 2: null
null
facility_idstringrequired

The facility the task belongs to.

Format: uuid

facility_namestringrequired

The name of the task's facility.

has_pinned_notebooleanrequired

True when the task has a pinned note. The note is on the task's detail.

has_proof_overridebooleanrequired

True when the task was completed without its proof photos, with a recorded reason.

idstringrequired

Unique identifier for this task.

Format: uuid

is_escalatedbooleanrequired

True when the task is overdue by more than its facility's escalation threshold and escalation is on.

kindstringrequired

task, work_order or inspection. It never changes.

leadTaskLeadResponse | null

The lead the task follows up; null when it follows none up.

Show lead schema
TaskLeadResponse | null

The lead the task follows up; null when it follows none up.

Variant 1: TaskLeadResponse
idstringrequired

The lead's id.

Format: uuid

namestringrequired

The lead's first and last name.

Variant 2: null
null
lead_idstring | null

The lead the task follows up.

Format: uuid

Show lead_id schema
string | null

The lead the task follows up.

Variant 1: string
string
Variant 2: null
null
lease_idstring | null

The lease the task concerns.

Format: uuid

Show lease_id schema
string | null

The lease the task concerns.

Variant 1: string
string
Variant 2: null
null
pinned_note_bystring | null

Who wrote the pinned note, where there is one.

Format: uuid

Show pinned_note_by schema
string | null

Who wrote the pinned note, where there is one.

Variant 1: string
string
Variant 2: null
null
prioritystringrequired

low, normal, high or urgent.

proof_photo_countintegerrequired

How many confirmed proof photos it holds. On a work order, its after photos count too.

reopen_countintegerrequired

How many times it has been reopened.

requires_photo_proofbooleanrequired

True when completing it needs proof photos.

sourcestringrequired

What 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 | null

The 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 | null

The 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
string
Variant 2: null
null
statusstringrequired

open, in_progress, completed or cancelled.

task_typestringrequired

The board type. A task stored without one reads the type its category and title give it.

template_idstring | null

The recurring template that filed it, where one did.

Format: uuid

Show template_id schema
string | null

The recurring template that filed it, where one did.

Variant 1: string
string
Variant 2: null
null
tenantTaskTenantResponse | null

The tenant the task concerns; null when it concerns none.

Show tenant schema
TaskTenantResponse | null

The tenant the task concerns; null when it concerns none.

Variant 1: TaskTenantResponse
idstringrequired

The tenant's id.

Format: uuid

namestringrequired

The tenant's name: the company for a business tenant, otherwise first and last name.

Variant 2: null
null
tenant_idstring | null

The tenant the task concerns.

Format: uuid

Show tenant_id schema
string | null

The tenant the task concerns.

Variant 1: string
string
Variant 2: null
null
titlestringrequired

What needs doing.

unitTaskUnitResponse | null

The unit the task concerns; null when it concerns none. A deleted unit is still shown, flagged.

Show unit schema
TaskUnitResponse | null

The unit the task concerns; null when it concerns none. A deleted unit is still shown, flagged.

Variant 1: TaskUnitResponse
idstringrequired

The unit's id.

Format: uuid

is_deletedbooleanrequired

True when the unit has been deleted.

unit_numberstringrequired

The unit's number at its facility.

Variant 2: null
null
unit_idstring | null

The unit the task concerns.

Format: uuid

Show unit_id schema
string | null

The unit the task concerns.

Variant 1: string
string
Variant 2: null
null
updated_atstringrequired

When it last changed.

Format: date-time

metaMetarequired

Envelope metadata. Every response carries one.

Show meta schema
request_idstringrequired
400Validation error
JSON · generated example
{
  "error": {
    "code": "string",
    "message": "string",
    "details": {}
  },
  "meta": {
    "request_id": "string"
  }
}

application/json

errorErrorBodyrequired

The shape of error.* in an error response.

Show error schema
codestringrequired
detailsobject | null
Show details schema
object | null
Variant 1: object
object
Variant 2: null
null
messagestringrequired
metaMetarequired

Envelope metadata. Every response carries one.

Show meta schema
request_idstringrequired
401Unauthenticated
JSON · generated example
{
  "error": {
    "code": "string",
    "message": "string",
    "details": {}
  },
  "meta": {
    "request_id": "string"
  }
}

application/json

errorErrorBodyrequired

The shape of error.* in an error response.

Show error schema
codestringrequired
detailsobject | null
Show details schema
object | null
Variant 1: object
object
Variant 2: null
null
messagestringrequired
metaMetarequired

Envelope metadata. Every response carries one.

Show meta schema
request_idstringrequired
403Permission denied
JSON · generated example
{
  "error": {
    "code": "string",
    "message": "string",
    "details": {}
  },
  "meta": {
    "request_id": "string"
  }
}

application/json

errorErrorBodyrequired

The shape of error.* in an error response.

Show error schema
codestringrequired
detailsobject | null
Show details schema
object | null
Variant 1: object
object
Variant 2: null
null
messagestringrequired
metaMetarequired

Envelope metadata. Every response carries one.

Show meta schema
request_idstringrequired
404Not found
JSON · generated example
{
  "error": {
    "code": "string",
    "message": "string",
    "details": {}
  },
  "meta": {
    "request_id": "string"
  }
}

application/json

errorErrorBodyrequired

The shape of error.* in an error response.

Show error schema
codestringrequired
detailsobject | null
Show details schema
object | null
Variant 1: object
object
Variant 2: null
null
messagestringrequired
metaMetarequired

Envelope metadata. Every response carries one.

Show meta schema
request_idstringrequired
409Business logic error
JSON · generated example
{
  "error": {
    "code": "string",
    "message": "string",
    "details": {}
  },
  "meta": {
    "request_id": "string"
  }
}

application/json

errorErrorBodyrequired

The shape of error.* in an error response.

Show error schema
codestringrequired
detailsobject | null
Show details schema
object | null
Variant 1: object
object
Variant 2: null
null
messagestringrequired
metaMetarequired

Envelope metadata. Every response carries one.

Show meta schema
request_idstringrequired
503Temporary failure
JSON · generated example
{
  "error": {
    "code": "string",
    "message": "string",
    "details": {}
  },
  "meta": {
    "request_id": "string"
  }
}

application/json

errorErrorBodyrequired

The shape of error.* in an error response.

Show error schema
codestringrequired
detailsobject | null
Show details schema
object | null
Variant 1: object
object
Variant 2: null
null
messagestringrequired
metaMetarequired

Envelope metadata. Every response carries one.

Show meta schema
request_idstringrequired
Continue exploringAll tasks operations
Build something that works beautifully.

Facily API · Contract v1.200 · Reviewed October 29, 2026

Create Work Order | Facily Developers