DEVELOPER PLATFORM

Build on hoa.to

hoa.to is the system of record for a community. The v1 REST API reads and writes units, owners, maintenance and ARC requests, ledgers, violations, documents and meetings, so you can sync both ways and automate workflows instead of being locked into a closed ecosystem.

28 operations, 12 of them writes. This page is generated from the same specification the API dispatches on, so what you read here is what the server implements.

REST API
Resource-oriented JSON over HTTPS.
OpenAPI 3.1
Import into Postman or generate a client.
Sandbox
A separate community with seeded data.
Webhooks
HMAC-signed event delivery.

Quickstart

  1. Sign in and open Console → Integrations → API keys. Tick Allow writes if your integration creates or updates anything, and Sandbox key to point at test data.
  2. Copy the key. It is shown once and stored only as a SHA-256 hash, so we cannot recover it for you.
  3. Call GET /api/v1/ping and check that write is true before trying a write.
  4. Register a webhook with POST /api/v1/webhooks and verify the signature on every delivery.
  5. Issue a live key when the integration behaves against the sandbox.

Authentication

Every request needs a bearer key. A key is bound to one community, and no key can reach another community’s data.

curl https://hoa.to/api/v1/ping \
  -H "Authorization: Bearer hoa_test_xxx"
Base URL and key types
Base URLhttps://hoa.to/api/v1
Live keyhoa_live_… writes to your real community.
Sandbox keyhoa_test_… writes to a separate sandbox community seeded with sample units, owners, charges, a meeting and an announcement. Same base URL.
Scopesread for every GET. write for POST, PATCH and DELETE. A read-only key gets 403 insufficient_scope.
Rate limits600 reads and 120 writes per key per 1 minute. Over the limit returns 429 with Retry-After.
PaginationList endpoints take limit (1–500, default 100) and return nextCursor. Pass it back as cursor. null means the last page.
Spec/api/v1/openapi.json is an OpenAPI 3.1 document you can import directly.

A note on what the API does not do

There is no partner OAuth flow yet: integrations authenticate with a community-issued API key. Webhook delivery is signed and its failures are recorded, but deliveries are not retried, so treat your endpoint as the source of truth and reconcile with a GET if you miss one.POST /payments records money already collected; it does not charge a card or debit a bank account.

API reference

Service

Check a key, discover the surface.

GET/pingread scope

Verify a key and read its scopes

Returns the association the key is bound to, the scopes it carries and whether it is a live or test key. Call this first: `write: true` tells you the key can perform POST and PATCH.

Request

curl -X GET https://hoa.to/api/v1/ping \
  -H "Authorization: Bearer hoa_test_xxx"

Response 200

{
  "ok": true,
  "association": {
    "id": "cly8x1p2q0001",
    "name": "Woodridge HOA",
    "slug": "woodridge",
    "region": "CO",
    "country": "US",
    "currency": "USD"
  },
  "mode": "test",
  "sandbox": true,
  "scopes": [
    "read",
    "write"
  ],
  "write": true,
  "at": "2026-11-05T19:52:04.167Z"
}
GET/read scope

List every resource this API exposes

A machine-readable index of the live surface, generated from the same spec that generates this page. Use it to confirm what a deployment actually supports.

Request

curl -X GET https://hoa.to/api/v1 \
  -H "Authorization: Bearer hoa_test_xxx"

Response 200

{
  "version": "v1",
  "baseUrl": "https://hoa.to/api/v1",
  "openapi": "https://hoa.to/api/v1/openapi.json",
  "operations": [
    {
      "method": "GET",
      "path": "units",
      "scope": "read",
      "summary": "List units"
    }
  ]
}

Units

The doors in the community. Everything else hangs off a unit.

GET/unitsread scope

List units

Every unit in the key's association, ordered by unit number.

Query parameters

FieldTypeDescription
limitintegerMaximum rows to return, 1 to 500. Defaults to 100.
cursorstringOpaque id from a previous response's `nextCursor`. Omit for the first page.

Request

curl -X GET https://hoa.to/api/v1/units \
  -H "Authorization: Bearer hoa_test_xxx"

Response 200

{
  "data": [
    {
      "id": "cly8x2a1b0003",
      "unitNumber": "101",
      "type": "condo-unit",
      "status": "active",
      "address": {
        "line1": "101 Pine St",
        "city": "Denver",
        "region": "CO",
        "postal": "80202"
      },
      "lotNumber": null,
      "bedrooms": 2,
      "sqft": 1100,
      "votingInterest": 1
    }
  ],
  "nextCursor": null
}
GET/units/:idread scope

Retrieve one unit

Fetch a single unit by id, including its current owners.

Path parameters

FieldTypeDescription
idrequiredstringThe unit's id, or its unit number.

Request

curl -X GET https://hoa.to/api/v1/units/ID \
  -H "Authorization: Bearer hoa_test_xxx"

Response 200

{
  "data": {
    "id": "cly8x2a1b0003",
    "unitNumber": "101",
    "type": "condo-unit",
    "status": "active",
    "address": {
      "line1": "101 Pine St",
      "city": "Denver",
      "region": "CO",
      "postal": "80202"
    },
    "owners": [
      {
        "userId": "cly8x3c2d0005",
        "name": "Dana Rivera",
        "email": "dana@example.com",
        "relation": "OWNER",
        "primary": true
      }
    ]
  }
}
POST/unitswrite scope

Create a unit

Adds a unit. `unitNumber` must be unique inside the association; a duplicate returns 409.

Body

FieldTypeDescription
unitNumberrequiredstringUnique identifier for the door, as owners know it.
addressobjectStreet address. Keys: line1, line2, city, region, postal, country.
typestringFree-form unit type.single-family · townhome · condo-unit · lot · commercial
lotNumberstringPlat or lot reference, when different from the unit number.
bedroomsintegerBedroom count.
sqftintegerInterior area in square feet.
votingInterestnumberVote weight for this unit. Defaults to 1.
assessmentPctnumberShare of the budget this unit carries, as a percentage.
statusstringDefaults to active.active · inactive

Request

curl -X POST https://hoa.to/api/v1/units \
  -H "Authorization: Bearer hoa_test_xxx" \
  -H "Content-Type: application/json" \
  -d '{"unitNumber":"101","address":{"line1":"101 Pine St","city":"Denver","region":"CO","postal":"80202"},"type":"condo-unit","lotNumber":"L-14","bedrooms":2,"sqft":1100}'

Response 201

{
  "data": {
    "id": "cly8x2a1b0003",
    "unitNumber": "101",
    "type": "condo-unit",
    "status": "active",
    "address": {
      "line1": "101 Pine St",
      "city": "Denver",
      "region": "CO",
      "postal": "80202"
    }
  }
}
PATCH/units/:idwrite scope

Update a unit

Updates only the fields you send. Omitted fields are left alone.

Path parameters

FieldTypeDescription
idrequiredstringThe unit's id, or its unit number.

Body

FieldTypeDescription
unitNumberstringNew unit number. Must stay unique.
addressobjectReplaces the whole address object.
typestringUnit type.
lotNumberstringPlat or lot reference.
bedroomsintegerBedroom count.
sqftintegerInterior area in square feet.
votingInterestnumberVote weight.
assessmentPctnumberBudget share, as a percentage.
statusstringactive or inactive.active · inactive

Request

curl -X PATCH https://hoa.to/api/v1/units/ID \
  -H "Authorization: Bearer hoa_test_xxx" \
  -H "Content-Type: application/json" \
  -d '{"unitNumber":"101A","address":{"line1":"101 Pine St","city":"Denver","region":"CO","postal":"80202"},"type":"townhome","lotNumber":"L-14","bedrooms":3,"sqft":1250}'

Response 200

{
  "data": {
    "id": "cly8x2a1b0003",
    "unitNumber": "101A",
    "type": "townhome",
    "status": "active",
    "address": {
      "line1": "101 Pine St",
      "city": "Denver",
      "region": "CO",
      "postal": "80202"
    }
  }
}

Owners

People attached to a unit: owners, co-owners, tenants, occupants.

GET/ownersread scope

List owners and residents

Current ownerships (those with no end date) across the association. Pass `unit` to filter to one door, or `includeEnded=true` to see history.

Query parameters

FieldTypeDescription
unitstringFilter to one unit number.
includeEndedbooleanInclude past owners. Defaults to false.
limitintegerMaximum rows to return, 1 to 500. Defaults to 100.
cursorstringOpaque id from a previous response's `nextCursor`. Omit for the first page.

Request

curl -X GET https://hoa.to/api/v1/owners \
  -H "Authorization: Bearer hoa_test_xxx"

Response 200

{
  "data": [
    {
      "id": "cly8x4d3e0007",
      "userId": "cly8x3c2d0005",
      "name": "Dana Rivera",
      "firstName": "Dana",
      "lastName": "Rivera",
      "email": "dana@example.com",
      "phone": "+13035550101",
      "unit": "101",
      "unitId": "cly8x2a1b0003",
      "relation": "OWNER",
      "primary": true,
      "startDate": "2026-01-15T00:00:00.000Z",
      "endDate": null
    }
  ],
  "nextCursor": null
}
POST/ownerswrite scope

Attach an owner or resident to a unit

Links a person to a unit. Matching is by email: an existing account is reused, otherwise one is created without a password (they set one through the normal invite or reset flow, so creating an owner here never sends a credential). Re-posting the same email and unit returns the existing ownership rather than duplicating it.

Body

FieldTypeDescription
unitrequiredstringUnit number, or pass `unitId` instead.
unitIdstringUnit id, as an alternative to `unit`.
emailrequiredstringThe person's email. Used as the identity key.
firstNamestringGiven name.
lastNamestringFamily name.
phonestringPhone in E.164 form.
relationstringDefaults to OWNER.OWNER · CO_OWNER · TENANT · OCCUPANT · PROPERTY_MANAGER
primarybooleanMark as the primary contact for the unit.
startDatestringISO date the ownership began. Defaults to now.
notesstringManager-only note about this person on this unit.

Request

curl -X POST https://hoa.to/api/v1/owners \
  -H "Authorization: Bearer hoa_test_xxx" \
  -H "Content-Type: application/json" \
  -d '{"unit":"101","unitId":"cly8x2a1b0003","email":"dana@example.com","firstName":"Dana","lastName":"Rivera","phone":"+13035550101"}'

Response 201

{
  "data": {
    "id": "cly8x4d3e0007",
    "userId": "cly8x3c2d0005",
    "name": "Dana Rivera",
    "email": "dana@example.com",
    "unit": "101",
    "relation": "OWNER",
    "primary": true,
    "startDate": "2026-01-15T00:00:00.000Z",
    "endDate": null
  }
}
PATCH/owners/:idwrite scope

Update or end an ownership

Updates the ownership row, not the person. Set `endDate` to record a move-out or sale: history is kept, the row is never deleted. Sending `endDate` emits `owner.moved_out`.

Path parameters

FieldTypeDescription
idrequiredstringThe ownership id returned by GET /owners.

Body

FieldTypeDescription
relationstringChange the relation.OWNER · CO_OWNER · TENANT · OCCUPANT · PROPERTY_MANAGER
primarybooleanMake this the primary contact.
endDatestringISO date the ownership ended. Ends the ownership.
endReasonstringWhy it ended.sold · removed · moved_out · correction
notesstringManager-only note.

Request

curl -X PATCH https://hoa.to/api/v1/owners/ID \
  -H "Authorization: Bearer hoa_test_xxx" \
  -H "Content-Type: application/json" \
  -d '{"relation":"TENANT","primary":false,"endDate":"2026-11-01","endReason":"sold","notes":"Sold to the Rivera family"}'

Response 200

{
  "data": {
    "id": "cly8x4d3e0007",
    "userId": "cly8x3c2d0005",
    "unit": "101",
    "relation": "OWNER",
    "primary": true,
    "endDate": "2026-11-01T00:00:00.000Z",
    "endReason": "sold"
  }
}

Requests

Maintenance work orders and architectural (ARC) review requests, in one resource.

GET/requestsread scope

List maintenance and ARC requests

Returns both kinds in one feed, each tagged with `kind`. Filter with `kind=maintenance` or `kind=arc`, and with `status`. Statuses differ by kind: maintenance uses NEW, ASSIGNED, SCHEDULED, IN_PROGRESS, ON_HOLD, COMPLETED, CANCELLED; ARC uses DRAFT, SUBMITTED, UNDER_REVIEW, MORE_INFO, APPROVED, DENIED, WITHDRAWN.

Query parameters

FieldTypeDescription
kindstringLimit to one kind.maintenance · arc
statusstringFilter by status. Case-insensitive.
unitstringFilter to one unit number.
openbooleanOnly requests that are not finished (not COMPLETED, CANCELLED, APPROVED, DENIED or WITHDRAWN).
limitintegerMaximum rows to return, 1 to 500. Defaults to 100.
cursorstringOpaque id from a previous response's `nextCursor`. Omit for the first page.

Request

curl -X GET https://hoa.to/api/v1/requests \
  -H "Authorization: Bearer hoa_test_xxx"

Response 200

{
  "data": [
    {
      "id": "cly8x5e4f0009",
      "kind": "maintenance",
      "title": "Garage door will not close",
      "description": "Sensor seems misaligned.",
      "status": "NEW",
      "priority": "normal",
      "category": "doors",
      "unit": "101",
      "unitId": "cly8x2a1b0003",
      "photos": [],
      "scheduledFor": null,
      "completedAt": null,
      "createdAt": "2026-11-05T18:00:00.000Z"
    },
    {
      "id": "cly8x6f5g000b",
      "kind": "arc",
      "title": "Repaint front door",
      "description": "Changing to slate grey.",
      "status": "SUBMITTED",
      "category": "paint",
      "unit": "102",
      "unitId": "cly8x2a1b0004",
      "photos": [],
      "dueBy": "2026-12-05T00:00:00.000Z",
      "decisionNote": null,
      "createdAt": "2026-11-05T18:05:00.000Z"
    }
  ],
  "nextCursor": null
}
GET/requests/:idread scope

Retrieve one request

Fetch a single request of either kind, with its update timeline.

Path parameters

FieldTypeDescription
idrequiredstringThe request id.

Request

curl -X GET https://hoa.to/api/v1/requests/ID \
  -H "Authorization: Bearer hoa_test_xxx"

Response 200

{
  "data": {
    "id": "cly8x5e4f0009",
    "kind": "maintenance",
    "title": "Garage door will not close",
    "status": "NEW",
    "unit": "101",
    "updates": [
      {
        "id": "cly8x7g6h000d",
        "status": "NEW",
        "note": "Logged via API",
        "authorName": "Integration",
        "ownerVisible": true,
        "createdAt": "2026-11-05T18:00:00.000Z"
      }
    ]
  }
}
POST/requestswrite scope

Create a maintenance or ARC request

Set `kind` to choose. `maintenance` creates a work order and emits `request.created`; `arc` creates an architectural review request and emits `arc.submitted`. A unit is required for ARC and optional for maintenance (common-area work has no unit).

Body

FieldTypeDescription
kindrequiredstringWhich kind of request to create.maintenance · arc
titlerequiredstringShort summary.
descriptionstringDetail. Required for ARC requests.
unitstringUnit number. Required when kind is arc.
unitIdstringUnit id, as an alternative to `unit`.
categorystringFree-form category, e.g. plumbing, paint, fence.
prioritystringMaintenance only. Defaults to normal.low · normal · high · urgent
statusstringInitial status. Defaults to NEW for maintenance and SUBMITTED for ARC.
photosstring[]Image URLs.
requestedByEmailstringEmail of the owner this is on behalf of. Matched to an existing account; never creates one.
scheduledForstringMaintenance only. ISO timestamp of the planned visit.
dueBystringARC only. ISO date a decision is due.
notestringFirst entry on the request's timeline.

Request

curl -X POST https://hoa.to/api/v1/requests \
  -H "Authorization: Bearer hoa_test_xxx" \
  -H "Content-Type: application/json" \
  -d '{"kind":"maintenance","title":"Garage door will not close","description":"Sensor seems misaligned.","unit":"101","unitId":"cly8x2a1b0003","category":"doors"}'

Response 201

{
  "data": {
    "id": "cly8x5e4f0009",
    "kind": "maintenance",
    "title": "Garage door will not close",
    "status": "NEW",
    "priority": "normal",
    "unit": "101",
    "createdAt": "2026-11-05T18:00:00.000Z"
  }
}
PATCH/requests/:idwrite scope

Update a request

Change status or detail on either kind. A status change emits `request.updated` for maintenance and `arc.decided` for an ARC request that reaches APPROVED or DENIED. Pass `note` to add a timeline entry explaining the change.

Path parameters

FieldTypeDescription
idrequiredstringThe request id.

Body

FieldTypeDescription
statusstringNew status, valid for the request's kind.
titlestringNew title.
descriptionstringNew description.
categorystringNew category.
prioritystringMaintenance only.low · normal · high · urgent
photosstring[]Replaces the photo list.
scheduledForstringMaintenance only. ISO timestamp.
completedAtstringMaintenance only. ISO timestamp.
costnumberMaintenance only. Final cost.
decisionNotestringARC only. The board's reasoning.
dueBystringARC only. ISO date.
notestringTimeline entry describing this change.
ownerVisiblebooleanWhether `note` is shown to the owner. Defaults to true.

Request

curl -X PATCH https://hoa.to/api/v1/requests/ID \
  -H "Authorization: Bearer hoa_test_xxx" \
  -H "Content-Type: application/json" \
  -d '{"status":"IN_PROGRESS","title":"Garage door sensor","description":"Technician booked.","category":"doors","priority":"high","photos":["https://example.com/door.jpg"]}'

Response 200

{
  "data": {
    "id": "cly8x5e4f0009",
    "kind": "maintenance",
    "status": "IN_PROGRESS",
    "scheduledFor": "2026-11-12T15:00:00.000Z"
  }
}

Money

Charges, payments and a unit's ledger.

GET/chargesread scope

List charges

Assessments, fines and other charges. `status=open` returns OPEN and PARTIAL together, which is what you want for a collections report.

Query parameters

FieldTypeDescription
statusstring`open` for OPEN and PARTIAL, or an exact status.open · OPEN · PARTIAL · PAID · VOID · WRITTEN_OFF
unitstringFilter to one unit number.
limitintegerMaximum rows to return, 1 to 500. Defaults to 100.
cursorstringOpaque id from a previous response's `nextCursor`. Omit for the first page.

Request

curl -X GET https://hoa.to/api/v1/charges \
  -H "Authorization: Bearer hoa_test_xxx"

Response 200

{
  "data": [
    {
      "id": "cly8x8h7i000f",
      "description": "November assessment",
      "amount": 325,
      "balance": 325,
      "dueDate": "2026-11-01T00:00:00.000Z",
      "status": "OPEN",
      "unit": "101",
      "unitId": "cly8x2a1b0003"
    }
  ],
  "nextCursor": null
}
GET/paymentsread scope

List payments

Payments recorded against the association, newest first.

Query parameters

FieldTypeDescription
limitintegerMaximum rows to return, 1 to 500. Defaults to 100.
cursorstringOpaque id from a previous response's `nextCursor`. Omit for the first page.

Request

curl -X GET https://hoa.to/api/v1/payments \
  -H "Authorization: Bearer hoa_test_xxx"

Response 200

{
  "data": [
    {
      "id": "cly8x9i8j000h",
      "amount": 325,
      "currency": "USD",
      "method": "api",
      "provider": "api",
      "status": "SUCCEEDED",
      "receivedAt": "2026-11-05T18:10:00.000Z"
    }
  ],
  "nextCursor": null
}
POST/paymentswrite scope

Record a payment

Records a payment already collected elsewhere and applies it to the unit's open charges, oldest first. This does not move money: it will not charge a card or debit a bank account. Emits `payment.received`.

Body

FieldTypeDescription
unitNumberrequiredstringThe unit the payment is for.
amountrequirednumberAmount in the association's currency. Must be greater than zero.
methodstringHow it was collected. Defaults to api.
referencestringYour own reference, e.g. a cheque number.
receivedAtstringISO timestamp the money arrived. Defaults to now.

Request

curl -X POST https://hoa.to/api/v1/payments \
  -H "Authorization: Bearer hoa_test_xxx" \
  -H "Content-Type: application/json" \
  -d '{"unitNumber":"101","amount":325,"method":"check","reference":"chk-10432","receivedAt":"2026-11-05T18:10:00Z"}'

Response 201

{
  "data": {
    "id": "cly8x9i8j000h",
    "amount": 325,
    "currency": "USD",
    "status": "SUCCEEDED",
    "unit": "101",
    "receivedAt": "2026-11-05T18:10:00.000Z"
  }
}
GET/ledger/:unitread scope

Pull a unit's ledger and balance

Every charge and payment for one unit as a dated ledger with a running balance, plus the current outstanding total. Charges are debits, payments are credits.

Path parameters

FieldTypeDescription
unitrequiredstringThe unit number, or the unit's id.

Query parameters

FieldTypeDescription
fromstringISO date. Only entries on or after this date.
tostringISO date. Only entries on or before this date.
limitintegerMaximum rows to return, 1 to 500. Defaults to 100.

Request

curl -X GET https://hoa.to/api/v1/ledger/101 \
  -H "Authorization: Bearer hoa_test_xxx"

Response 200

{
  "data": {
    "unit": "101",
    "unitId": "cly8x2a1b0003",
    "currency": "USD",
    "balance": 0,
    "entries": [
      {
        "date": "2026-11-01T00:00:00.000Z",
        "type": "charge",
        "id": "cly8x8h7i000f",
        "description": "November assessment",
        "debit": 325,
        "credit": 0,
        "runningBalance": 325
      },
      {
        "date": "2026-11-05T18:10:00.000Z",
        "type": "payment",
        "id": "cly8x9i8j000h",
        "description": "Payment, api",
        "debit": 0,
        "credit": 325,
        "runningBalance": 0
      }
    ]
  }
}

Compliance

Violations and the documents behind them.

GET/violationsread scope

List violations

Open and historical violations, newest first.

Query parameters

FieldTypeDescription
statusstringFilter by status.OPEN · IN_PROGRESS · CURED · FINED · HEARING · CLOSED · DISMISSED
unitstringFilter to one unit number.
limitintegerMaximum rows to return, 1 to 500. Defaults to 100.
cursorstringOpaque id from a previous response's `nextCursor`. Omit for the first page.

Request

curl -X GET https://hoa.to/api/v1/violations \
  -H "Authorization: Bearer hoa_test_xxx"

Response 200

{
  "data": [
    {
      "id": "cly8xaj9k000j",
      "description": "Trash bins left at the kerb",
      "status": "OPEN",
      "stage": "courtesy",
      "unit": "101",
      "unitId": "cly8x2a1b0003",
      "photos": [],
      "observedAt": "2026-11-04T00:00:00.000Z",
      "dueDate": "2026-11-18T00:00:00.000Z",
      "fineAmount": null,
      "createdAt": "2026-11-04T12:00:00.000Z"
    }
  ],
  "nextCursor": null
}
POST/violationswrite scope

File a violation with photos

Records a violation against a unit and emits `violation.created`. Filing a violation does not send a notice or post a fine on its own.

Body

FieldTypeDescription
unitrequiredstringUnit number, or pass `unitId`.
unitIdstringUnit id, as an alternative to `unit`.
descriptionrequiredstringWhat was observed.
photosstring[]Image URLs.
stagestringEnforcement stage. Defaults to courtesy.
statusstringDefaults to OPEN.OPEN · IN_PROGRESS · CURED · FINED · HEARING · CLOSED · DISMISSED
observedAtstringISO timestamp it was seen. Defaults to now.
dueDatestringISO date the owner must cure by.
fineAmountnumberFine recorded on the violation. This is not posted to the owner's ledger.

Request

curl -X POST https://hoa.to/api/v1/violations \
  -H "Authorization: Bearer hoa_test_xxx" \
  -H "Content-Type: application/json" \
  -d '{"unit":"101","unitId":"cly8x2a1b0003","description":"Trash bins left at the kerb","photos":["https://example.com/bins.jpg"],"stage":"courtesy","status":"OPEN"}'

Response 201

{
  "data": {
    "id": "cly8xaj9k000j",
    "description": "Trash bins left at the kerb",
    "status": "OPEN",
    "stage": "courtesy",
    "unit": "101",
    "observedAt": "2026-11-04T00:00:00.000Z"
  }
}
GET/documentsread scope

List documents

Documents published to the community. `url` is relative to the site root unless it is already absolute.

Query parameters

FieldTypeDescription
categorystringFilter by category.governing · financial · meeting · insurance · resale
limitintegerMaximum rows to return, 1 to 500. Defaults to 100.
cursorstringOpaque id from a previous response's `nextCursor`. Omit for the first page.

Request

curl -X GET https://hoa.to/api/v1/documents \
  -H "Authorization: Bearer hoa_test_xxx"

Response 200

{
  "data": [
    {
      "id": "cly8xbk0l000l",
      "name": "Bylaws, amended 2026",
      "category": "governing",
      "url": "/api/files/cly8xck1m000n",
      "mime": "application/pdf",
      "sizeBytes": 482113,
      "visibility": "members",
      "version": 2,
      "createdAt": "2026-10-01T00:00:00.000Z"
    }
  ],
  "nextCursor": null
}
POST/documentswrite scope

Publish a document

Registers a document the community can see and emits `document.published`. This takes a URL you already host; it does not accept a file upload. Upload binaries through the console instead.

Body

FieldTypeDescription
namerequiredstringTitle shown to owners.
urlrequiredstringWhere the file lives. Must be http(s) or a site-relative path.
categorystringGrouping in the console.governing · financial · meeting · insurance · resale
mimestringContent type.
sizeBytesintegerFile size.
visibilitystringWho can see it. Defaults to members.public · members · board · admin
versionintegerVersion number. Defaults to 1.

Request

curl -X POST https://hoa.to/api/v1/documents \
  -H "Authorization: Bearer hoa_test_xxx" \
  -H "Content-Type: application/json" \
  -d '{"name":"Bylaws, amended 2026","url":"https://example.com/bylaws.pdf","category":"governing","mime":"application/pdf","sizeBytes":482113,"visibility":"members"}'

Response 201

{
  "data": {
    "id": "cly8xbk0l000l",
    "name": "Bylaws, amended 2026",
    "category": "governing",
    "url": "https://example.com/bylaws.pdf",
    "visibility": "members",
    "version": 2,
    "createdAt": "2026-10-01T00:00:00.000Z"
  }
}

Governance

Meetings, minutes and announcements.

GET/meetingsread scope

List meetings and minutes

Meetings with their agenda, minutes and motions. Newest first by default.

Query parameters

FieldTypeDescription
typestringFilter by meeting type.board · annual · special · committee
upcomingbooleanOnly meetings that start in the future, oldest first.
limitintegerMaximum rows to return, 1 to 500. Defaults to 100.
cursorstringOpaque id from a previous response's `nextCursor`. Omit for the first page.

Request

curl -X GET https://hoa.to/api/v1/meetings \
  -H "Authorization: Bearer hoa_test_xxx"

Response 200

{
  "data": [
    {
      "id": "cly8xdl2n000p",
      "title": "November board meeting",
      "type": "board",
      "startsAt": "2026-11-20T01:00:00.000Z",
      "location": "Clubhouse",
      "virtualUrl": null,
      "agenda": [
        "Approve minutes",
        "Reserve study"
      ],
      "minutes": null,
      "minutesStatus": "draft",
      "quorum": 3,
      "motions": [],
      "createdAt": "2026-11-01T00:00:00.000Z"
    }
  ],
  "nextCursor": null
}
GET/meetings/:idread scope

Retrieve one meeting

A single meeting with its full minutes and every motion and vote count.

Path parameters

FieldTypeDescription
idrequiredstringThe meeting id.

Request

curl -X GET https://hoa.to/api/v1/meetings/ID \
  -H "Authorization: Bearer hoa_test_xxx"

Response 200

{
  "data": {
    "id": "cly8xdl2n000p",
    "title": "November board meeting",
    "type": "board",
    "startsAt": "2026-11-20T01:00:00.000Z",
    "minutes": "The meeting was called to order at 6.02pm.",
    "minutesStatus": "approved",
    "motions": [
      {
        "id": "cly8xem3o000r",
        "text": "Approve the reserve study proposal",
        "result": "passed",
        "votesFor": 4,
        "votesAgainst": 1,
        "votesAbstain": 0
      }
    ]
  }
}
POST/meetingswrite scope

Schedule a meeting

Creates a meeting and emits `meeting.scheduled`. Scheduling through the API does not send a notice to owners; statutory notice periods are your responsibility.

Body

FieldTypeDescription
titlerequiredstringMeeting title.
startsAtrequiredstringISO timestamp the meeting starts.
typestringDefaults to board.board · annual · special · committee
locationstringPhysical location.
virtualUrlstringVideo call link.
agendaarrayAgenda items, in order.
quorumintegerDirectors needed for a quorum.

Request

curl -X POST https://hoa.to/api/v1/meetings \
  -H "Authorization: Bearer hoa_test_xxx" \
  -H "Content-Type: application/json" \
  -d '{"title":"November board meeting","startsAt":"2026-11-20T01:00:00Z","type":"board","location":"Clubhouse","virtualUrl":"https://meet.example.com/abc","agenda":["Approve minutes","Reserve study"]}'

Response 201

{
  "data": {
    "id": "cly8xdl2n000p",
    "title": "November board meeting",
    "type": "board",
    "startsAt": "2026-11-20T01:00:00.000Z",
    "location": "Clubhouse",
    "minutesStatus": "draft",
    "createdAt": "2026-11-01T00:00:00.000Z"
  }
}
GET/announcementsread scope

List published announcements

Announcements that have been published, pinned ones first. Drafts are not returned.

Query parameters

FieldTypeDescription
limitintegerMaximum rows to return, 1 to 500. Defaults to 100.
cursorstringOpaque id from a previous response's `nextCursor`. Omit for the first page.

Request

curl -X GET https://hoa.to/api/v1/announcements \
  -H "Authorization: Bearer hoa_test_xxx"

Response 200

{
  "data": [
    {
      "id": "cly8xfn4p000t",
      "title": "Pool closed Monday",
      "body": "Resurfacing runs all day.",
      "pinned": true,
      "publishedAt": "2026-11-02T00:00:00.000Z"
    }
  ],
  "nextCursor": null
}

Webhooks

Outbound event delivery, signed with HMAC SHA-256.

GET/webhooksread scope

List webhook endpoints

Your registered endpoints and their recent delivery health. Signing secrets are never returned after creation.

Request

curl -X GET https://hoa.to/api/v1/webhooks \
  -H "Authorization: Bearer hoa_test_xxx"

Response 200

{
  "data": [
    {
      "id": "cly8xgo5q000v",
      "url": "https://example.com/hooks/hoa",
      "events": [
        "payment.received",
        "request.created"
      ],
      "description": "Ops pipeline",
      "enabled": true,
      "lastStatus": "ok",
      "lastDeliveryAt": "2026-11-05T18:11:00.000Z",
      "failureCount": 0,
      "createdAt": "2026-11-01T00:00:00.000Z"
    }
  ]
}
POST/webhookswrite scope

Register an outbound webhook endpoint

Registers a URL to receive events. The response contains the signing secret exactly once, so store it. Each delivery carries `X-HoaTo-Event` and `X-HoaTo-Signature: sha256=<hex>`, the HMAC of the raw request body using that secret.

Body

FieldTypeDescription
urlrequiredstringHTTPS endpoint to POST to.
eventsstring[]Event names to subscribe to, or ["*"] for all. Defaults to all.
descriptionstringLabel for the console.
enabledbooleanDefaults to true.

Request

curl -X POST https://hoa.to/api/v1/webhooks \
  -H "Authorization: Bearer hoa_test_xxx" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/hooks/hoa","events":["payment.received","request.created"],"description":"Ops pipeline","enabled":true}'

Response 201

{
  "data": {
    "id": "cly8xgo5q000v",
    "url": "https://example.com/hooks/hoa",
    "events": [
      "payment.received",
      "request.created"
    ],
    "enabled": true,
    "secret": "whsec_8f2c...",
    "createdAt": "2026-11-01T00:00:00.000Z"
  }
}
DELETE/webhooks/:idwrite scope

Remove a webhook endpoint

Deletes the endpoint and stops delivery. This is the only DELETE in the API; domain records are ended or voided, never deleted.

Path parameters

FieldTypeDescription
idrequiredstringThe endpoint id.

Request

curl -X DELETE https://hoa.to/api/v1/webhooks/ID \
  -H "Authorization: Bearer hoa_test_xxx"

Response 200

{
  "data": {
    "id": "cly8xgo5q000v",
    "deleted": true
  }
}

Errors

Every error returns the same envelope: a human-readable error, a stable code you can branch on, and a docs link.

{
  "error": "This key is read-only. Create a key with read and write scope in the console under Integrations, API keys, then retry.",
  "code": "insufficient_scope",
  "docs": "https://hoa.to/developers",
  "required": "write",
  "granted": [
    "read"
  ]
}
StatusCodeWhat it means
400invalid_requestA required field is missing, or a value is the wrong type or not an allowed value. The message names the field.
401unauthorizedThe Authorization header is missing, malformed, or the key is unknown or revoked.
403insufficient_scopeThe key is valid but read-only. Create a key with read and write scope in Console, Integrations, API keys.
404not_foundNo such resource on this API, or the record does not exist in the key's association.
405method_not_allowedThe resource exists but does not support that HTTP method. The `allowed` field lists the ones it does.
409conflictThe write would duplicate something unique, such as a unit number already in use.
429rate_limitedToo many requests. Back off for the number of seconds in `Retry-After`.
500server_errorSomething failed on our side. Safe to retry with the same body.

Webhooks

Register an endpoint with POST /api/v1/webhooks. The signing secret is returned once. Each delivery carries X-HoaTo-Event and X-HoaTo-Signature: sha256=<hex>, an HMAC-SHA256 of the raw request body using that secret. Compare with a constant-time function.

// Node, verifying a delivery
const expected = "sha256=" + crypto
  .createHmac("sha256", process.env.HOA_WEBHOOK_SECRET)
  .update(rawBody)            // the raw bytes, before JSON.parse
  .digest("hex");
const ok = crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(req.headers["x-hoato-signature"]));
EventFires when
owner.createdAn owner or resident is attached to a unit.
owner.moved_outAn ownership is given an end date.
payment.receivedA payment is recorded and applied.
payment.failedA payment attempt fails.
charge.postedA charge is posted to a unit.
assessment.postedAn assessment run posts charges.
request.createdA maintenance request is created.
request.updatedA maintenance request changes status or detail.
violation.createdA violation is filed.
violation.escalatedA violation moves to a later enforcement stage.
arc.submittedAn architectural request is submitted.
arc.decidedAn architectural request is approved or denied.
document.publishedA document is published to the community.
signature.completedEvery signer has signed a document.
meeting.scheduledA meeting is created.
election.closedAn election closes and results are final.
vendor.addedA vendor is linked to the association.
bill.approvedA bill is approved for payment.

No-code with Zapier

Not a developer? Connect hoa.to to thousands of apps with Zapier, turning “new payment,” “new violation” or “resident moved out” into any action, no engineering required.

Open the Integration Hub →

Frequently asked questions

Why does my key get 403 on a POST?

The key is read-only. Scopes are chosen when the key is created: open Console, Integrations, API keys, tick Allow writes and create a new key. Keys cannot be upgraded in place, because only the hash is stored. Call GET /api/v1/ping to see what a key holds: it returns write: true when the key can write.

How do I get a sandbox?

In Console, Integrations, API keys, tick Sandbox key when you create one. That creates a separate sandbox community in your organization, seeded with three units, three owners, open charges, a meeting and an announcement, and binds the key to it. The base URL is the same. A Reset sandbox button returns it to the seeded state.

Is the sandbox separate from live community data?

Yes. A sandbox key is bound to a different association row, so every read and write is scoped away from your real records. Seed owners use addresses on a reserved, non-routable domain and have no password, so they can never be signed in to or emailed.

Do I need to be a developer to connect hoa.to to another tool?

No. The Zapier connector covers common triggers and actions without writing code. The REST API and webhooks are for custom integrations.

How are webhook payloads secured?

Each payload is signed with HMAC-SHA256 using your endpoint's secret and delivered in the X-HoaTo-Signature header, so your endpoint can verify it came from hoa.to. Verify against the raw body, before parsing.

Are failed webhook deliveries retried?

Not currently. A failure is recorded against the endpoint with a failure count you can see in the Integration Hub, but it is not re-sent. Build your integration to reconcile with a GET rather than relying on every delivery arriving.

Can I delete records through the API?

Only webhook endpoints. Domain records are ended or voided rather than deleted, so history survives: set endDate on an ownership to record a move-out, or move a request to CANCELLED.

Is there an OAuth flow for partner apps?

Not yet. Integrations authenticate with an API key issued by the community, which is scoped to that one community. If you are building a product that needs to serve many communities, write to support@hoa.to and we will talk about what you need.