Information
- OpenAPI version:
3.1.0
Quote Hedge Instant Quote markets from your own software. The API mirrors the broker portal: the same markets, the same questions, the same quotes and documents.
Instant markets only. Files created over the API (and the MCP
connector) reach Hedge Instant Quote markets only: the markets Hedge
quotes through the carrier’s own system. Binding and specialty markets
are never reached over the API. When no instant market fits a risk,
Hedge says so (instant_available: false on the appetite read, 422
no_instant_market on a create, which creates nothing) and the
email_us block says where to email the risk and what to include.
The flow.
POST /broker/appetite/instant (read): which instant markets fit
the state, lines and class, or email_us when none does.POST /broker/requirements (read): the file’s core fields and each
chosen market’s own questions, per market and never deduplicated. A
question’s key is its canonical fact: answer it once in
shared_answers and every market that asks it is prefilled.POST /broker/submissions (structured JSON) or POST /broker/intake
(documents and/or text) (submit): creates the file for those
markets and returns each market’s state. quote: true quotes
each market as soon as it is ready.GET /broker/submissions/{id}/instant-quotes (read): poll it. Each
market is preparing, needs_answers (with exactly what is
missing), ready, quoting, quoted, declined or not_a_fit.
A value Hedge suggests (a carrier class, for example) comes back in
suggested and is never used as your answer until you confirm it.PATCH /broker/submissions/{id}/answers (submit) answers the gaps;
POST /broker/submissions/{id}/quote (submit) requests the ready
markets.GET /broker/submissions/{id}/quotes (read): the itemized quotes and
their documents (Hedge’s quote PDF and the carrier’s), downloaded
from GET /broker/finalized-documents/{document_id}/pdf.POST /broker/submissions/{id}/quotes/{quote_id}/bind-link (submit):
the link to bind, the broker’s bind checklist in the Hedge portal or
the insured’s pay-and-bind page.An API file reaches Hedge Instant Quote markets only (no email or portal markets). Hedge emails your team about it exactly as for a portal file; emails follow your brokerage’s notification settings, and the defaults match the portal.
Following files. Poll one file with GET .../instant-quotes, or
every file at once with the brokerage-wide GET /broker/events feed
(quote_received events carry the quote’s documents), or register a
webhook (below). Which emails Hedge sends your team, to whom and on
which channel is set per event in the broker portal (Settings →
Notifications).
Access. Two doors to the same rail, both scoped to one brokerage:
hedge CLI sign in this way.client_credentials grant. Every submit call made with one names a
producer_email, an active portal user of your brokerage.Read access (broker_mcp) is self-serve: appetite, requirements and
your brokerage’s own files, quotes, documents and events. Submit access
(broker_submit: create, answer, quote, bind link) is turned on per
brokerage by Hedge; a brokerage admin requests it in the broker portal
(Settings → API keys). Until it is on, tokens are issued without
broker_submit; the token response’s scope says what was granted.
Conventions.
https://api.hedgespecialty.com/api/v1. A record of another
brokerage answers 404, never 403.{"detail": {"code": "...", "message": "...", ...}}
with a stable code (a few older validators return
{"detail": "<message>"}).client_reference (up to 128 characters, unique per
brokerage) makes a create idempotent. The same reference returns the
existing file (200) instead of a new one. Idempotency-Key on create,
intake, document upload and thread replies replays the saved result
of a retried call.currency on the quote read; the flow’s
short quote summary is in dollars. null means unknown, never zero.next_cursor, never a short page;
dedupe by id.Hedge-Client: <name>/<version> (for example
Hedge-Client: acme-ams/2.3.0) so Hedge can tell your integration
apart in its logs.Limits. Each OAuth connection or API key gets 120 reads (GET) and
60 writes (every other method, MCP write tools included) per minute,
counted per key or per connected user in fixed one-minute windows.
Daily per-brokerage caps also apply (100 creates, 100 intake calls, 500
uploads, 150 appetite checks). Over a limit the API answers 429 with
a Retry-After header (seconds); 503 with Retry-After means Hedge
couldn’t count a write just now.
Errors: stop and back off.
detail to a person, and send any remaining work by email.Retry-After seconds before the next call. Don’t
fire queued calls in the meantime; a daily cap resets the next day.Retry-After.detail says; resending it
unchanged gets the same answer.Sandbox. Build against https://sandbox-api.hedgespecialty.com/api/v1
(MCP: https://sandbox-mcp.hedgespecialty.com/mcp), Hedge’s staging
environment. To get a sandbox account, ask your Hedge contact; Hedge
creates it for the email address you will sign in with. Sign in at
https://staging-brokers.hedgespecialty.com (Google, or “Forgot
password”) and create keys under Settings → API keys. Sandbox keys work
only in the sandbox, and production keys do not work there. Quotes are
real responses from carriers’ test systems (the instant-quote markets
whose carrier runs one: Blitz, CFC, Coalition, Coterie, Cowbell,
EMPLOYERS, LIO and NEC today); they are test quotes, never coverage.
Other markets do not appear. Nothing reaches a carrier’s production
system or an underwriter, and no texts are sent. The only thing that
leaves the sandbox is email to your own sandbox users. Your account sees
only its own files.
The thread. GET /broker/submissions/{id}/thread mirrors the
conversation Hedge has with you on a file as one plain-text message
stream (Hedge’s emails, your replies, and the assistant chat; never
carrier correspondence), and POST .../thread replies to Hedge exactly
as an email reply would. Answers arrive in the thread and on the
submission.message webhook.
Webhooks (push). Instead of polling the events feed and the
thread, register a webhook endpoint and Hedge POSTs new submission
events (submission.events) and new thread messages
(submission.message) to you as they become visible; same objects,
same visibility rules, minutes instead of poll intervals. Endpoints
are managed in the broker portal (Settings → Webhooks, brokerage
admins only; the management API is portal-session-only by design; a
leaked machine key must never be able to point your event stream
somewhere new). An endpoint’s optional event_types filter may name
any feed event type plus message. Deliveries are signed
(svix-compatible) and documented under Webhooks below. Endpoints
created in the sandbox portal receive sandbox deliveries, with their
own secrets.
Changes are additive-only on this version. Breaking changes ship as a new version with notice to integrated partners.
Broker access token. Scopes: broker_mcp (read), broker_submit
(write). Per-user tokens come from the OAuth authorization-code +
PKCE flow (/oauth/authorize → /oauth/token); machine tokens
from client_credentials, using an API key created self-serve in
the broker portal (Settings → API keys) or issued by Hedge ops.
Access tokens live 60 minutes. broker_submit is granted only when
Hedge has turned submit on for the brokerage; reads are self-serve.
A 403 is final for that call: don’t retry it.
Security scheme type: oauth2
Flow type: authorizationCode
Authorization URL: https://api.hedgespecialty.com/api/v1/oauth/authorize
Token URL: https://api.hedgespecialty.com/api/v1/oauth/token
Scopes:
Flow type: clientCredentials
Token URL: https://api.hedgespecialty.com/api/v1/oauth/token
Scopes: