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

Create Inspection

Tasks · REST API reference

Get support
POST/v1/facilities/{facility_id}/inspections
Schedule one inspection, 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>/inspections' \
  --header "Authorization: Bearer $FACILY_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "inspection_kind": "lock_audit",
  "scheduled_on": "2026-10-29",
  "assignment": {
    "mode": "direct",
    "user_id": "00000000-0000-4000-8000-000000000001"
  },
  "description": "string",
  "title": "string",
  "unit_group_id": "00000000-0000-4000-8000-000000000001"
}'
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 round, in the form the task assign route takes. Omitted, the round is scheduled unassigned.

Show assignment schema
TaskAssignmentRequest | null

Who does the round, in the form the task assign route takes. Omitted, the round is scheduled 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
descriptionstring | null

Longer detail for whoever does the round. 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 does the round. At most 2,000 characters. Empty or only spaces is stored as null.

Variant 1: string
string
Variant 2: null
null
inspection_kindstringrequired

The kind of round: lock_audit, fire_life_safety, pest_control, lighting_safety, walkthrough, move_out or general. It cannot be changed later.

Values: "lock_audit", "fire_life_safety", "pest_control", "lighting_safety", "walkthrough", "move_out", "general"

scheduled_onstringrequired

The business date the round is scheduled for. It is the task's due date.

Format: date

titlestring | null

The round's title, up to 255 characters. Omitted, empty or only spaces, it is the kind's name followed by the unit group's name, such as Lock audit, Building A.

Max length: 255

Show title schema
string | null

The round's title, up to 255 characters. Omitted, empty or only spaces, it is the kind's name followed by the unit group's name, such as Lock audit, Building A.

Variant 1: string
string
Variant 2: null
null
unit_group_idstring | null

The unit group the round covers: a live unit group of this facility. Omitted for the whole facility. It cannot be changed later.

Format: uuid

Show unit_group_id schema
string | null

The unit group the round covers: a live unit group of this facility. Omitted for the whole facility. It cannot be changed later.

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": {
      "display_status": "scheduled",
      "inspection_kind": "string",
      "issues_found_count": 0,
      "number": "string",
      "unit_group": {
        "id": "00000000-0000-4000-8000-000000000001",
        "name": "string"
      },
      "units_inspected_count": 0
    },
    "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

dataInspectionResponserequired

One inspection on its own list: the task row, with the fields the inspection list 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.

extensionInspectionListExtensionResponserequired

What an inspection's row carries on the inspection list.

Show extension schema
display_statusstringrequired

scheduled, in_progress, completed or cancelled.

Values: "scheduled", "in_progress", "completed", "cancelled"

inspection_kindstringrequired

The kind of round: lock_audit, fire_life_safety, pest_control, lighting_safety, walkthrough, move_out or general.

issues_found_countintegerrequired

How many of them had an issue.

numberstringrequired

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

unit_groupInspectionUnitGroupResponse | nullrequired

The part of the facility the round covers; null for the whole facility.

Show unit_group schema
InspectionUnitGroupResponse | null

The part of the facility the round covers; null for the whole facility.

Variant 1: InspectionUnitGroupResponse
idstringrequired

The unit group's id.

Format: uuid

namestringrequired

The unit group's name.

Variant 2: null
null
units_inspected_countintegerrequired

How many units the round inspected.

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 Inspection | Facily Developers