Skip to content
Hedge Developer Docs

Create a submission

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_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 }'

Creates the submission and starts the run: appetite match, the structured clearance email to the producer, lanes opened, the instant-quote markets quoted on recorded favorable assumptions. Documents uploaded afterwards flow into the open lanes. Pass hold: true to defer the run until finalize; an expected_document_sha256s manifest also holds (you declared originals are still coming).

The response’s marketing_status says which happened (matching or awaiting_finalization) and next_step names the call to make.

Supports an Idempotency-Key header: a retried create with the same key within 24h replays the original response 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”
Idempotency-Key
string

Request Bodyrequired

Section titled “Request Bodyrequired”
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_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

Defer the run. false (default) starts marketing as soon as the create commits, appetite match, clearance email to the producer, lanes opened, instant-quote markets quoted. true holds the draft until POST /broker/submissions/{id}/finalize releases it (attach documents and answer requirements first).

boolean

Responses

Section titled “Responses”

201

Section titled “201”

Created

Media typeapplication/json
object
submission_id
string format: uuid
state
string
status_label
string
marketing_status

matching when the run started on create; awaiting_finalization when held (call finalize to release).

string
Allowed values: matching awaiting_finalization
next_step

The call to make next, e.g. GET /broker/submissions/{id}/markets or POST /broker/submissions/{id}/finalize.

string
warnings

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

Array<string>
Example
{
  "marketing_status": "matching"
}

409

Section titled “409”

Same Idempotency-Key already in flight

422

Section titled “422”

Validation error (message says exactly what to fix)

429

Section titled “429”

Daily create limit reached