HOACraft integration guide
HOACraft is the field layer for HOA management companies. Inspectors drive the community and handle three kinds of field work from the phone:
- Violations: snap, match the house, cite the rule, approve, and re-check after the cure date.
- Work orders: report common-area and association-maintained issues with photos, priority and vendor.
- ACC requests: visit the site of an architectural application and record what they saw and a recommendation.
Your management system stays the system of record: it sends letters, tracks fines, pays vendors, decides ACC applications and runs the homeowner portal.
This guide is for the developers who connect the two.
Status: draft contract, version
2026-11-01.
- Already working: the webhook payloads and signature documented here. The HOACraft app produces them today, in demo mode, on the Integrations screen (⋯ → Integrations).
- Not built yet: the REST endpoints in
openapi.yamlare the planned server API. No server exists yet.
Communities & properties →
Your system pushes communities and properties so inspectors drive with the right map, and so every payload carries your own ids.
Violations →
Read violations HOACraft recorded (the pull alternative to webhooks).
Work orders →
Maintenance issues an inspector spots in the field, usually in common areas or where the association maintains the item.
ACC requests →
Architectural change requests.
Drives →
A drive is one inspector's pass through a community.
Webhooks & signing →
Headers, retries, every event type and a signature tester.
How data moves
Your management system HOACraft
─────────────────────── ────────
communities, properties ── PUT (import) ──► drive map, who lives where
open violations, stages ── PUT (sync) ──► "re-check due" on the drive
ACC applications ── PUT (push) ──► site visits on the drive
◄── webhooks ───── violation.created / .still_open / .resolved
◄── webhooks ───── work_order.created / .updated / .completed
◄── webhooks ───── acc_request.site_reviewed
◄── webhooks ───── drive.completed
work order status ── PATCH ──► inspector checks the work
ACC committee decision ── POST ──► request closed on the drive
letters, fines, portal (stay with you)
── GET (pull) ──► same data, if you prefer polling
Use whichever you can run:
| Option | Best for | What you build |
|---|---|---|
| Webhooks (recommended) | Teams with an HTTPS endpoint | One receiver that verifies the signature and upserts by id |
| Pull API | Teams that run scheduled jobs | GET /v1/violations, /work-orders and /acc-requests with updated_since=… every few minutes |
| CSV export | Teams without developers | Nothing. Download it from the app's Integrations screen and import the file |
Authentication
- API calls: each management company gets API keys, sent as
Authorization: Bearer <key>.hc_test_…keys work only against the sandbox (https://sandbox.api.hoacraft.com/v1), which holds fictional data.hc_live_…keys work against production.
- Webhooks: each endpoint has its own signing secret (
whsec_…). See "Verifying the signature" below.
Webhook events
Each event is one POST to your endpoint with a JSON body:
{
"id": "evt-…", // unique; retries reuse it, so dedupe on this
"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": { … }
}
| Type | When | data |
|---|---|---|
violation.created |
A manager or inspector approves a violation | violation |
violation.still_open |
A re-check after the cure date finds it unfixed. HOACraft restarts the cure clock; you decide the next letter or fine. | violation, recheck |
violation.resolved |
A re-check finds it fixed | violation, recheck |
work_order.created |
An inspector submits a work order (drafts stay on the phone) | work_order |
work_order.updated |
Its status or vendor changes | work_order, previous_status |
work_order.completed |
It is marked done, with completion notes and photos | work_order |
acc_request.site_reviewed |
An inspector records an ACC site review. It is a recommendation, never a decision. | acc_request, site_review |
acc_request.decided |
A manager records the committee decision in HOACraft (if you record it in your system instead, POST it to us) | acc_request |
drive.completed |
An inspector ends a drive | drive (stops, skipped stops with reasons, ids of violations created, re-check results) |
webhook.test |
You press "Send test event" | message |
Full examples, generated from the app's code and checked in CI: examples/.
The violation object includes:
- Location:
location.address,location.lot_number, andlocation.geo(where the property is). - Evidence: photo URLs with capture times, and rule citations (
document,section,title). - Escalation:
level(1 = first offence) andsuggested_stage, taken from the community's notice ladder. This is advice only; your system owns the real stage. - Cure date:
cure_by. - History: every re-check, and
resolved_at/resolutiononce it's closed.
Fields that may be null are listed in openapi.yaml. Unknown fields may be added within an API version, so ignore fields you don't use.
Responding
- Success: reply
2xxwithin 10 seconds. Do slow work after you reply. - Failure: any other response, or a timeout, is retried with backoff for up to 24 hours: 1 min, 5 min, 30 min, 2 h, 6 h, 12 h, 24 h.
- Events can arrive out of order. Use
created_atand the violation'sstatusrather than arrival order.
Verifying the signature
Every request carries:
HOACraft-Event: violation.created
HOACraft-Delivery: evt-…
HOACraft-Signature: t=1763049600,v1=5d41402abc4b2a76b9719d911017c592…
v1 is the hex HMAC-SHA256 of "<t>.<raw body>", keyed with your signing secret. To check it:
- Recompute
v1over the raw request body. Re-serialized JSON won't match. - Compare the two values in constant time.
- Reject the request if
tis more than 5 minutes from now.
Node.js:
const crypto = require('crypto');
function verify(secret, rawBody, header) {
const parts = Object.fromEntries(header.split(',').map(p => p.split('=')));
const age = Math.abs(Date.now() / 1000 - Number(parts.t));
if (!parts.t || !parts.v1 || age > 300) return false;
const mac = crypto.createHmac('sha256', secret)
.update(`${parts.t}.${rawBody}`).digest('hex');
return crypto.timingSafeEqual(Buffer.from(mac), Buffer.from(parts.v1));
}
C#:
using System.Security.Cryptography;
using System.Text;
static bool Verify(string secret, string rawBody, string header)
{
var parts = header.Split(',').Select(p => p.Split('=', 2))
.ToDictionary(p => p[0], p => p[1]);
if (!parts.TryGetValue("t", out var t) || !parts.TryGetValue("v1", out var v1)) return false;
if (Math.Abs(DateTimeOffset.UtcNow.ToUnixTimeSeconds() - long.Parse(t)) > 300) return false;
using var hmac = new HMACSHA256(Encoding.UTF8.GetBytes(secret));
var mac = Convert.ToHexString(hmac.ComputeHash(Encoding.UTF8.GetBytes($"{t}.{rawBody}"))).ToLowerInvariant();
return CryptographicOperations.FixedTimeEquals(Encoding.UTF8.GetBytes(mac), Encoding.UTF8.GetBytes(v1));
}
Keeping HOACraft in sync (import)
Inspectors need to know what's already open at each house: "re-check due", the current stage and the last letter. Push these from your system:
PUT /v1/communities/{id}: name, address, cure days and notice ladder.PUT /v1/communities/{id}/properties: a bulk upsert of up to 1,000 rows per call, keyed by yourexternal_id.PUT /v1/communities/{id}/open-violations: the violations you consider open, with the stage and cure date you set. Anything you leave out is treated as closed on your side.PATCH /v1/violations/{id}: after you send a letter, updatestageandcure_byso the next re-check lands on the right day. You can also close the violation (for example "paid fine, closed").PUT /v1/communities/{id}/acc-requests: ACC applications that need a site visit. They appear on the inspector's next open-items drive.POST /v1/acc-requests/{id}/decision: the committee's decision, once it's made.PATCH /v1/work-orders/{id}: if vendors are managed in your system, send status changes back so the inspector can check finished work.
Once properties are imported, every payload's location also carries your external_id, so you never have to match on addresses.
Versioning
- Within a version: fields may be added. Fields are never removed or renamed.
- Breaking changes: these ship as a new
api_version. Each endpoint is pinned to the version it was created with, until you upgrade it.