Overview

Hedge Submission API 1.0

Submit commercial insurance risks to Hedge programmatically and track them to quote. One rail, two doors:

Connected apps / broker agents, per-user OAuth 2.1 (PKCE, dynamic client registration). The broker consents once; tokens are scoped to their brokerage. This is also how the Hedge MCP connector works.
Systems (machine) credentials, brokerage API clients created self-serve in the broker portal (Settings → API keys) or issued by Hedge ops, exchanged via the client_credentials grant. Submissions made with a machine credential must name a producer_email.

The contract works like emailing Hedge a risk: one call in, the system runs. POST /broker/intake (free text and/or PDFs) or POST /broker/submissions (structured JSON) creates the submission and immediately starts marketing: Hedge matches appetite, sends the structured clearance email to the producer listing every market being tried, opens the lanes, and quotes the instant-quote markets on recorded favorable assumptions. Pass hold: true to defer the run until you call finalize. Then read GET /broker/submissions/{id}/markets: the markets come back in three categories, Hedge Instant Quote (connected carrier APIs), Hedge Binding (markets Hedge quotes for you) and Hedge Specialty (email markets), each lane with what it still needs from you, the assumptions Hedge filed on the broker’s behalf (pre-bind attestations to confirm) and released quotes. GET /broker/submissions/{id}/requirements stays the gaps view.

All endpoints are scoped to YOUR brokerage by the token, there is no cross-tenant access. Base URL: https://api.hedgespecialty.com/api/v1.

The thread. API brokers get the same emails an email broker gets, and Hedge starts the conversation (the clearance email, questions, quote deliveries). GET /broker/submissions/{id}/thread mirrors that conversation 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: answer a question, send a revision, authorize a bind. 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 staging portal receive staging 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

Authentication

brokerOAuth

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.

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