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

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:

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.yaml are the planned server API. No server exists yet.

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

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:

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

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:

  1. Recompute v1 over the raw request body. Re-serialized JSON won't match.
  2. Compare the two values in constant time.
  3. Reject the request if t is 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:

  1. PUT /v1/communities/{id}: name, address, cure days and notice ladder.
  2. PUT /v1/communities/{id}/properties: a bulk upsert of up to 1,000 rows per call, keyed by your external_id.
  3. 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.
  4. PATCH /v1/violations/{id}: after you send a letter, update stage and cure_by so the next re-check lands on the right day. You can also close the violation (for example "paid fine, closed").
  5. PUT /v1/communities/{id}/acc-requests: ACC applications that need a site visit. They appear on the inspector's next open-items drive.
  6. POST /v1/acc-requests/{id}/decision: the committee's decision, once it's made.
  7. 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