Violations
Read violations HOACraft recorded (the pull alternative to webhooks).
How it flows
- An inspector snaps a photo on the drive. HOACraft matches the house and the rule.
- A person approves it, and you get
violation.createdwith photos, rule citations and a cure date. - Your system sends the letter, then PATCHes the stage and next re-check date.
- After the cure date it shows up on the drive as a re-check. You get
violation.still_openorviolation.resolved.
The Violation object
| idrequiredstring | |
| statusrequiredstring | One of: open resolved |
| locationrequiredLocation | |
| issue_typerequiredstring | One of: landscaping trash exteriorMaintenance fence parking unapprovedChange signage commonAreaDamage other |
| titlerequiredstring | |
| descriptionstring | |
| levelinteger · nullable | 1 = first offence of this issue type at this location. |
| suggested_stagestring · nullable | Advisory |
| cure_bystring (date-time) · nullable | Next re-check date. |
| rulesarray of Rule | |
| photosarray of Photo | |
| observed_atrequiredstring (date-time) | |
| observed_byPerson | |
| approved_atstring (date-time) · nullable | |
| approved_byPerson · nullable | |
| session_idstring · nullable | The drive it was found on. |
| ai_assistedboolean | An AI suggestion was reviewed and approved by a person. |
| ai_confidencenumber · nullable | |
| rechecksrequiredarray of Recheck | |
| resolved_atstring (date-time) · nullable | |
| resolutionstring · nullable |
Sample
{
"id": "f-ho4l8rev40-3",
"status": "open",
"location": {
"kind": "property",
"id": "willow-creek-p02",
"lot_number": "Lot 02",
"address": "103 Willow Creek Dr",
"geo": {
"lat": 30.544895,
"lng": -97.692616
}
},
"issue_type": "landscaping",
"title": "Lawn not maintained",
"description": "Turf about 8 in, weeds in beds.",
"level": 1,
"suggested_stage": "Courtesy notice",
"cure_by": "2026-11-27T16:00:00.000Z",
"rules": [
{
"id": "wce-ccr-7.1",
"document": "CC&Rs",
"section": "7.1",
"title": "Lawn and Landscape Maintenance"
}
],
"photos": [
{
"id": "ph-ho4l8rev40-2",
"url": "https://files.hoacraft.com/photos/ph-ho4l8rev40-2.jpg",
"taken_at": "2026-11-13T16:00:00.000Z",
"demo": true
}
],
"observed_at": "2026-11-13T16:00:00.000Z",
"observed_by": {
"id": "staff-dana",
"name": "Dana Whitfield"
},
"approved_at": "2026-11-13T16:00:00.000Z",
"approved_by": {
"id": "staff-dana",
"name": "Dana Whitfield"
},
"session_id": "sess-ho4l8rev40-0",
"ai_assisted": true,
"ai_confidence": 0.86,
"rechecks": [],
"resolved_at": null,
"resolution": null
}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.
EVENTviolation.created
A violation was approved in the field
data fields
| violationrequiredViolation |
Sample payload
{
"id": "evt-ho4l8rev40-6",
"type": "violation.created",
"api_version": "2026-11-01",
"created_at": "2026-11-13T16:00:00.000Z",
"community": {
"id": "willow-creek",
"name": "Willow Creek Estates"
},
"data": {
"violation": {
"id": "f-ho4l8rev40-3",
"status": "open",
"location": {
"kind": "property",
"id": "willow-creek-p02",
"lot_number": "Lot 02",
"address": "103 Willow Creek Dr",
"geo": {
"lat": 30.544895,
"lng": -97.692616
}
},
"issue_type": "landscaping",
"title": "Lawn not maintained",
"description": "Turf about 8 in, weeds in beds.",
"level": 1,
"suggested_stage": "Courtesy notice",
"cure_by": "2026-11-27T16:00:00.000Z",
"rules": [
{
"id": "wce-ccr-7.1",
"document": "CC&Rs",
"section": "7.1",
"title": "Lawn and Landscape Maintenance"
}
],
"photos": [
{
"id": "ph-ho4l8rev40-2",
"url": "https://files.hoacraft.com/photos/ph-ho4l8rev40-2.jpg",
"taken_at": "2026-11-13T16:00:00.000Z",
"demo": true
}
],
"observed_at": "2026-11-13T16:00:00.000Z",
"observed_by": {
"id": "staff-dana",
"name": "Dana Whitfield"
},
"approved_at": "2026-11-13T16:00:00.000Z",
"approved_by": {
"id": "staff-dana",
"name": "Dana Whitfield"
},
"session_id": "sess-ho4l8rev40-0",
"ai_assisted": true,
"ai_confidence": 0.86,
"rechecks": [],
"resolved_at": null,
"resolution": null
}
}
}EVENTviolation.still_open
A re-check after the cure date found the violation unfixed
data fields
| violationrequiredViolation | |
| recheckrequiredRecheck |
Sample payload
{
"id": "evt-ho4l8rev40-8",
"type": "violation.still_open",
"api_version": "2026-11-01",
"created_at": "2026-11-13T16:00:00.000Z",
"community": {
"id": "willow-creek",
"name": "Willow Creek Estates"
},
"data": {
"violation": {
"id": "f-wce-3",
"status": "open",
"location": {
"kind": "property",
"id": "willow-creek-p12",
"lot_number": "Lot 12",
"address": "123 Willow Creek Dr",
"geo": {
"lat": 30.546254,
"lng": -97.689211
}
},
"issue_type": "landscaping",
"title": "Lawn not maintained (repeat)",
"description": "Turf still overgrown at follow-up; no visible change since courtesy notice.",
"level": 2,
"suggested_stage": "First violation notice",
"cure_by": "2026-11-27T16:00:00.000Z",
"rules": [
{
"id": "wce-ccr-7.1",
"document": "CC&Rs",
"section": "7.1",
"title": "Lawn and Landscape Maintenance"
}
],
"photos": [
{
"id": "ph-willow-creek-2",
"url": "https://files.hoacraft.com/photos/ph-willow-creek-2.jpg",
"taken_at": "2026-10-06T15:40:00.000Z",
"demo": true
}
],
"observed_at": "2026-10-06T15:30:00.000Z",
"observed_by": {
"id": "staff-dana",
"name": "Dana Whitfield"
},
"approved_at": "2026-10-06T17:00:00.000Z",
"approved_by": {
"id": "staff-dana",
"name": "Dana Whitfield"
},
"session_id": null,
"ai_assisted": false,
"ai_confidence": null,
"rechecks": [
{
"at": "2026-11-13T16:00:00.000Z",
"by": {
"id": "staff-dana",
"name": "Dana Whitfield"
},
"result": "still_open",
"note": "No visible change",
"photos": []
}
],
"resolved_at": null,
"resolution": null
},
"recheck": {
"at": "2026-11-13T16:00:00.000Z",
"by": {
"id": "staff-dana",
"name": "Dana Whitfield"
},
"result": "still_open",
"note": "No visible change",
"photos": []
}
}
}EVENTviolation.resolved
A re-check found the violation fixed
data fields
| violationrequiredViolation | |
| recheckrequiredRecheck |
Sample payload
{
"id": "evt-ho4l8rev40-a",
"type": "violation.resolved",
"api_version": "2026-11-01",
"created_at": "2026-11-13T16:00:00.000Z",
"community": {
"id": "willow-creek",
"name": "Willow Creek Estates"
},
"data": {
"violation": {
"id": "f-ho4l8rev40-3",
"status": "resolved",
"location": {
"kind": "property",
"id": "willow-creek-p02",
"lot_number": "Lot 02",
"address": "103 Willow Creek Dr",
"geo": {
"lat": 30.544895,
"lng": -97.692616
}
},
"issue_type": "landscaping",
"title": "Lawn not maintained",
"description": "Turf about 8 in, weeds in beds.",
"level": 1,
"suggested_stage": "Courtesy notice",
"cure_by": "2026-11-27T16:00:00.000Z",
"rules": [
{
"id": "wce-ccr-7.1",
"document": "CC&Rs",
"section": "7.1",
"title": "Lawn and Landscape Maintenance"
}
],
"photos": [
{
"id": "ph-ho4l8rev40-2",
"url": "https://files.hoacraft.com/photos/ph-ho4l8rev40-2.jpg",
"taken_at": "2026-11-13T16:00:00.000Z",
"demo": true
}
],
"observed_at": "2026-11-13T16:00:00.000Z",
"observed_by": {
"id": "staff-dana",
"name": "Dana Whitfield"
},
"approved_at": "2026-11-13T16:00:00.000Z",
"approved_by": {
"id": "staff-dana",
"name": "Dana Whitfield"
},
"session_id": "sess-ho4l8rev40-0",
"ai_assisted": true,
"ai_confidence": 0.86,
"rechecks": [
{
"at": "2026-11-13T16:00:00.000Z",
"by": {
"id": "staff-dana",
"name": "Dana Whitfield"
},
"result": "fixed",
"note": "Mowed and edged",
"photos": []
}
],
"resolved_at": "2026-11-13T16:00:00.000Z",
"resolution": "Fixed on re-check"
},
"recheck": {
"at": "2026-11-13T16:00:00.000Z",
"by": {
"id": "staff-dana",
"name": "Dana Whitfield"
},
"result": "fixed",
"note": "Mowed and edged",
"photos": []
}
}
}Endpoints
Planned REST API, not live yet. Base URL https://sandbox.api.hoacraft.com/v1, Authorization: Bearer <key>. See basics.
Replace the set of violations your system considers open
PUT/communities/{communityId}/open-violations
Drives the "re-check due" list on the inspector's phone. Violations that
HOACraft created and you omit here are marked resolved with resolution
closed_in_management_system (no webhook is sent for that change).
Parameters
| communityIdrequiredpath · string |
Request body
| violationsrequiredarray of OpenViolationInput |
Responses
| 200 | Per-row outcomeobject |
| 422 | Validation failedError |
Example request
curl -X PUT "https://sandbox.api.hoacraft.com/v1/communities/willow-creek/open-violations" \
-H "Authorization: Bearer $HOACRAFT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"violations": [
{
"external_id": "string",
"hoacraft_id": "string",
"property_external_id": "string",
"issue_type": "landscaping",
"title": "string",
"stage": "string",
"level": 1,
"cure_by": "2026-11-13T16:00:00Z",
"last_notice_at": "2026-11-13T16:00:00Z"
}
]
}'
Example response
{
"created": 1,
"updated": 1,
"errors": [
{
"index": 1,
"external_id": "string",
"message": "string"
}
]
}
List violations
GET/violations
Parameters
| community_idquery · string | |
| statusquery · string | One of: open resolved |
| updated_sincequery · string (date-time) | Only violations created, re-checked or resolved after this time. |
| cursorquery · string | |
| limitquery · integer | default 100 · min 1 · max 500 |
Responses
| 200 | A page of violations, oldest change first.object |
Example request
curl -X GET "https://sandbox.api.hoacraft.com/v1/violations" \
-H "Authorization: Bearer $HOACRAFT_API_KEY"
Example response
{
"data": [
{
"id": "f-ho4l8rev40-3",
"status": "open",
"location": {
"kind": "property",
"id": "willow-creek-p02",
"lot_number": "Lot 02",
"address": "103 Willow Creek Dr",
"geo": {
"lat": 30.544895,
"lng": -97.692616
}
},
"issue_type": "landscaping",
"title": "Lawn not maintained",
"description": "Turf about 8 in, weeds in beds.",
"level": 1,
"suggested_stage": "Courtesy notice",
"cure_by": "2026-11-27T16:00:00.000Z",
"rules": [
{
"id": "wce-ccr-7.1",
"document": "CC&Rs",
"section": "7.1",
"title": "Lawn and Landscape Maintenance"
}
],
"photos": [
{
"id": "ph-ho4l8rev40-2",
"url": "https://files.hoacraft.com/photos/ph-ho4l8rev40-2.jpg",
"taken_at": "2026-11-13T16:00:00.000Z",
"demo": true
}
],
"observed_at": "2026-11-13T16:00:00.000Z",
"observed_by": {
"id": "staff-dana",
"name": "Dana Whitfield"
},
"approved_at": "2026-11-13T16:00:00.000Z",
"approved_by": {
"id": "staff-dana",
"name": "Dana Whitfield"
},
"session_id": "sess-ho4l8rev40-0",
"ai_assisted": true,
"ai_confidence": 0.86,
"rechecks": [],
"resolved_at": null,
"resolution": null
}
],
"next_cursor": "string"
}
Get a violation
GET/violations/{violationId}
Parameters
| violationIdrequiredpath · string |
Responses
| 200 | OKViolation |
| 404 | Not foundError |
Example request
curl -X GET "https://sandbox.api.hoacraft.com/v1/violations/f-ho4l8rev40-3" \
-H "Authorization: Bearer $HOACRAFT_API_KEY"
Example response
{
"id": "f-ho4l8rev40-3",
"status": "open",
"location": {
"kind": "property",
"id": "willow-creek-p02",
"lot_number": "Lot 02",
"address": "103 Willow Creek Dr",
"geo": {
"lat": 30.544895,
"lng": -97.692616
}
},
"issue_type": "landscaping",
"title": "Lawn not maintained",
"description": "Turf about 8 in, weeds in beds.",
"level": 1,
"suggested_stage": "Courtesy notice",
"cure_by": "2026-11-27T16:00:00.000Z",
"rules": [
{
"id": "wce-ccr-7.1",
"document": "CC&Rs",
"section": "7.1",
"title": "Lawn and Landscape Maintenance"
}
],
"photos": [
{
"id": "ph-ho4l8rev40-2",
"url": "https://files.hoacraft.com/photos/ph-ho4l8rev40-2.jpg",
"taken_at": "2026-11-13T16:00:00.000Z",
"demo": true
}
],
"observed_at": "2026-11-13T16:00:00.000Z",
"observed_by": {
"id": "staff-dana",
"name": "Dana Whitfield"
},
"approved_at": "2026-11-13T16:00:00.000Z",
"approved_by": {
"id": "staff-dana",
"name": "Dana Whitfield"
},
"session_id": "sess-ho4l8rev40-0",
"ai_assisted": true,
"ai_confidence": 0.86,
"rechecks": [],
"resolved_at": null,
"resolution": null
}
Update from your system (after a letter, or when you close it)
PATCH/violations/{violationId}
Parameters
| violationIdrequiredpath · string |
Request body
| external_idstring | Your violation/case id. |
| stagestring | Stage you are at, e.g. "First violation notice". |
| cure_bystring (date-time) | Next re-check date. |
| statusstring | One of: open resolved |
| resolutionstring | e.g. "Fine paid, closed". |
Responses
| 200 | UpdatedViolation |
| 404 | Not foundError |
Example request
curl -X PATCH "https://sandbox.api.hoacraft.com/v1/violations/f-ho4l8rev40-3" \
-H "Authorization: Bearer $HOACRAFT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"external_id": "string",
"stage": "string",
"cure_by": "2026-11-13T16:00:00Z",
"status": "open",
"resolution": "string"
}'
Example response
{
"id": "f-ho4l8rev40-3",
"status": "open",
"location": {
"kind": "property",
"id": "willow-creek-p02",
"lot_number": "Lot 02",
"address": "103 Willow Creek Dr",
"geo": {
"lat": 30.544895,
"lng": -97.692616
}
},
"issue_type": "landscaping",
"title": "Lawn not maintained",
"description": "Turf about 8 in, weeds in beds.",
"level": 1,
"suggested_stage": "Courtesy notice",
"cure_by": "2026-11-27T16:00:00.000Z",
"rules": [
{
"id": "wce-ccr-7.1",
"document": "CC&Rs",
"section": "7.1",
"title": "Lawn and Landscape Maintenance"
}
],
"photos": [
{
"id": "ph-ho4l8rev40-2",
"url": "https://files.hoacraft.com/photos/ph-ho4l8rev40-2.jpg",
"taken_at": "2026-11-13T16:00:00.000Z",
"demo": true
}
],
"observed_at": "2026-11-13T16:00:00.000Z",
"observed_by": {
"id": "staff-dana",
"name": "Dana Whitfield"
},
"approved_at": "2026-11-13T16:00:00.000Z",
"approved_by": {
"id": "staff-dana",
"name": "Dana Whitfield"
},
"session_id": "sess-ho4l8rev40-0",
"ai_assisted": true,
"ai_confidence": 0.86,
"rechecks": [],
"resolved_at": null,
"resolution": null
}