How-to: Developer / Partner API

Integrate CoverGuard into your own systems with API keys and webhooks — pull insurability data and push events straight into your stack.

Who this is for: Developers and partners on a Team plan. Where: Sys Admin → Developer (/developer), inside the Sys Admin sub-nav. Public reference: /api-reference; machine spec at GET /api/v1/openapi.json (OpenAPI 3.1).

Create an API key

1. Go to Sys Admin → Developer.
2. Click Create key. The raw key is shown once — copy it now; CoverGuard only

stores a hash + a display prefix, so it can't show it again.

1. Use it as a bearer credential against the /api/v1 surface.

Rotate a key (revoke + reissue with the same config) or revoke it anytime. Optionally set an expiry at creation (30 / 90 days / 1 year / never) — an expired key is refused at the API (401 API_KEY_EXPIRED) until you rotate or replace it. Rotate carries the old expiry forward by default.

Three gates every key must pass on each call

1. Paying — key creation is Team-tier-gated, and every call re-checks the owner's live

entitlement (a lapsed/downgraded account → 403 SUBSCRIPTION_INACTIVE).

1. Approved — a super-admin can require approval; an unapproved key gets

403 KEY_NOT_APPROVED. (New keys auto-approve unless approval is required.)

1. Scoped — a call outside the key's scopes gets 403 FORBIDDEN_SCOPE.

Keys carry a per-key rate limit and monthly quota; responses include RateLimit-* / Retry-After headers.

What you can call (v1 surface)

• GET /api/v1/me — introspect the calling key.
• GET /api/v1/properties/:id/insurability — insurability assessment.
• POST /api/v1/quote-requests/:id/status — report a quote-request status update

(carrier/broker ingestion; forward-only state machine; needs quotes:write).

• GET/POST/PATCH/DELETE /api/v1/team/members — pull/push your company's members (3rd-party

user sync); every change emits a team.member.* webhook.

Full contract: the OpenAPI spec at /api/v1/openapi.json.

Webhooks

1. In Developer, register an HTTPS endpoint — the **signing secret is returned

once**; store it.

1. Click Test on the endpoint to send a test event (a webhook.test ping) through

the real signed path — confirm your receiver is reachable and your signature check works before real events depend on it.

1. CoverGuard delivers events HMAC-SHA256 signed; verify the signature on your side.
2. Filter by event type, toggle active, and review the per-endpoint delivery log — each

attempt shows the response code + latency, and you can Resend any past delivery.

Domain events you can receive include quote/lead/subscription/team events (e.g. lead.captured, team.member.invited, subscription.payment_failed).

Dedupe on the event `id`. Delivery is at-least-once (a retry or a resend can arrive twice); the body id is a stable event id that stays the same across retries and redeliveries, so record processed ids and treat a repeat as a no-op.

Troubleshooting

• Developer tab is locked → API access is Team-tier. See

Billing & plans.

• `403 KEY_NOT_APPROVED` → an admin must approve the key.
• `403 SUBSCRIPTION_INACTIVE` → the owning account lapsed/downgraded below Team.
• `403 FORBIDDEN_SCOPE` → the key lacks the scope for that call.
• `429` / `Retry-After` → you hit the key's rate limit or monthly quota; back off.
• Webhook not delivered → check the delivery log + retries and that your endpoint is

HTTPS and returns 2xx. See Integrations & API.

Do this next

Create your first API key, introspect it with GET /api/v1/me, then register an HTTPS webhook so events reach your systems. Full contract: /api-reference.

• Integrations (Integration Hub) — no-code sync as an alternative
• Teams, seats & billing — the Team tier the API needs
• Integrations & API troubleshooting