Create a submission for Hedge Instant Quote markets
const url = 'https://api.hedgespecialty.com/api/v1/broker/submissions';const options = { method: 'POST', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"applicant":{"insured_name":"example","dba_name":"example","entity_type":"example","fein_or_ssn":"example","nature_of_business":"example","date_business_started":"2026-04-15","business_start_year":1,"business_phone":"example","business_email":"example","website":"example","contact_first_name":"example","contact_last_name":"example","contact_title":"example","contact_phone":"example","contact_email":"example","naics":"example","sic":"example","gl_code":"example","mailing_address":{"line1":"example","line2":"example","city":"example","county":"example","state":"example","zip":"example","zip4":"example","country":"US"}},"narrative":"example","lines_of_business":["example"],"effective_date":"2026-04-15","primary_state":"example","producer_email":"example","insured_id":"2489E9AD-2EE2-8E00-8EC9-32D5F69181C0","locations":[{"location_number":1,"address":{"line1":"example","line2":"example","city":"example","county":"example","state":"example","zip":"example","zip4":"example","country":"US"},"description_of_operations":"example","employees_full_time":1,"employees_part_time":1,"annual_revenue_at_location":1}],"requested_coverages":["example"],"property_tiv_total":1,"auto_vehicle_count":1,"wc_total_annual_payroll":1,"prior_carriers":[{"coverage_category":"example","carrier_name":"example","policy_number":"example","effective_date":"2026-04-15","expiration_date":"2026-04-15"}],"line_target_premiums":{"additionalProperty":1},"structure_to_target":false,"hold":false,"program_ids":["2489E9AD-2EE2-8E00-8EC9-32D5F69181C0"],"shared_answers":{},"answers":{"additionalProperty":{}},"client_reference":"example","quote":false,"mode":"rater","partner_program_ids":["2489E9AD-2EE2-8E00-8EC9-32D5F69181C0"],"partner_reference":"example"}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url https://api.hedgespecialty.com/api/v1/broker/submissions \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "applicant": { "insured_name": "example", "dba_name": "example", "entity_type": "example", "fein_or_ssn": "example", "nature_of_business": "example", "date_business_started": "2026-04-15", "business_start_year": 1, "business_phone": "example", "business_email": "example", "website": "example", "contact_first_name": "example", "contact_last_name": "example", "contact_title": "example", "contact_phone": "example", "contact_email": "example", "naics": "example", "sic": "example", "gl_code": "example", "mailing_address": { "line1": "example", "line2": "example", "city": "example", "county": "example", "state": "example", "zip": "example", "zip4": "example", "country": "US" } }, "narrative": "example", "lines_of_business": [ "example" ], "effective_date": "2026-04-15", "primary_state": "example", "producer_email": "example", "insured_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "locations": [ { "location_number": 1, "address": { "line1": "example", "line2": "example", "city": "example", "county": "example", "state": "example", "zip": "example", "zip4": "example", "country": "US" }, "description_of_operations": "example", "employees_full_time": 1, "employees_part_time": 1, "annual_revenue_at_location": 1 } ], "requested_coverages": [ "example" ], "property_tiv_total": 1, "auto_vehicle_count": 1, "wc_total_annual_payroll": 1, "prior_carriers": [ { "coverage_category": "example", "carrier_name": "example", "policy_number": "example", "effective_date": "2026-04-15", "expiration_date": "2026-04-15" } ], "line_target_premiums": { "additionalProperty": 1 }, "structure_to_target": false, "hold": false, "program_ids": [ "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0" ], "shared_answers": {}, "answers": { "additionalProperty": {} }, "client_reference": "example", "quote": false, "mode": "rater", "partner_program_ids": [ "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0" ], "partner_reference": "example" }'With a connected app or machine credential this creates a structured
file that reaches Hedge Instant Quote markets only, as the
portal wizard does. The create first runs the appetite read
(POST /broker/appetite/instant) on these facts: when no instant
market fits (or none of program_ids does) it returns 422
no_instant_market with email_us, and nothing is created.
Otherwise the response is the file’s state: each market starts
preparing (usually under a minute); poll
GET /broker/submissions/{id}/instant-quotes, answer gaps with
PATCH .../answers and request quotes with POST .../quote (or
create with quote: true). Emails follow your brokerage’s notification
settings; the defaults match the portal. Required: applicant.insured_name, narrative,
lines_of_business and a state (primary_state or the mailing
address’s): 422 missing_core names what is absent.
client_reference (unique per brokerage) returns the existing file
(200) when used again. Idempotency-Key also works: a retried
create with the same key within 24h replays instead of creating a
duplicate; a concurrent duplicate returns 409, retry shortly.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Header Parameters
Section titled “Header Parameters”Request Bodyrequired
Section titled “Request Bodyrequired”object
object
Legal entity type, e.g. llc, corporation, sole_proprietor.
FEIN, or SSN for a sole proprietor.
The year the business started, when the exact date is not known.
The producer’s email. Strongly recommended: Hedge emails the clearance (every market being tried), any questions, and quotes here; the same thread an email broker gets.
Line1, city, state and zip are required together.
object
Operations description of the risk, what the business does, size, anything an underwriter should know. Required; appetite matching depends on it.
Canonical slugs (e.g. commercial_general_liability) or common aliases (gl, wc).
Primary risk state, 2-letter US code (normalized to uppercase). When the applicant mailing address also carries a state the two must agree: the request 422s on a conflict, with a message that says exactly what to fix. Omit it to use the mailing address state.
REQUIRED when authenticating with a machine credential, the active portal user this submission is attributed to.
Optional id of an existing insured from GET /broker/insureds; links the new submission to that client’s account (repeat business, a new line for an existing client). Must belong to your brokerage; an unknown or foreign id returns 404.
Risk locations (ACORD 125 premises). Location numbers must be unique.
object
Unique per submission.
Line1, city, state and zip are required together.
object
Explicit narrow coverage intent as canonical slugs (e.g. auto_physical_damage, motor_truck_cargo). Omit when unstated; an empty list means the broker explicitly selected none.
Total insured property value, whole dollars.
Total annual payroll, whole dollars.
Expiring or prior carriers per line; drives loss-run requests.
object
Canonical line slug or common alias.
Broker-stated target annual premium per line slug, whole dollars. Non-positive values are dropped.
object
Ask Hedge to structure options (limits, deductibles) to hit the target premiums.
Accepted and changes nothing for a connected app or machine
credential: its file never starts marketing (it quotes Hedge
Instant Quote markets through /answers and /quote).
The Hedge Instant Quote programs to quote (from
POST /broker/appetite/instant). Default: every one that fits.
A program that doesn’t fit returns 422 not_instant.
Answers by canonical key (a question’s key in
POST /broker/requirements, e.g. annual_revenue): written to the
file once, and every market that asks the question is prefilled
from it. A key no chosen market asks is ignored and named in
warnings[] (the file is still created). A value of the wrong
type returns 422 invalid_answers and nothing is created.
object
One market’s own answers: {program_id: {question_id: value}}
(a question’s id; its canonical key works too). Applied as
soon as that market is prepared.
object
object
Your own reference for the file. Unique per brokerage: a create
carrying a reference already used returns that file (200)
instead of creating another. Takes precedence over
Idempotency-Key.
Quote each market as soon as it is ready (now, or after later answers).
Partner integrations only (an acting-as partner token; anyone
else gets 403). rater quotes exactly partner_program_ids and
no other market. The file is always held until finalize, and
lines_of_business and primary_state are required. A live
submission for the same insured returns 409 hedge_file_exists
with its submission_id, except your own rater submissions
(one per coverage) where no chosen program’s market already
quotes one of its lines and no carrier application is shared.
Different markets may quote the same line on sibling
submissions. When your own rater submission collides, the 409
also lists programs: each colliding program_id, its
reasons (market_line_on_live_file,
carrier_application_on_live_file, lines_unknown) and the
submission_ids it collides with. Untick those and retry.
With mode: rater only: the exact programs to quote (API,
portal or email programs; a portal-robot program must be
qualified on Hedge’s executor), at most one per market and
channel for a requested line. Each refused program is named
with its reasons in a 422.
With mode: rater only, the partner’s own id for this quote
request; echoed on the file’s start event.
Responses
Section titled “Responses”client_reference already made a file: that file, as it stands
object
structured_v1 for an instant-flow file.
Null for a file a connected app or machine credential creates (it
never starts marketing). Otherwise matching when the run started
on create, awaiting_finalization when held.
The call to make next, e.g. GET /broker/submissions/{id}/instant-quotes.
Created with quote: true.
Each Hedge Instant Quote market on the file and where it stands (instant-flow files).
One Hedge Instant Quote program on the file and where it stands.
object
preparing: Hedge is preparing the application (poll). needs_answers: answer missing[]. ready: request the quote. quoting: requested. quoted: quote is set. declined / not_a_fit: closed, with reason.
Plain words: Preparing · Needs 2 answers · Ready to quote · Quoting · Quoted · $1,234.00 · Declined · reason · Not a fit · reason.
object
The canonical key (what shared_answers takes); null for a file-level gap.
The market’s own question id (what answers[program_id] takes).
Plain-language note on what to do. A gap in the business’s own name, address, contact or effective date names the call that sets it: PATCH /broker/submissions/{id}/business and its field.
object
Dollars.
Dollars
A class Hedge picked, or ranked for an unanswered class question, that you must confirm (the same ranking POST /broker/appetite/instant returns). Confirm it with confirm_suggestions, by answering with the same value, or answer another.
object
Non-fatal notices about an already-created submission (e.g. a background enqueue that needs attention).
Set when this create repeated a live submission for the same insured
from the last day and landed on it as an update instead of opening a
second file; submission_id is that file.
On a merged create from a portal session, the requested lines the live file did not have, now added to it (their instant markets start preparing). Empty otherwise.
Example
{ "marketing_status": "matching", "markets": [ { "state": "preparing", "quote": { "kind": "quote" } } ]}Created
object
structured_v1 for an instant-flow file.
Null for a file a connected app or machine credential creates (it
never starts marketing). Otherwise matching when the run started
on create, awaiting_finalization when held.
The call to make next, e.g. GET /broker/submissions/{id}/instant-quotes.
Created with quote: true.
Each Hedge Instant Quote market on the file and where it stands (instant-flow files).
One Hedge Instant Quote program on the file and where it stands.
object
preparing: Hedge is preparing the application (poll). needs_answers: answer missing[]. ready: request the quote. quoting: requested. quoted: quote is set. declined / not_a_fit: closed, with reason.
Plain words: Preparing · Needs 2 answers · Ready to quote · Quoting · Quoted · $1,234.00 · Declined · reason · Not a fit · reason.
object
The canonical key (what shared_answers takes); null for a file-level gap.
The market’s own question id (what answers[program_id] takes).
Plain-language note on what to do. A gap in the business’s own name, address, contact or effective date names the call that sets it: PATCH /broker/submissions/{id}/business and its field.
object
Dollars.
Dollars
A class Hedge picked, or ranked for an unanswered class question, that you must confirm (the same ranking POST /broker/appetite/instant returns). Confirm it with confirm_suggestions, by answering with the same value, or answer another.
object
Non-fatal notices about an already-created submission (e.g. a background enqueue that needs attention).
Set when this create repeated a live submission for the same insured
from the last day and landed on it as an update instead of opening a
second file; submission_id is that file.
On a merged create from a portal session, the requested lines the live file did not have, now added to it (their instant markets start preparing). Empty otherwise.
Example
{ "marketing_status": "matching", "markets": [ { "state": "preparing", "quote": { "kind": "quote" } } ]}Same Idempotency-Key or client_reference already in flight
{code: no_instant_market, email_us}: nothing fits and nothing was created; missing_core (fields); not_instant (program_ids); invalid_answers (errors); or a validation message
Daily create limit reached