Verification.
Connected.

Authentication

Every call carries your key in the X-API-Key header. There is no OAuth dance, no bearer exchange and no session — one header, on every request, over TLS.

curl https://connect.homeequal.ai/api/v1/partner/whoami \
  -H "X-API-Key: heq_live_YOUR_API_KEY"

whoami is the first call worth making: it answers which tenant the key belongs to, which products it may order, whether it is live or test, and — usefully — the source IP we saw you from, which is the number an allowlist is written against.

Two key literals, two worlds

Use the key issued for your environment. Keys are displayed once at issue. If a key is lost, rotate it and update your integration.

Network restriction

A key may be pinned to your egress addresses (IPv4, CIDR, or exact IPv6). Used from anywhere else it fails with 403 API_KEY_IP_FORBIDDEN — so a leaked key is worth nothing outside your network. Confirm what we see you as with the seenFrom field above before you ask for one.

Scopes

Request verify:create and the scopes for your contracted products (verify:voa, verify:voe, verify:voi). Your key may access only authorized products and records. Use whoami to confirm your entitlements before creating an order.

keys:rotate is credential-grade: it can replace your keys and repoint your webhook. Issue it to a deliberately separate management key, never to the integration key — otherwise a leaked integration key can mint itself a fresh secret and start the clock on locking you out.

Manage all of this yourself in the developer console: inventory, ages, last use, zero-downtime rotation, webhook configuration and live usage.

Ordering a verification

Three products, ordered the same way and sold separately. The last column says what each product's result carries: a VOE order confirms employment and never returns an income figure. The full reference lists the response fields behind each.

Step 1 — consent, always first

No verification exists without a permissible-purpose record. Capture the borrower's consent in your own UI, then exchange it here for a single-use, purpose-limited token. The token is minted in the calling key's mode and can only be spent in that mode, so a sandbox rehearsal can never produce the consent record for a real borrower's pull.

curl -X POST https://connect.homeequal.ai/api/v1/verify/consent \
  -H "X-API-Key: heq_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"borrower":{"id":"borrower-8891"},"purpose":"mortgage_application"}'

{
  "token": "CONSENT_TOKEN_SHOWN_ONCE",
  "consentId": "vc_0123456789abcdef",
  "purpose": "mortgage_application",
  "disclosure": "band",
  "expiresAt": "2026-08-07T16:04:05Z"
}

Exact income — a contracted tier, doubly authorized

By default an income result carries a band (income.band, exactDisclosed: false). Underwriting runs on figures, so keys contracted for it hold verify:income:exact and receive income.amount — but only when both authorities align: your key's scope, and a borrower grant issued with "disclosure": "exact", which requires the consent text you showed to have named exact-figure disclosure. Either alone yields the band. Two keys of the same tenant can read the same verification and see different tiers — that is the design, not a bug.

Exact income requires both borrower authorization and the appropriate tenant entitlement. Exact disclosures are auditable. Retrieve authorized exact values through the result endpoint; webhooks carry the band response. The band remains present in both response tiers.

Employed-as-of re-check — the verbal VOE, replaced

Closing re-verifies employment inside the final days before funding. Order it as a first-class re-check instead of a phone log: POST /api/v1/verify/:id/recheck (no body, Idempotency-Key required) creates a fresh employment-only verification chained to the original. Its authority is the window the borrower granted up front — issue the original consent with "recheckDays": 45 (max 180) and the consent text you show must name re-verification through that bound; inside the window no fresh token is needed, outside it the order is refused. A re-check is always product voe whatever the original was — it answers continuance, so it can never widen disclosure (an exact-tier VOI original still yields an income-free re-check), and it needs voe entitlement. The completed re-check carries a tri-state recheck.continuity block — unchanged is true only when the employer affirmatively matches and status is affirmatively active; incomplete evidence reads null, never reassurance — and the original verification's tamper-evident event log records every re-check ordered and resolved against it.

Step 2 — order it

Idempotency-Key is required on this endpoint: 8–128 characters of [A-Za-z0-9._:-], unique per intended order. A network timeout followed by a retry is otherwise a second real verification on the same borrower, billed twice. Replaying the same key with the same body returns the original response with X-Idempotent-Replay: 1; reusing it with a different body is a 409 IDEMPOTENCY_KEY_CONFLICT, because that is a bug on your side, not a retry.

curl -X POST https://connect.homeequal.ai/api/v1/verify \
  -H "X-API-Key: heq_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: app-2026-000412-voa-01" \
  -d @order.json

{
  "applicationId": "APP-2026-000412",
  "product": "voa",
  "borrower": {
    "id": "borrower-8891",
    "fullName": "Jordan Rivera",
    "emailOrPhone": "complete@example.com"
  },
  "consent": {
    "token": "CONSENT_TOKEN_FROM_STEP_1",
    "capturedAt": "2026-08-07T15:04:05Z",
    "purpose": "mortgage_application"
  },
  "claimedFacts": {
    "employer_name": "Northwind Logistics",
    "stated_income": 128000
  },
  "options": {
    "policy": "observe"
  },
  "delivery": {
    "email": true
  }
}

{
  "verificationId": "ver_0000000000",
  "status": "AWAITING_BORROWER_CONNECT",
  "product": "voa",
  "borrowerLink": {
    "url": "https://homeequal.ai/verify-income/BORROWER_LINK_TOKEN",
    "token": "BORROWER_LINK_TOKEN",
    "expiresAt": "2026-08-14T15:04:05Z"
  }
}

202, not 200. The borrower has not done anything yet. Hand them borrowerLink.url (or set delivery.email and we will), then wait for the webhook. Always use the returned link; do not construct a borrower URL or infer a connection flow from the product name. The response example shows the fields needed to complete this integration.

Two refusals worth handling explicitly, because neither is a bad request: 409 SOURCE_UNAVAILABLE means verification is currently unavailable for that request and we refused it up front rather than accepting a verification that could never complete — nothing was created, and your consent token is unspent. 403 PRODUCT_NOT_ENTITLED means the key is product-scoped and this is not one of its products.

Getting the result

Webhooks — the path to build on

Every terminal state is delivered to your receiver as a signed envelope. Configure the URL yourself (PUT /api/v1/partner/webhook, keys:rotate scope) or in the console.

{
  "id": "evt_00000000000000000000",
  "type": "verification.completed",
  "tenantId": "your-tenant-id",
  "livemode": true,
  "createdAt": "2026-08-07T15:19:41.204Z",
  "data": {
    "applicationId": "APP-2026-000412",
    "verificationId": "ver_0000000000",
    "status": "COMPLETED",
    "product": "voa"
  }
}

Events emitted: verification.completed, verification.denied, verification.expired, verification.failed. livemode is on the envelope for a reason — read it and route on it. It is absent-means-live: only an explicit false is a sandbox event. Each mode has its own receiver URL and its own signing secret, so a test event can never arrive signed with your production secret, and a sandbox rehearsal can never be booked as a real one by a receiver that was not paying attention.

Verifying the signature

The HMAC is computed over <timestamp>.<raw body>, so a signature captured yesterday cannot be replayed onto today's body and vice versa. Reject anything outside a five-minute window, and compare in constant time.

const crypto = require('node:crypto');

// Verify against the RAW request bytes. Re-serializing the parsed JSON
// changes key order and whitespace, and the signature will never match.
function verify(rawBody, header, secret) {
  const parts = Object.fromEntries(header.split(',').map((s) => s.split('=', 2)));
  const age = Math.abs(Math.floor(Date.now() / 1000) - Number(parts.t));
  if (!(age <= 300)) return false;                       // 5-minute replay window
  const expected = crypto.createHmac('sha256', secret)
    .update(parts.t + '.' + rawBody).digest('hex');
  const a = Buffer.from(expected, 'hex');
  const b = Buffer.from(String(parts.v1 || ''), 'hex');
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

Delivery retries use exponential backoff on server or network errors. Receivers must be idempotent. Answer 2xx quickly and do the work afterwards: a receiver that verifies and enqueues never needs a replay. Setting a webhook URL always issues a fresh signing secret, and secret rotation has no overlap window — a webhook carries one signature per event, so the very next delivery uses the new secret. Deploy it before you rotate, not after.

Polling — the fallback, not the design

curl https://connect.homeequal.ai/api/v1/verify/ver_0000000000 \
  -H "X-API-Key: heq_live_YOUR_API_KEY"

Tenant-scoped, mode-scoped and product-scoped: a key sees only its own tenant's verifications, only its own mode's, and only the products it is entitled to. Everything else answers 404 — deliberately not 403, so the endpoint cannot be used to discover what exists.

The report and its seal

The artifact a lender files and forwards is a PDF, guarded identically to the JSON read — same tenant scope, same product entitlement, same 404-not-403, so the PDF is never a way around the shaping applied to the JSON.

Availability is product-scoped: today only voa renders a PDF. A voe or voi verification returns 409 REPORT_UNAVAILABLE here, and the JSON read is its deliverable. This is a real limit, not a transient one — build against the JSON and treat the PDF as additive for asset orders. The seal below likewise exists only where a report does.

curl https://connect.homeequal.ai/api/v1/verify/ver_0000000000/report.pdf \
  -H "X-API-Key: heq_live_YOUR_API_KEY" \
  -o report.pdf

The seal

Every report carries a sixteen-character seal in four groups. Anyone holding the document — a counterparty, an investor, an auditor with no account here — can check it, unauthenticated, with nothing but the code on the page.

curl https://homeequal.ai/verify/ABCD-EFGH-JKLM-NPQR \
  -H "Accept: application/json"

Read this part carefully, because the distinction is the whole value of the seal.

To get the content-bound answer, pass the report's digest — a sha256 over its canonical facts:

curl "https://homeequal.ai/verify/ABCD-EFGH-JKLM-NPQR?digest=REPORT_CONTENT_DIGEST" \
  -H "Accept: application/json"

The seal check never discloses the subject's name, an account, or a balance — only facts already printed on the face of the document the asker is holding. Someone who guessed a valid seal learns nothing they could not have learned by holding the report.

The full reference

Two sections are served to key holders only: the sandbox — the outcome personas and when each one lands — and quotas — the ceilings by tier behind the 402 QUOTA_EXCEEDED response and the X-Quota-* headers. Paste any heq_test_ or heq_live_ key to open it here, or fetch it directly:

curl -H 'X-API-Key: heq_test_YOUR_API_KEY' https://connect.homeequal.ai/api/v1/partner/docs/reference

No key yet? The developer console issues sandbox keys, and fintegral@homeequal.ai reaches a person.

Error codes

Every error is { "error": { "code", "message", … } }. Branch on code for request errors; handle all HTTP 503 responses as temporary failures and retry with backoff. Never branch on the message — messages are written for humans and will be improved.