Skip to content

Create a submission for Hedge Instant Quote markets

POST
/broker/submissions
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.

Idempotency-Key
string
Media typeapplication/json
object
applicant
required
object
insured_name
required
string
<= 256 characters
dba_name
string
entity_type

Legal entity type, e.g. llc, corporation, sole_proprietor.

string
fein_or_ssn

FEIN, or SSN for a sole proprietor.

string
nature_of_business
string
date_business_started
string format: date
business_start_year

The year the business started, when the exact date is not known.

integer
business_phone
string
business_email
string
website
string
contact_first_name
string
contact_last_name
string
contact_title
string
<= 128 characters
contact_phone
string
contact_email

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.

string
naics
string
sic
string
<= 64 characters
gl_code
string
<= 64 characters
mailing_address

Line1, city, state and zip are required together.

object
line1
required
string
line2
string
city
required
string
county
string
state
required
string
>= 2 characters <= 2 characters
zip
required
string
zip4
string
country
string
default: US
narrative
required

Operations description of the risk, what the business does, size, anything an underwriter should know. Required; appetite matching depends on it.

string
lines_of_business

Canonical slugs (e.g. commercial_general_liability) or common aliases (gl, wc).

Array<string>
effective_date
string format: date
primary_state

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.

string
>= 2 characters <= 2 characters
producer_email

REQUIRED when authenticating with a machine credential, the active portal user this submission is attributed to.

string
insured_id

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.

string format: uuid
locations

Risk locations (ACORD 125 premises). Location numbers must be unique.

Array<object>
<= 250 items
object
location_number
required

Unique per submission.

integer
>= 1
address
required

Line1, city, state and zip are required together.

object
line1
required
string
line2
string
city
required
string
county
string
state
required
string
>= 2 characters <= 2 characters
zip
required
string
zip4
string
country
string
default: US
description_of_operations
string
<= 10000 characters
employees_full_time
integer
employees_part_time
integer
annual_revenue_at_location
number
requested_coverages

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.

Array<string>
property_tiv_total

Total insured property value, whole dollars.

integer
auto_vehicle_count
integer
wc_total_annual_payroll

Total annual payroll, whole dollars.

integer
prior_carriers

Expiring or prior carriers per line; drives loss-run requests.

Array<object>
object
coverage_category

Canonical line slug or common alias.

string
carrier_name
string
policy_number
string
effective_date
string format: date
expiration_date
string format: date
line_target_premiums

Broker-stated target annual premium per line slug, whole dollars. Non-positive values are dropped.

object
key
additional properties
integer
>= 1
structure_to_target

Ask Hedge to structure options (limits, deductibles) to hit the target premiums.

boolean
hold

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

boolean
program_ids

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.

Array<string>
>= 1 items <= 30 items
shared_answers

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
key
additional properties
any
answers

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
key
additional properties
object
key
additional properties
any
client_reference

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.

string
>= 1 characters <= 128 characters
quote

Quote each market as soon as it is ready (now, or after later answers).

boolean
mode

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.

string
Allowed values: rater
partner_program_ids

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.

Array<string>
>= 1 items <= 40 items unique items
partner_reference

With mode: rater only, the partner’s own id for this quote request; echoed on the file’s start event.

string
<= 128 characters

client_reference already made a file: that file, as it stands

Media typeapplication/json
object
submission_id
string format: uuid
application_workflow_version

structured_v1 for an instant-flow file.

string
state
string
status_label
string
marketing_status

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.

string
nullable
Allowed values: matching awaiting_finalization
next_step

The call to make next, e.g. GET /broker/submissions/{id}/instant-quotes.

string
client_reference
string
nullable
portal_url
string
nullable
automatic_quoting

Created with quote: true.

boolean
nullable
markets

Each Hedge Instant Quote market on the file and where it stands (instant-flow files).

Array<object>
nullable

One Hedge Instant Quote program on the file and where it stands.

object
program_id
required
string format: uuid
program
required
string
market_id
string format: uuid
nullable
market
required
string
lines
Array<string>
state
required

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.

string
Allowed values: preparing needs_answers ready quoting quoted declined not_a_fit
status_label
required

Plain words: Preparing · Needs 2 answers · Ready to quote · Quoting · Quoted · $1,234.00 · Declined · reason · Not a fit · reason.

string
missing
required
Array<object>
object
key

The canonical key (what shared_answers takes); null for a file-level gap.

string
nullable
id

The market’s own question id (what answers[program_id] takes).

string
nullable
label
required
string
message
required

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.

string
reason
string
nullable
quote
object
quote_id
required
string
kind
required
string
Allowed values: quote indication
premium

Dollars.

number
nullable
total

Dollars

number
nullable
suggested
Array<object>
nullable

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
program_id
required
string format: uuid
key
string
nullable
id
required
string
label
required
string
value
required
value_label
string
nullable
message
required
string
warnings

Non-fatal notices about an already-created submission (e.g. a background enqueue that needs attention).

Array<string>
merged_into

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.

string format: uuid
nullable
lines_added

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.

Array<string>
Example
{
"marketing_status": "matching",
"markets": [
{
"state": "preparing",
"quote": {
"kind": "quote"
}
}
]
}

Created

Media typeapplication/json
object
submission_id
string format: uuid
application_workflow_version

structured_v1 for an instant-flow file.

string
state
string
status_label
string
marketing_status

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.

string
nullable
Allowed values: matching awaiting_finalization
next_step

The call to make next, e.g. GET /broker/submissions/{id}/instant-quotes.

string
client_reference
string
nullable
portal_url
string
nullable
automatic_quoting

Created with quote: true.

boolean
nullable
markets

Each Hedge Instant Quote market on the file and where it stands (instant-flow files).

Array<object>
nullable

One Hedge Instant Quote program on the file and where it stands.

object
program_id
required
string format: uuid
program
required
string
market_id
string format: uuid
nullable
market
required
string
lines
Array<string>
state
required

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.

string
Allowed values: preparing needs_answers ready quoting quoted declined not_a_fit
status_label
required

Plain words: Preparing · Needs 2 answers · Ready to quote · Quoting · Quoted · $1,234.00 · Declined · reason · Not a fit · reason.

string
missing
required
Array<object>
object
key

The canonical key (what shared_answers takes); null for a file-level gap.

string
nullable
id

The market’s own question id (what answers[program_id] takes).

string
nullable
label
required
string
message
required

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.

string
reason
string
nullable
quote
object
quote_id
required
string
kind
required
string
Allowed values: quote indication
premium

Dollars.

number
nullable
total

Dollars

number
nullable
suggested
Array<object>
nullable

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
program_id
required
string format: uuid
key
string
nullable
id
required
string
label
required
string
value
required
value_label
string
nullable
message
required
string
warnings

Non-fatal notices about an already-created submission (e.g. a background enqueue that needs attention).

Array<string>
merged_into

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.

string format: uuid
nullable
lines_added

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.

Array<string>
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