API 2026-11-01 Draft contract. Webhook payloads are final for this version; the REST API is in design and not live yet.

Work orders

Maintenance issues an inspector spots in the field, usually in common areas or where the association maintains the item. HOACraft sends each submitted work order to your system; drafts stay on the phone. Vendor billing and payment stay with you.

How it flows

  1. An inspector spots a broken gate, a dead light or anything the association maintains.
  2. They submit a work order with photos, category, priority and an optional vendor. You get work_order.created.
  3. Status and vendor changes send work_order.updated; completion sends work_order.completed with notes and photos.
  4. If the vendor workflow lives in your system, PATCH the status back so the inspector can check the work on the next drive.

The WorkOrder object

idrequiredstring
numberrequiredintegerPer-community number shown to staff
statusrequiredstring
One of: open assigned inProgress completed cancelled
locationrequiredLocation
titlerequiredstring
categoryrequiredstring
One of: landscaping irrigation lighting poolAmenity fencingGates signage drainage pavement general
priorityrequiredstring
One of: low normal high urgent
descriptionstring
vendorobject · nullable
due_datestring (date-time) · nullable
follow_up_datestring (date-time) · nullableWhen the inspector plans to check it again.
photosarray of Photo
created_atrequiredstring (date-time)
created_byrequiredPerson
ai_assistedbooleanThe description was drafted with AI and reviewed by the creator.
completed_atstring (date-time) · nullable
completion_notesstring · nullable

Sample

{
  "id": "wo-ho4l8rev40-b",
  "number": 106,
  "status": "completed",
  "location": {
    "kind": "common_area",
    "id": "wce-ca-pool",
    "address": "Pool & Clubhouse",
    "geo": {
      "lat": 30.544838,
      "lng": -97.690914
    }
  },
  "title": "Pool gate latch broken",
  "category": "fencingGates",
  "priority": "urgent",
  "description": "Latch does not catch; gate will not self-close.",
  "vendor": {
    "id": "v-ssh",
    "name": "SSH Gates & Access"
  },
  "due_date": null,
  "follow_up_date": null,
  "photos": [],
  "created_at": "2026-11-13T16:00:00.000Z",
  "created_by": {
    "id": "staff-dana",
    "name": "Dana Whitfield"
  },
  "ai_assisted": false,
  "completed_at": "2026-11-13T16:00:00.000Z",
  "completion_notes": "Latch and closer replaced, tested"
}

Webhook events

Sent to your endpoint as they happen, signed as described in Webhooks & signing. The samples are real output from the HOACraft app, checked against the code on every build.

EVENTwork_order.created

A work order was submitted in the field

data fields

work_orderrequiredWorkOrder

Sample payload

{
  "id": "evt-ho4l8rev40-d",
  "type": "work_order.created",
  "api_version": "2026-11-01",
  "created_at": "2026-11-13T16:00:00.000Z",
  "community": {
    "id": "willow-creek",
    "name": "Willow Creek Estates"
  },
  "data": {
    "work_order": {
      "id": "wo-ho4l8rev40-b",
      "number": 106,
      "status": "assigned",
      "location": {
        "kind": "common_area",
        "id": "wce-ca-pool",
        "address": "Pool & Clubhouse",
        "geo": {
          "lat": 30.544838,
          "lng": -97.690914
        }
      },
      "title": "Pool gate latch broken",
      "category": "fencingGates",
      "priority": "urgent",
      "description": "Latch does not catch; gate will not self-close.",
      "vendor": {
        "id": "v-ssh",
        "name": "SSH Gates & Access"
      },
      "due_date": null,
      "follow_up_date": null,
      "photos": [],
      "created_at": "2026-11-13T16:00:00.000Z",
      "created_by": {
        "id": "staff-dana",
        "name": "Dana Whitfield"
      },
      "ai_assisted": false,
      "completed_at": null,
      "completion_notes": null
    }
  }
}
EVENTwork_order.updated

A work order changed status or vendor

data fields

work_orderrequiredWorkOrder
previous_statusstring
One of: open assigned inProgress completed cancelled

Sample payload

{
  "id": "evt-ho4l8rev40-f",
  "type": "work_order.updated",
  "api_version": "2026-11-01",
  "created_at": "2026-11-13T16:00:00.000Z",
  "community": {
    "id": "willow-creek",
    "name": "Willow Creek Estates"
  },
  "data": {
    "work_order": {
      "id": "wo-ho4l8rev40-b",
      "number": 106,
      "status": "inProgress",
      "location": {
        "kind": "common_area",
        "id": "wce-ca-pool",
        "address": "Pool & Clubhouse",
        "geo": {
          "lat": 30.544838,
          "lng": -97.690914
        }
      },
      "title": "Pool gate latch broken",
      "category": "fencingGates",
      "priority": "urgent",
      "description": "Latch does not catch; gate will not self-close.",
      "vendor": {
        "id": "v-ssh",
        "name": "SSH Gates & Access"
      },
      "due_date": null,
      "follow_up_date": null,
      "photos": [],
      "created_at": "2026-11-13T16:00:00.000Z",
      "created_by": {
        "id": "staff-dana",
        "name": "Dana Whitfield"
      },
      "ai_assisted": false,
      "completed_at": null,
      "completion_notes": null
    },
    "previous_status": "assigned"
  }
}
EVENTwork_order.completed

A work order was marked completed

data fields

work_orderrequiredWorkOrder

Sample payload

{
  "id": "evt-ho4l8rev40-h",
  "type": "work_order.completed",
  "api_version": "2026-11-01",
  "created_at": "2026-11-13T16:00:00.000Z",
  "community": {
    "id": "willow-creek",
    "name": "Willow Creek Estates"
  },
  "data": {
    "work_order": {
      "id": "wo-ho4l8rev40-b",
      "number": 106,
      "status": "completed",
      "location": {
        "kind": "common_area",
        "id": "wce-ca-pool",
        "address": "Pool & Clubhouse",
        "geo": {
          "lat": 30.544838,
          "lng": -97.690914
        }
      },
      "title": "Pool gate latch broken",
      "category": "fencingGates",
      "priority": "urgent",
      "description": "Latch does not catch; gate will not self-close.",
      "vendor": {
        "id": "v-ssh",
        "name": "SSH Gates & Access"
      },
      "due_date": null,
      "follow_up_date": null,
      "photos": [],
      "created_at": "2026-11-13T16:00:00.000Z",
      "created_by": {
        "id": "staff-dana",
        "name": "Dana Whitfield"
      },
      "ai_assisted": false,
      "completed_at": "2026-11-13T16:00:00.000Z",
      "completion_notes": "Latch and closer replaced, tested"
    }
  }
}

Endpoints

Planned REST API, not live yet. Base URL https://sandbox.api.hoacraft.com/v1, Authorization: Bearer <key>. See basics.

List work orders

GET/work-orders

Parameters

community_idquery · string
statusquery · string
updated_sincequery · string (date-time)
cursorquery · string
limitquery · integer default 100 · min 1 · max 500

Responses

200A page of work orders, oldest change first.object

Example request

curl -X GET "https://sandbox.api.hoacraft.com/v1/work-orders" \
  -H "Authorization: Bearer $HOACRAFT_API_KEY"
Example response
{
  "data": [
    {
      "id": "wo-ho4l8rev40-b",
      "number": 106,
      "status": "completed",
      "location": {
        "kind": "common_area",
        "id": "wce-ca-pool",
        "address": "Pool & Clubhouse",
        "geo": {
          "lat": 30.544838,
          "lng": -97.690914
        }
      },
      "title": "Pool gate latch broken",
      "category": "fencingGates",
      "priority": "urgent",
      "description": "Latch does not catch; gate will not self-close.",
      "vendor": {
        "id": "v-ssh",
        "name": "SSH Gates & Access"
      },
      "due_date": null,
      "follow_up_date": null,
      "photos": [],
      "created_at": "2026-11-13T16:00:00.000Z",
      "created_by": {
        "id": "staff-dana",
        "name": "Dana Whitfield"
      },
      "ai_assisted": false,
      "completed_at": "2026-11-13T16:00:00.000Z",
      "completion_notes": "Latch and closer replaced, tested"
    }
  ],
  "next_cursor": "string"
}

Get a work order

GET/work-orders/{workOrderId}

Parameters

workOrderIdrequiredpath · string

Responses

200OKWorkOrder
404Not foundError

Example request

curl -X GET "https://sandbox.api.hoacraft.com/v1/work-orders/wo-ho4l8rev40-b" \
  -H "Authorization: Bearer $HOACRAFT_API_KEY"
Example response
{
  "id": "wo-ho4l8rev40-b",
  "number": 106,
  "status": "completed",
  "location": {
    "kind": "common_area",
    "id": "wce-ca-pool",
    "address": "Pool & Clubhouse",
    "geo": {
      "lat": 30.544838,
      "lng": -97.690914
    }
  },
  "title": "Pool gate latch broken",
  "category": "fencingGates",
  "priority": "urgent",
  "description": "Latch does not catch; gate will not self-close.",
  "vendor": {
    "id": "v-ssh",
    "name": "SSH Gates & Access"
  },
  "due_date": null,
  "follow_up_date": null,
  "photos": [],
  "created_at": "2026-11-13T16:00:00.000Z",
  "created_by": {
    "id": "staff-dana",
    "name": "Dana Whitfield"
  },
  "ai_assisted": false,
  "completed_at": "2026-11-13T16:00:00.000Z",
  "completion_notes": "Latch and closer replaced, tested"
}

Update from your system (vendor assigned, work done, cancelled)

PATCH/work-orders/{workOrderId}

Use this when the vendor workflow runs in your system, so the inspector sees the current status and can check the work on the next drive. Status changes follow the same rules as the app: open → assigned → in_progress → completed, with cancel and reopen.

Parameters

workOrderIdrequiredpath · string

Request body

external_idstringYour work order id.
statusstring
One of: open assigned inProgress completed cancelled
vendor_external_idstring · nullableYour vendor id. Imported vendors only.
due_datestring (date-time) · nullable
completion_notesstringRequired when status is completed.

Responses

200UpdatedWorkOrder
404Not foundError
409The status change is not allowed from the current status.Error

Example request

curl -X PATCH "https://sandbox.api.hoacraft.com/v1/work-orders/wo-ho4l8rev40-b" \
  -H "Authorization: Bearer $HOACRAFT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "external_id": "string",
  "status": "open",
  "vendor_external_id": "string",
  "due_date": "2026-11-13T16:00:00Z",
  "completion_notes": "string"
}'
Example response
{
  "id": "wo-ho4l8rev40-b",
  "number": 106,
  "status": "completed",
  "location": {
    "kind": "common_area",
    "id": "wce-ca-pool",
    "address": "Pool & Clubhouse",
    "geo": {
      "lat": 30.544838,
      "lng": -97.690914
    }
  },
  "title": "Pool gate latch broken",
  "category": "fencingGates",
  "priority": "urgent",
  "description": "Latch does not catch; gate will not self-close.",
  "vendor": {
    "id": "v-ssh",
    "name": "SSH Gates & Access"
  },
  "due_date": null,
  "follow_up_date": null,
  "photos": [],
  "created_at": "2026-11-13T16:00:00.000Z",
  "created_by": {
    "id": "staff-dana",
    "name": "Dana Whitfield"
  },
  "ai_assisted": false,
  "completed_at": "2026-11-13T16:00:00.000Z",
  "completion_notes": "Latch and closer replaced, tested"
}