Skip to content

Conventions

A few rules hold across every endpoint. Learn them once and the rest of the API is predictable.

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.

  • JSON over HTTPS. Send Content-Type: application/json on requests with a body. Exceptions: the OAuth token and device endpoints take application/x-www-form-urlencoded, and file uploads (/broker/intake, .../documents) take multipart/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/v1 in production, https://sandbox-api.hedgespecialty.com/api/v1 in the sandbox.
  • Hedge-Client header. Send Hedge-Client: <name>/<version> (for example Hedge-Client: acme-ams/2.3.0) so Hedge can tell your integration apart in its logs. Optional, and recommended.
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.

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 (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 with 200 instead 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-Key header: 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, returns 409.
  • Identical files sent in one intake call are stored once.
  • PATCH .../answers is all or nothing: a refused answer saves nothing.

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.

A question has two names:

  • key, the canonical fact it is bound to (annual_revenue), or program.<slug>.<id> for a question only one market asks. Answer a key once in shared_answers and every market that asks it is filled.
  • id, the market’s own question id. Answer it under answers[program_id].

missing[] items carry both. One with key: null is a file-level gap, answered through the file’s core facts.

  • The quote summary on a market (premium, total) is in dollars.
  • The itemized quote read, GET .../quotes, is in integer cents with currency: USD.
  • null means unknown, never zero.
  • Poll GET .../instant-quotes every 5 to 10 seconds while a market is preparing or quoting. Preparation usually finishes within a minute.
  • Across many files, poll GET /broker/events or use webhooks. See Notifications and events.
  • GET /broker/events, GET .../events and GET .../thread are cursor-paged. The end of the stream is a null cursor, never page length. A non-null next_cursor means more may exist: call again with since=<cursor> until you get null. Dedupe by id.

Errors carry {"detail": {"code": "…", "message": "…", …}}. 403 means stop, 429 means wait Retry-After. The full list is in Errors.

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.