REST API Reference

Base URL & authentication

• Base path: {host}/api/havho/v1.
• Every request needs an X-API-Key header. Keys are issued in the admin under Settings → API → HAVHO REST API, or via the HAVHO_V1_KEYS environment variable.
• A missing or unrecognised key returns 401 unauthorized with a WWW-Authenticate: X-API-Key header.
• Every response — success or error — carries an X-Correlation-Id header and a generatedAt field (server time, ISO-8601 UTC). Quote the correlation id when reporting a problem. Responses are never cached (Cache-Control: no-store).

Errors

Every error is JSON, with the same envelope:

{
  "error": {
    "code": "not_found",
    "message": "No property with externalListingId 'NOPE'",
    "correlationId": "req_uw5cyixy2yx1g1lztop9"
  }
}

Rate limits

Every response carries X-RateLimit-Limit and X-RateLimit-Remaining headers — these two are the number that actually governs you, currently 60 requests per minute per caller (IP-based), enforced ahead of this API by the application's shared HTTP layer.

Pagination

List endpoints (properties, agents, agencies, property-deletions) share one cursor scheme:

"pagination": {
  "limit": 50,
  "count": 50,
  "hasMore": true,
  "nextCursor": "eyJhZnRlciI6NTd9"
}

count is how many records are in this page, not a total — for the total, use activePropertyCount from sync status. Keep paging while hasMore is true; a cursor is stable only within one sweep (results can shift between separate sweeps as the catalogue changes).

Incremental retrieval

Add ?updated_since= (ISO-8601 UTC) to any list endpoint to get only records changed at or after that time:

• properties, agents, agencies compare against each record's sourceUpdatedAt.
• property-deletions compares against deletedAt.
• The value you sent is echoed back as updatedSince on every page.
• On the last page of a sweep (pagination.hasMore = false) the response also carries nextUpdatedSince — the newest timestamp seen. Store it and send it as updated_since on your next sweep; it is null on earlier pages. The comparison is inclusive, so the newest record repeats once at the start of the next sweep — upsert by id, which is always safe.

Endpoints

GET /properties

Active listings only. Paginated, supports updated_since.

{
  "data": [
    {
      "externalListingId": "CPT-S-1842",
      "externalAgentId": "AGT-1049",
      "externalAgencyId": "AGY-77",
      "providerId": "havho-sandbox",
      "sourceUpdatedAt": "2026-08-31T09:12:00Z",
      "status": "active",
      "type": "sale",
      "propertyType": "apartment",
      "title": "Sea-facing apartment in Green Point",
      "price": 4250000,
      "description": "Renovated two-bedroom apartment with open-plan living areas and sea views.",
      "address": "14 Ocean View Drive, Green Point, Cape Town, Western Cape",
      "suburb": "Green Point",
      "city": "Cape Town",
      "province": "Western Cape",
      "beds": 2,
      "baths": 2,
      "garage": 1,
      "parking": 1,
      "unitSize": 98,
      "photoUrls": [ "https://cdn.example.com/listing/1842/image1.jpg" ],
      "features": [ "Pool", "Security Estate" ],
      "agency": {
        "id": "AGY-77",
        "name": "Atlantic Edge Properties",
        "providerId": "havho-sandbox",
        "sourceUpdatedAt": "2026-08-31T09:12:00Z"
      },
      "agent": {
        "id": "AGT-1049",
        "providerId": "havho-sandbox",
        "fullName": "Naledi Mokoena",
        "email": "naledi.mokoena@example.co.za",
        "phone": "+27 82 555 0142",
        "sourceUpdatedAt": "2026-08-31T09:12:00Z",
        "location": "Cape Town, Atlantic Seaboard",
        "photoUrl": "https://cdn.example.com/agents/agt-1049.jpg",
        "ffcNumber": "FFC-2026-114829"
      }
    }
  ],
  "pagination": { "limit": 50, "count": 1, "hasMore": false, "nextCursor": null },
  "nextUpdatedSince": "2026-08-31T09:12:00Z",
  "updatedSince": null,
  "generatedAt": "2026-09-22T06:45:39Z"
}

Field meanings are in the Field Reference (same data, feed field names). A rental listing additionally carries availableNow and availableFrom. photoUrls is in gallery order.

GET /properties/{externalListingId}

One active listing, identical shape to a properties list item. 404 not_found if the id does not match a currently active listing (including one that was just removed — check property-deletions).

GET /agents

The distinct agents referenced by active listings — not a separate table, derived from the properties themselves, so an agent who has no active listing does not appear here (they still appear nested in history only via the property responses that referenced them while active). Paginated, supports updated_since.

{
  "externalAgentId": "AGT-1049",
  "providerId": "havho-sandbox",
  "fullName": "Naledi Mokoena",
  "email": "naledi.mokoena@example.co.za",
  "phone": "+27 82 555 0142",
  "externalAgencyId": "AGY-77",
  "agencyName": "Atlantic Edge Properties",
  "sourceUpdatedAt": "2026-08-31T09:12:00Z",
  "location": "Cape Town, Atlantic Seaboard",
  "photoUrl": "https://cdn.example.com/agents/agt-1049.jpg",
  "ffcNumber": "FFC-2026-114829"
}

providerId is always the agent's agency's providerId — an agent has no namespace of its own. If the same agent appears on several properties, the most recently changed one wins.

GET /agencies

The distinct agencies referenced by active listings, same derivation as agents. Paginated, supports updated_since.

{
  "externalAgencyId": "AGY-77",
  "name": "Atlantic Edge Properties",
  "providerId": "havho-sandbox",
  "sourceUpdatedAt": "2026-08-31T09:12:00Z"
}

GET /property-deletions

Listings removed since updated_since (compared against deletedAt), or the full retained history when omitted. Paginated.

{
  "deletionId": "del_9f2c7a4e1b3d5f60",
  "providerId": "havho-sandbox",
  "externalListingId": "CPT-S-1502",
  "deletedAt": "2026-08-29T16:40:00Z",
  "reason": "sold"
}

A distinct deletion event is the combination of providerId + externalListingId + deletedAt; deletionId is a stable hash of those three, so a consumer can de-duplicate even across separate pulls. The same event is never returned twice by this endpoint (the importer collapses exact duplicates on the way in). A listing that is later re-listed and removed again produces a separate event with its own deletedAt — do not treat externalListingId alone as the removal's identity.

GET /sync/status

Health of the import pipeline behind this API. Not paginated.

{
  "sourceHealth": "healthy",
  "snapshot": "complete",
  "lastCompletedSnapshotAt": "2026-09-22T11:38:54Z",
  "activePropertyCount": 3458
}

This reports import health, not delivery health. A complete snapshot means the catalogue was read correctly from the source; it says nothing about whether Firebase or any other downstream consumer has since applied it. Track your own consumption checkpoint (e.g. the last nextUpdatedSince you stored) separately.

Naming differences from the feed contract

The feed you send us and the API you read back use different names for the same identifiers — this trips people up more than anything else here:

These REST names are a fixed contract kept stable for existing integrations; they will not be renamed to match the feed's id-based naming in this version.

Delivery guarantees worth relying on

Postman collection

A ready-to-run collection covering every endpoint above, cursor paging, an incremental sweep, the auth failure cases and the sandbox feed is available from the admin at Settings → API → Postman collection (requires an admin login).

HAVHO Property Feed Specification · v2.0 · AdminBuilder