Skip to content

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 link

Before 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.

  1. Install and sign in.

    Terminal window
    npm i -g hedge-broker
    hedge login # device code, in your browser
    hedge login --client-id bac_... --client-secret bas_... # or an API key, for scripts

    Add --sandbox to any command to use the sandbox. Homebrew and a one-line installer are in the CLI guide.

  2. Check appetite.

    Terminal window
    hedge appetite "Residential landscaping and lawn care, 6 employees, no tree work over 15 ft" \
    --state CA --lines gl --naics 561730

    This lists the instant markets that will quote the risk, each with its program_id and, where the carrier picks its class from a list, the class Hedge would use. When none fits, it prints the email_us block instead: the address and what to include.

  3. Read the requirements.

    Terminal window
    hedge requirements --state CA --lines gl --naics 561730 \
    --description "Residential landscaping and lawn care"

    Without --programs it uses every instant market appetite returned. You get the file’s core fields, then each market’s own questions, per market and not deduplicated. A question’s key is its canonical fact (annual_revenue): answer it once and every market that asks it is filled. Its id is the market’s own question id, for answers that belong to one market.

  4. 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.com

    Send 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-reference returns the existing file instead of creating another, so a retry is safe.

  5. Follow it and answer the gaps.

    Terminal window
    hedge status <submission-id> --wait
    hedge answer <submission-id> --confirm-suggestions

    To correct a fact later, answer it again:

    Terminal window
    hedge answer <submission-id> --set annual_revenue=900000

    Each market starts preparing and settles within about a minute into needs_answers (with what is missing), ready, or not_a_fit. Hedge suggests a value where a carrier picks from its own list (a class, for example); --confirm-suggestions confirms every suggestion as it stands, or answer one with another value. --set key=value answers by canonical key and corrects an earlier answer; --set <program-id>:<id>=value answers one market’s own question.

  6. Request quotes.

    Terminal window
    hedge quote <submission-id> --wait

    Every ready market is requested; the rest come back with what they still need. Create with --quote and each market quotes on its own as soon as it is ready.

  7. Read the quotes and download the PDFs.

    Terminal window
    hedge quotes <submission-id> --download ./quotes

    Pricing, 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.

  8. 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.example emails the insured their pay-and-bind link.

Add --json to any command for the API’s own JSON.

Every step is one REST call under https://api.hedgespecialty.com/api/v1 with a bearer token ($HEDGE_TOKEN below; see Authentication).

Terminal window
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"
]
}
}
Terminal window
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].

Terminal window
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.

Poll every 5 to 10 seconds while a market is preparing:

Terminal window
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:

Terminal window
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:

Terminal window
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.

Skip this when you created the file with "quote": true.

Terminal window
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.

Terminal window
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.

Terminal window
curl "https://api.hedgespecialty.com/api/v1/broker/finalized-documents/5b1e…/pdf" \
-H "Authorization: Bearer $HEDGE_TOKEN" -o quote.pdf
Terminal window
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: insured returns the insured’s pay-and-bind link where the market takes the insured’s own payment (Coterie today; 409 insured_link_unavailable elsewhere). The first call needs insured_email and emails the link to the insured, copying the producer. Confirm the assumptions behind the quote with attest_assumptions first, or it answers 409 assumptions_unconfirmed.

The quote must be bindable now (bind.available on the quote read).

Building an AI agent? The Agents guide covers the workflow, the rules, the MCP connector and the Hedge skill for Claude.