Quickstart
This walks one risk through the whole flow: a residential landscaper in California asking for general liability.
appetite ──► requirements ──► create ──► answer ──► quote ──► quotes + PDFs ──► bind linkBefore you start. You need a token with submit access (see
Authentication); with an API key, every submit call names
the producing broker with producer_email. Build against the
sandbox first: add --sandbox to the CLI, or use
https://sandbox-api.hedgespecialty.com/api/v1 as the base URL.
With the CLI
Section titled “With the CLI”-
Install and sign in.
Terminal window npm i -g hedge-brokerhedge login # device code, in your browserhedge login --client-id bac_... --client-secret bas_... # or an API key, for scriptsAdd
--sandboxto any command to use the sandbox. Homebrew and a one-line installer are in the CLI guide. -
Check appetite.
Terminal window hedge appetite "Residential landscaping and lawn care, 6 employees, no tree work over 15 ft" \--state CA --lines gl --naics 561730This lists the instant markets that will quote the risk, each with its
program_idand, where the carrier picks its class from a list, the class Hedge would use. When none fits, it prints theemail_usblock instead: the address and what to include. -
Read the requirements.
Terminal window hedge requirements --state CA --lines gl --naics 561730 \--description "Residential landscaping and lawn care"Without
--programsit uses every instant market appetite returned. You get the file’scorefields, then each market’s own questions, per market and not deduplicated. A question’skeyis its canonical fact (annual_revenue): answer it once and every market that asks it is filled. Itsidis the market’s own question id, for answers that belong to one market. -
Create the file.
Terminal window hedge create \--insured "Green Thumb Landscaping LLC" \--narrative "Residential landscaping and lawn care, 6 employees, no tree work over 15 ft." \--lines gl --state CA --naics 561730 --effective 2026-11-15 \--address "6834 Olive Tree Way" --city "Citrus Heights" --zip 95610 \--contact-first Dana --contact-last Reyes --contact-email dana@greenthumb.example --contact-phone 9165550142 \--set annual_revenue=850000 --set employee_count=6 --set annual_payroll=260000 \--set business_start_date=2016-04-01 \--client-reference AI-9f3c2b \--producer-email dana@youragency.comSend everything you know up front (the insured’s contact, when the business started, payroll): every market that asks it is filled, and fewer gaps come back.
Or send the whole body with
--file payload.json. Have the ACORDs instead?hedge intake ./acord-125.pdf ./acord-126.pdf --text "..."reads the documents and returns the same result. The same--client-referencereturns the existing file instead of creating another, so a retry is safe. -
Follow it and answer the gaps.
Terminal window hedge status <submission-id> --waithedge answer <submission-id> --confirm-suggestionsTo correct a fact later, answer it again:
Terminal window hedge answer <submission-id> --set annual_revenue=900000Each market starts
preparingand settles within about a minute intoneeds_answers(with what ismissing),ready, ornot_a_fit. Hedge suggests a value where a carrier picks from its own list (a class, for example);--confirm-suggestionsconfirms every suggestion as it stands, or answer one with another value.--set key=valueanswers by canonical key and corrects an earlier answer;--set <program-id>:<id>=valueanswers one market’s own question. -
Request quotes.
Terminal window hedge quote <submission-id> --waitEvery
readymarket is requested; the rest come back with what they still need. Create with--quoteand each market quotes on its own as soon as it is ready. -
Read the quotes and download the PDFs.
Terminal window hedge quotes <submission-id> --download ./quotesPricing, taxes and fees, coverages and subjectivities per quote, and every quote document saved to
./quotes: Hedge’s quote PDF (hedge_quote_pdf) and the carrier’s own. -
Get the bind link.
Terminal window hedge bind-link <submission-id> <quote-id>Opens the Hedge portal’s bind checklist for that quote, signed in as the producer. It works once and expires after 24 hours. For a market that takes the insured’s own payment (Coterie today),
--for insured --insured-email owner@greenthumb.exampleemails the insured their pay-and-bind link.
Add --json to any command for the API’s own JSON.
With curl
Section titled “With curl”Every step is one REST call under https://api.hedgespecialty.com/api/v1
with a bearer token ($HEDGE_TOKEN below; see
Authentication).
1. Appetite
Section titled “1. Appetite”curl -X POST "https://api.hedgespecialty.com/api/v1/broker/appetite/instant" \ -H "Authorization: Bearer $HEDGE_TOKEN" -H "Content-Type: application/json" \ -d '{ "state": "CA", "lines": ["general_liability"], "naics": "561730", "description": "Residential landscaping and lawn care, 6 employees, no tree work over 15 ft" }'{ "instant_available": true, "instant_markets": [ { "program_id": "6f1c2a0e-…", "program": "Coterie General Liability", "market_id": "a0b1c2d3-…", "market": "Coterie", "lines": ["general_liability"], "asks_class": true, "class": { "suggested": { "value": "ak_7d1e…", "label": "Landscaping Services (NAICS 561730)" }, "alternatives": [ { "value": "ak_19c0…", "label": "Lawn Care Services (NAICS 561730)" } ] } } ], "email_us": null}When instant_available is false, instant_markets is empty and
email_us is set:
{ "instant_available": false, "instant_markets": [], "email_us": { "address": "submissions@hedgespecialty.com", "what_to_include": [ "ACORD 125 (Commercial Insurance Application)", "ACORD 126 (General Liability)", "Your description of the operations, the requested effective date and limits" ] }}2. Requirements
Section titled “2. Requirements”curl -X POST "https://api.hedgespecialty.com/api/v1/broker/requirements" \ -H "Authorization: Bearer $HEDGE_TOKEN" -H "Content-Type: application/json" \ -d '{ "program_ids": ["6f1c2a0e-…"], "state": "CA", "lines": ["general_liability"] }'{ "core": [ { "key": "applicant.insured_name", "label": "Legal business name", "type": "text", "required": true, "validations": { "max_length": 255 } }, { "key": "narrative", "label": "What the business does", "type": "textarea", "required": true }, { "key": "primary_state", "label": "Risk state", "type": "text", "required": true, "validations": { "pattern": "^[A-Z]{2}$" } } ], "markets": [ { "program_id": "6f1c2a0e-…", "program": "Coterie General Liability", "market": "Coterie", "schema_version": "q1-3a9d…", "questions": [ { "id": "annual_revenue", "key": "annual_revenue", "label": "Annual revenue", "type": "number", "required": true, "prefilled_from": null, "validations": { "min": 0 } }, { "id": "gl_each_occurrence_limit", "key": "gl_each_occurrence_limit", "label": "Each occurrence limit", "type": "select", "options": [ { "value": 1000000, "label": "$1,000,000" } ], "required": true } ] } ]}core[].key is the create body path. Answer a question’s key once in
shared_answers and every market that asks it is filled; answer a market’s
own questions by id under answers[program_id].
3. Create
Section titled “3. Create”curl -X POST "https://api.hedgespecialty.com/api/v1/broker/submissions" \ -H "Authorization: Bearer $HEDGE_TOKEN" -H "Content-Type: application/json" \ -d '{ "applicant": { "insured_name": "Green Thumb Landscaping LLC", "naics": "561730", "date_business_started": "2016-04-01", "mailing_address": { "line1": "6834 Olive Tree Way", "city": "Citrus Heights", "state": "CA", "zip": "95610" }, "contact_first_name": "Dana", "contact_last_name": "Reyes", "contact_email": "dana@greenthumb.example", "contact_phone": "9165550142" }, "narrative": "Residential landscaping and lawn care, 6 employees, no tree work over 15 ft.", "lines_of_business": ["general_liability"], "primary_state": "CA", "effective_date": "2026-11-15", "program_ids": ["6f1c2a0e-…"], "shared_answers": { "annual_revenue": 850000, "employee_count": 6, "annual_payroll": 260000 }, "answers": { "6f1c2a0e-…": { "gl_each_occurrence_limit": 1000000 } }, "client_reference": "AI-9f3c2b", "quote": true, "producer_email": "dana@youragency.com" }'201 (or 200 when client_reference found the file you already created):
{ "submission_id": "0694932d-…", "client_reference": "AI-9f3c2b", "portal_url": "https://brokers.hedgespecialty.com/submissions/0694932d-…", "automatic_quoting": true, "markets": [ { "program_id": "6f1c2a0e-…", "program": "Coterie General Liability", "market": "Coterie", "lines": ["general_liability"], "state": "preparing", "status_label": "Preparing", "missing": [], "reason": null, "quote": null } ], "suggested": [], "warnings": []}The file reaches the instant markets only and starts no marketing. If the
facts fit no instant market, the create returns 422 no_instant_market with
email_us and creates nothing. From documents instead, POST /broker/intake
takes multipart files and/or text (plus optional program_ids,
client_reference, quote and the usual typed fields) and returns the same
response.
4. Status and answers
Section titled “4. Status and answers”Poll every 5 to 10 seconds while a market is preparing:
curl "https://api.hedgespecialty.com/api/v1/broker/submissions/$SUBMISSION_ID/instant-quotes" \ -H "Authorization: Bearer $HEDGE_TOKEN"A market that needs answers lists them:
{ "program_id": "6f1c2a0e-…", "market": "Coterie", "state": "needs_answers", "status_label": "Needs 1 answer", "missing": [ { "key": null, "id": "ak_hash", "label": "Business description", "message": "Confirm Hedge's suggested class, or answer with another." } ]}Values Hedge picked for you come back in suggested[] and stay in missing[]
until you confirm them. Confirm them all as they stand:
curl -X PATCH "https://api.hedgespecialty.com/api/v1/broker/submissions/$SUBMISSION_ID/answers" \ -H "Authorization: Bearer $HEDGE_TOKEN" -H "Content-Type: application/json" \ -d '{ "confirm_suggestions": true, "producer_email": "dana@youragency.com" }'To pick another value instead, answer that market’s question by its id, for
example "answers": { "<program_id>": { "ak_hash": "<value>" } } with a value
from the class alternatives. To correct a fact, answer it again; every market
that asks it is refilled:
curl -X PATCH "https://api.hedgespecialty.com/api/v1/broker/submissions/$SUBMISSION_ID/answers" \ -H "Authorization: Bearer $HEDGE_TOKEN" -H "Content-Type: application/json" \ -d '{ "shared_answers": { "annual_revenue": 900000 }, "producer_email": "dana@youragency.com" }'Answers are all or nothing: a refused answer returns 422 invalid_answers
with errors[] and saves nothing. A shared key no market on the file asks is
ignored and named in warnings[]. The response is the file state again.
A market briefly updates after preparing (applying the answers you sent at
create) and after a shared answer changes. A confirmation that reaches it
then is not applied, and warnings[] says so: read the file state again and
send confirm_suggestions once the market reads needs_answers. Send it on
its own, not in the call that changes a shared answer.
state |
Meaning |
|---|---|
preparing |
Hedge is preparing the market’s application. Poll. |
needs_answers |
Answer missing[]. |
ready |
Complete. Request the quote. |
quoting |
Requested; the carrier is working on it. |
quoted |
quote is set (quote_id, premium, total in dollars). |
declined |
The carrier declined; reason says why when it gave one. |
not_a_fit |
The carrier’s appetite refused the risk; reason says why. |
5. Quote
Section titled “5. Quote”Skip this when you created the file with "quote": true.
curl -X POST "https://api.hedgespecialty.com/api/v1/broker/submissions/$SUBMISSION_ID/quote" \ -H "Authorization: Bearer $HEDGE_TOKEN" -H "Content-Type: application/json" \ -d '{ "producer_email": "dana@youragency.com" }'The response is the file state plus results[], one per market:
requested, already_quoting, already_quoted, preparing, not_ready
(with missing[]) or not_a_fit (with reason). The status is 200 when
at least one market was requested or is already in progress, else 409
with the same body. Then poll .../instant-quotes until the markets are
quoted, declined or not_a_fit.
6. Quotes and PDFs
Section titled “6. Quotes and PDFs”curl "https://api.hedgespecialty.com/api/v1/broker/submissions/$SUBMISSION_ID/quotes" \ -H "Authorization: Bearer $HEDGE_TOKEN"Each lane’s quotes[] carries the itemized pricing in integer cents
(premium_cents, taxes, fees, total_cents, payment_options),
coverages, endorsements, subjectivities, bind.available and documents[]:
"documents": [ { "kind": "hedge_quote_pdf", "file_name": "Hedge quote.pdf", "download_path": "/api/v1/broker/finalized-documents/5b1e…/pdf", "carrier_url": null }, { "kind": "quote_proposal", "file_name": null, "download_path": null, "carrier_url": "https://…" }]hedge_quote_pdf is Hedge’s quote PDF and is listed first; the other kinds
are the carrier’s documents. A download_path is a Hedge route you call with
the same token; a carrier_url is carrier-hosted. Hedge prepares its PDF when
the quote is first read, so it can appear a few seconds after the quote; read
again to pick it up.
curl "https://api.hedgespecialty.com/api/v1/broker/finalized-documents/5b1e…/pdf" \ -H "Authorization: Bearer $HEDGE_TOKEN" -o quote.pdf7. Bind link
Section titled “7. Bind link”curl -X POST "https://api.hedgespecialty.com/api/v1/broker/submissions/$SUBMISSION_ID/quotes/$QUOTE_ID/bind-link" \ -H "Authorization: Bearer $HEDGE_TOKEN" -H "Content-Type: application/json" \ -d '{ "for": "broker", "producer_email": "dana@youragency.com" }'{ "url": "https://brokers.hedgespecialty.com/…", "expires_at": "2026-10-30T18:04:11Z", "for": "broker" }for: broker(the default) is a one-time sign-in link into the portal’s bind checklist for that quote, signed in as the producer. It works once and expires after 24 hours. The URL is a credential: give it only to that person and never log it.for: insuredreturns the insured’s pay-and-bind link where the market takes the insured’s own payment (Coterie today;409 insured_link_unavailableelsewhere). The first call needsinsured_emailand emails the link to the insured, copying the producer. Confirm the assumptions behind the quote withattest_assumptionsfirst, or it answers409 assumptions_unconfirmed.
The quote must be bindable now (bind.available on the quote read).
Where to go next
Section titled “Where to go next”Building an AI agent? The Agents guide covers the workflow, the rules, the MCP connector and the Hedge skill for Claude.
Follow many files with one poll of GET /broker/events, or webhooks. See
Notifications and events.
What every error means and whether to retry: Errors.
Build against carrier test systems first: Sandbox.