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
- An inspector spots a broken gate, a dead light or anything the association maintains.
- They submit a work order with photos, category, priority and an optional vendor. You get
work_order.created. - Status and vendor changes send
work_order.updated; completion sendswork_order.completedwith notes and photos. - 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 | |
| numberrequiredinteger | Per-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) · nullable | When the inspector plans to check it again. |
| photosarray of Photo | |
| created_atrequiredstring (date-time) | |
| created_byrequiredPerson | |
| ai_assistedboolean | The 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.
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
}
}
}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"
}
}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
Parameters
| community_idquery · string | |
| statusquery · string | |
| updated_sincequery · string (date-time) | |
| cursorquery · string | |
| limitquery · integer | default 100 · min 1 · max 500 |
Responses
| 200 | A 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
Parameters
| workOrderIdrequiredpath · string |
Responses
| 200 | OKWorkOrder |
| 404 | Not 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)
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_idstring | Your work order id. |
| statusstring | One of: open assigned inProgress completed cancelled |
| vendor_external_idstring · nullable | Your vendor id. Imported vendors only. |
| due_datestring (date-time) · nullable | |
| completion_notesstring | Required when status is completed. |
Responses
| 200 | UpdatedWorkOrder |
| 404 | Not foundError |
| 409 | The 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"
}