Skip to content

Overview

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.

  1. POST /broker/appetite/instant (read): which instant markets fit the state, lines and class, or email_us when none does.
  2. 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.
  3. 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.
  4. 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.
  5. PATCH /broker/submissions/{id}/answers (submit) answers the gaps; POST /broker/submissions/{id}/quote (submit) requests the ready markets.
  6. 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.
  7. 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:

  • Connected apps and agents: per-user OAuth 2.1 (PKCE, dynamic client registration, device flow). The broker consents once. The Hedge MCP connector and the hedge CLI sign in this way.
  • API keys: brokerage machine credentials created in the broker portal (Settings → API keys) or issued by Hedge, exchanged with the 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.

  • JSON over HTTPS; uploads are multipart. Base URL: https://api.hedgespecialty.com/api/v1. A record of another brokerage answers 404, never 403.
  • Error bodies are {"detail": {"code": "...", "message": "...", ...}} with a stable code (a few older validators return {"detail": "<message>"}).
  • Idempotency: 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.
  • Money is integer cents with currency on the quote read; the flow’s short quote summary is in dollars. null means unknown, never zero.
  • On cursor feeds the tail is a null next_cursor, never a short page; dedupe by id.
  • Send 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.

  • 401: the token is missing, expired or revoked. Get a new token once; if that fails, stop.
  • 403: the token is valid but not allowed to do this. For example, submit access is off, the scope is missing, the brokerage is paused or the key was revoked. Don’t retry a 403: the same call fails the same way until a person changes the access. Stop the run, surface the detail to a person, and send any remaining work by email.
  • 429: wait the Retry-After seconds before the next call. Don’t fire queued calls in the meantime; a daily cap resets the next day.
  • 503: retry the same call once after Retry-After.
  • 409 / 422: fix the request as the 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.

Hedge developer documentation

Information

  • OpenAPI version: 3.1.0

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:

  • broker_mcp - Read brokerage-scoped submissions, policies, payments, appetite, and requirements.
  • broker_submit - Create submissions, answer Hedge's asks, and act on quotes for your brokerage.

Flow type: clientCredentials

Token URL: https://api.hedgespecialty.com/api/v1/oauth/token

Scopes:

  • broker_mcp - Read brokerage-scoped submissions, policies, payments, appetite, and requirements.
  • broker_submit - Create submissions, answer Hedge's asks, and act on quotes for your brokerage.