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

Violations

Read violations HOACraft recorded (the pull alternative to webhooks).

How it flows

  1. An inspector snaps a photo on the drive. HOACraft matches the house and the rule.
  2. A person approves it, and you get violation.created with photos, rule citations and a cure date.
  3. Your system sends the letter, then PATCHes the stage and next re-check date.
  4. After the cure date it shows up on the drive as a re-check. You get violation.still_open or violation.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 · nullable1 = first offence of this issue type at this location.
suggested_stagestring · nullableAdvisory
cure_bystring (date-time) · nullableNext 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 · nullableThe drive it was found on.
ai_assistedbooleanAn 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

200Per-row outcomeobject
422Validation 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

200A 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

200OKViolation
404Not 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_idstringYour violation/case id.
stagestringStage you are at, e.g. "First violation notice".
cure_bystring (date-time)Next re-check date.
statusstring
One of: open resolved
resolutionstringe.g. "Fine paid, closed".

Responses

200UpdatedViolation
404Not 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
}