How the pieces fit

Every county integration implements one interface, ICountyAdapter. A registry resolves an adapter from whatever county string sits on the property row, after normalizing it, and returns null for a county we do not cover. Every consumer, the portal and the assistant’s home context alike, must tolerate that null and render “not on file” rather than guess.

// src/lib/adapters/types.ts (abridged)
export interface ICountyAdapter {
  readonly countyName: string;
  readonly state: string;
  fetchPropertyByParcelId(parcelId: string): Promise<CountyPropertyData>;
  fetchTaxAndHomesteadData(parcelId: string): Promise<CountyTaxData>;
  getCountyAlerts(property: CountyPropertyData): Promise<CountyAlert[]>;
  // Optional. Consumers feature-detect before calling.
  getUtilities?(location?: UtilityLocation): UtilityService[];
  getStormResources?(): StormResources;
  getInspections?(parcelId: string): Promise<CountyInspection[]>;
}

// src/lib/adapters/index.ts
import { getCountyAdapter } from "@/lib/adapters";

// "St. Johns", "st johns", "Saint Johns County, FL" all resolve the same way.
const adapter = getCountyAdapter(property.county); // ICountyAdapter | null
if (adapter?.getUtilities) {
  const providers = adapter.getUtilities({ zip: "32080", city: "St. Augustine" });
}

What is real and what is simulated

There is one adapter today, St. Johns County, Florida. The county Property Appraiser has no public parcel API, so the adapter’s parcel, tax and permit lookups are a deterministic simulation: every figure derives from a hash of the parcel id, so a parcel returns the same numbers on every request. That simulation is for demo surfaces only.

A live home is built by countyPropertyFromRow from the property row plus its enrichment payload: ATTOM first, then the Florida statewide cadastral or RentCast for assessed value and last sale. PermitStack supplies real permit history where it covers the jurisdiction and says when it does not (St. Johns County was not covered as of August 2026), so an empty permit list renders as unknown rather than as none. The adapter still supplies county alerts, the utilities directory and storm resources; the utilities and storm data are curated by hand and were checked against provider territories in August 2026.

Two fields are deliberately withheld on live rows. Owner of record is never surfaced. Homestead status is unknown, so every homestead message is phrased conditionally and never as an assertion.

Adding a county means implementing the interface in a sibling file and registering its name aliases. The interface and the St. Johns adapter are treated as a contract; consumers are written against the shape, not the county.

Field-service platforms (ServiceTitan, Housecall Pro, Jobber, or anything that can POST JSON) report completed jobs to one endpoint. The visit lands on the matched homeowner’s portal as reported. The homeowner confirms or dismisses it there. The endpoint never changes a home’s records directly, and a vendor can only report against homes in the brokerages that list that vendor.

Endpoint and authentication

POST /api/integrations/service-visit with a JSON body of at most 32 KB. Send the key as Authorization: Bearer <key> or x-api-key: <key>. Keys are issued per vendor; we store a SHA-256 hash and the first twelve characters as a lookup prefix, compare in constant time, and never log or echo the plaintext.

Keys are minted in the vendor workspace, which is switched off during the invite-only pilot, so no vendor holds a key today. If you run a field-service platform and want to test against a real account, write to support@kepthaven.com.

Request body

curl -X POST https://www.kepthaven.com/api/integrations/service-visit \
  -H "Authorization: Bearer lvk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "address": "212 Ocean Trace Rd, St. Augustine, FL 32084",
    "serviceType": "HVAC tune-up",
    "description": "Annual maintenance. Replaced 16x25 filter, cleared condensate line.",
    "serviceDate": "2026-09-03",
    "invoiceTotal": 189,
    "externalRef": "INV-48213"
  }'

Address matching

Only the street line matters: everything before the first comma, normalized for case, punctuation and common suffix abbreviations (Rd and Road, St and Street, and so on). Candidates are narrowed in the database to the vendor’s brokerages and the leading house number, and released homes are excluded. Zero matches is a 404; more than one is a 409, and nothing is recorded in either case.

Responses

HTTP/1.1 201 Created
{
  "ok": true,
  "visitId": "5f1c2f0a-8d7e-4a4b-9c1e-2b6d3f7a9e10",
  "matched": { "upkeepItem": true, "maintenanceTask": false },
  "status": "reported"
}

HTTP/1.1 400 Bad Request
{ "ok": false, "error": "invalid_body", "detail": "serviceDate: serviceDate must be formatted YYYY-MM-DD" }

HTTP/1.1 401 Unauthorized
{ "ok": false, "error": "missing_api_key", "hint": "Send the key as `Authorization: Bearer <key>` or `x-api-key: <key>`." }

HTTP/1.1 404 Not Found
{ "ok": false, "error": "address_not_found", "hint": "No property matched that street address. Send the full street line as it appears on the homeowner's account ..." }

HTTP/1.1 409 Conflict
{ "ok": false, "error": "address_ambiguous", "matches": 2 }

HTTP/1.1 429 Too Many Requests
Retry-After: 3600
{ "ok": false, "error": "rate_limited", "hint": "Limit is 60 integration requests per vendor per hour." }

Rate limits

• Before authentication: 60 requests per IP address per 10 minutes, so a key-guessing spray is throttled before it reaches the key lookup.
• After authentication: 60 attempts per vendor per hour, counted across every key and every outcome. A validation error or an unmatched address counts the same as a created visit, so address probing is throttled exactly like success.
• Over either limit, the response is 429 with a Retry-After header.

A brokerage admin controls two groups of settings. Branding Studio sets the identity every portal, claim page and email inherits. The landing page editor shapes the brokerage’s public front door, with a live preview that is the real page. The page skeleton never changes: hero, three value cards, how it works, closing call to action. Fonts and layouts are curated lists, never free input.

The stored landing configuration

The brokerage’s configuration is validated field by field on read, and a bad or missing value falls back to the default, so a single stale entry can never blank the page.

{
  "layout": "split",
  "font": "coastal",
  "tone": "auto",
  "backgroundImageUrl": "https://example.com/hero.jpg",
  "overlay": "dark",
  "overlayStrength": 0.45,
  "badge": "Your agent, for life",
  "headline": "Everything about your home, in one place.",
  "subheadline": "Every home we close comes with a private portal.",
  "ctaLabel": "See your home's portal",
  "cards": [
    { "title": "Your documents, found in seconds", "copy": "..." },
    { "title": "Deadlines you never have to remember", "copy": "..." },
    { "title": "Pros your agent already trusts", "copy": "..." }
  ],
  "closingHeadline": "Ready to see your home's portal?",
  "showAgentCard": true
}

What an agent may change

An agent’s page layers a small override on the brokerage configuration. They can change what they say and where their portrait sits, not how the brokerage looks: layout, fonts, photo and colors all inherit.

// What an agent may change on their own page. Everything else inherits.
{
  "headline": "Hi, I'm your agent for life.",
  "subheadline": "...",
  "ctaLabel": "...",
  "intro": "Up to 320 characters about you.",
  "showAgentCard": true,
  "portraitPlacement": "hero" | "below"
}

For how these settings reach a homeowner and what they can and cannot see, read who can see a homeowner’s vault.