Conventions
A few rules hold across every endpoint. Learn them once and the rest of the API is predictable.
Instant Quote markets only
Section titled “Instant Quote markets only”Files created over the API and the MCP connector reach Hedge Instant Quote
markets only: programs Hedge quotes through the carrier’s own system. Binding
and specialty markets are never reached over the API, and an API file starts
no marketing. It gets the same emails a portal file gets (submission
received, Hedge’s questions, quotes, bind and policy emails), following your
brokerage’s notification settings. When no instant market
fits, the API answers 422 no_instant_market with an email_us block
(address and what to include); email that and Hedge works the risk the
usual way.
Requests
Section titled “Requests”- JSON over HTTPS. Send
Content-Type: application/jsonon requests with a body. Exceptions: the OAuth token and device endpoints takeapplication/x-www-form-urlencoded, and file uploads (/broker/intake,.../documents) takemultipart/form-data. - Bearer auth. Every request carries a short-lived OAuth 2.1 token:
Authorization: Bearer <token>. API keys are exchanged for tokens and never sent on API requests. See Authentication. - Base URLs.
https://api.hedgespecialty.com/api/v1in production,https://sandbox-api.hedgespecialty.com/api/v1in the sandbox. Hedge-Clientheader. SendHedge-Client: <name>/<version>(for exampleHedge-Client: acme-ams/2.3.0) so Hedge can tell your integration apart in its logs. Optional, and recommended.
Scopes and submit access
Section titled “Scopes and submit access”| Scope | Grants |
|---|---|
broker_mcp |
Read: appetite, requirements, your files and their market states, quotes and documents, events, policies, payments. |
broker_submit |
Submit: create and intake, answer, quote, bind link, upload documents, withdraw. |
Read access is self-serve. Submit access is turned on per brokerage by Hedge;
until it is on, tokens are issued without broker_submit (the token
response’s scope says what was granted) and submit calls return 403. A
valid token without the scope for a call gets 403; don’t retry it.
producer_email for API keys
Section titled “producer_email for API keys”A token minted from an API key (the client_credentials grant) carries no
broker identity. Every submit call made with one names the producing broker
with producer_email, an active portal user of your brokerage. The file and
the action are attributed to that broker. Missing or unknown producer_email
returns 422. Per-user tokens ignore the field.
client_reference and idempotency
Section titled “client_reference and idempotency”client_reference(up to 128 characters) is your own reference for a file, and it is unique per brokerage. Creating with a reference you have used before returns the existing file with200instead of creating another (201). Use it on every create and intake so a retry, a crash or a second run of your agent never duplicates a file.Idempotency-Keyheader:POST /broker/submissions,POST /broker/intake, document uploads and thread replies accept one. Re-sending the same key replays the saved result. A key reused with different inputs, or still in flight, returns409.- Identical files sent in one intake call are stored once.
PATCH .../answersis all or nothing: a refused answer saves nothing.
Market states
Section titled “Market states”Every Hedge Instant Quote market on a file has one state. Create, intake,
GET .../instant-quotes, PATCH .../answers and POST .../quote all return
the same file state.
state |
Meaning | status_label |
|---|---|---|
preparing |
Hedge is preparing the market’s application. Poll. | Preparing |
needs_answers |
The market needs the answers in missing[]. |
Needs 2 answers |
ready |
Complete. POST .../quote requests it. |
Ready to quote |
quoting |
Requested; the carrier is working on it. | Quoting |
quoted |
A quote is in; quote is set. |
Quoted · $1,234.00 |
declined |
The carrier declined; reason says why when it gave one. |
Declined · <reason> |
not_a_fit |
The carrier’s appetite refused the risk at preparation. | Not a fit · <reason> |
Values Hedge picked (a carrier class, for example) come back in suggested[]
and stay in that market’s missing[] until you confirm them: send
confirm_suggestions: true to confirm every one as it stands, or answer one
with another value. Hedge never treats a suggestion as an answer on its own.
Keys and ids
Section titled “Keys and ids”A question has two names:
key, the canonical fact it is bound to (annual_revenue), orprogram.<slug>.<id>for a question only one market asks. Answer a key once inshared_answersand every market that asks it is filled.id, the market’s own question id. Answer it underanswers[program_id].
missing[] items carry both. One with key: null is a file-level gap,
answered through the file’s core facts.
- The
quotesummary on a market (premium,total) is in dollars. - The itemized quote read,
GET .../quotes, is in integer cents withcurrency: USD. nullmeans unknown, never zero.
Polling and cursors
Section titled “Polling and cursors”- Poll
GET .../instant-quotesevery 5 to 10 seconds while a market ispreparingorquoting. Preparation usually finishes within a minute. - Across many files, poll
GET /broker/eventsor use webhooks. See Notifications and events. GET /broker/events,GET .../eventsandGET .../threadare cursor-paged. The end of the stream is a null cursor, never page length. A non-nullnext_cursormeans more may exist: call again withsince=<cursor>until you getnull. Dedupe byid.
Errors
Section titled “Errors”Errors carry {"detail": {"code": "…", "message": "…", …}}. 403 means
stop, 429 means wait Retry-After. The full list is in Errors.
Data scoping
Section titled “Data scoping”Every token is bound to exactly one brokerage, and all data is scoped to it. The brokerage comes from the token, never from the request body.