--- title: "Create a submission for Hedge Instant Quote markets" method: POST path: "/broker/submissions" tags: ["Submissions"] --- # Create a submission for Hedge Instant Quote markets `POST /broker/submissions` ## Request - Base URL: `https://api.hedgespecialty.com/api/v1` - URL: `https://api.hedgespecialty.com/api/v1/broker/submissions` - Auth: OAuth 2 - Authorization code: `https://api.hedgespecialty.com/api/v1/oauth/authorize` - Client credentials - Token URL: `https://api.hedgespecialty.com/api/v1/oauth/token` 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. ## Headers - `Idempotency-Key` string ## Request body - SubmissionCreate - `applicant` Applicant, required - `insured_name` string, required - `dba_name` string - `entity_type` string: Legal entity type, e.g. llc, corporation, sole_proprietor. - `fein_or_ssn` string: FEIN, or SSN for a sole proprietor. - `nature_of_business` string - `date_business_started` string, date - `business_start_year` integer: The year the business started, when the exact date is not known. - `business_phone` string - `business_email` string - `website` string - `contact_first_name` string - `contact_last_name` string - `contact_title` string - `contact_phone` string - `contact_email` string: 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. - `naics` string - `sic` string - `gl_code` string - `mailing_address` Address: line1, city, state and zip are required together. - `line1` string, required - `line2` string - `city` string, required - `county` string - `state` string, required - `zip` string, required - `zip4` string - `country` string - `narrative` string, required: Operations description of the risk, what the business does, size, anything an underwriter should know. Required; appetite matching depends on it. - `lines_of_business` string[]: Canonical slugs (e.g. commercial_general_liability) or common aliases (gl, wc). - `effective_date` string, date - `primary_state` string: 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. - `producer_email` string: REQUIRED when authenticating with a machine credential, the active portal user this submission is attributed to. - `insured_id` string, uuid: 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. - `locations` Location[]: Risk locations (ACORD 125 premises). Location numbers must be unique. - `location_number` integer, required: Unique per submission. - `address` Address, required: line1, city, state and zip are required together. - `line1` string, required - `line2` string - `city` string, required - `county` string - `state` string, required - `zip` string, required - `zip4` string - `country` string - `description_of_operations` string - `employees_full_time` integer - `employees_part_time` integer - `annual_revenue_at_location` number - `requested_coverages` string[]: 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. - `property_tiv_total` integer: Total insured property value, whole dollars. - `auto_vehicle_count` integer - `wc_total_annual_payroll` integer: Total annual payroll, whole dollars. - `prior_carriers` PriorCarrier[]: Expiring or prior carriers per line; drives loss-run requests. - `coverage_category` string: Canonical line slug or common alias. - `carrier_name` string - `policy_number` string - `effective_date` string, date - `expiration_date` string, date - `line_target_premiums` object: Broker-stated target annual premium per line slug, whole dollars. Non-positive values are dropped. - `structure_to_target` boolean: Ask Hedge to structure options (limits, deductibles) to hit the target premiums. - `hold` boolean: 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`). - `program_ids` string[]: 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`. - `shared_answers` object: 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. - `answers` 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. - `client_reference` string: 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` boolean: Quote each market as soon as it is `ready` (now, or after later answers). - `mode` 'rater': 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. - `partner_program_ids` string[]: 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. - `partner_reference` string: With `mode: rater` only, the partner's own id for this quote request; echoed on the file's start event. ## Response `200` `client_reference` already made a file: that file, as it stands - SubmissionCreated - `submission_id` string, uuid - `application_workflow_version` string: `structured_v1` for an instant-flow file. - `state` string - `status_label` string - `marketing_status` 'matching' | 'awaiting_finalization' | 'null', nullable: 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. - `next_step` string: The call to make next, e.g. `GET /broker/submissions/{id}/instant-quotes`. - `client_reference` string, nullable - `portal_url` string, nullable - `automatic_quoting` boolean, nullable: Created with `quote: true`. - `markets` FlowMarket[], nullable: Each Hedge Instant Quote market on the file and where it stands (instant-flow files). - `program_id` string, uuid, required - `program` string, required - `market_id` string, uuid, nullable - `market` string, required - `lines` string[] - `state` 'preparing' | 'needs_answers' | 'ready' | 'quoting' | 'quoted' | 'declined' | 'not_a_fit', 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`. - `status_label` string, required: Plain words: Preparing · Needs 2 answers · Ready to quote · Quoting · Quoted · $1,234.00 · Declined · reason · Not a fit · reason. - `missing` FlowMissing[], required - `key` string, nullable: The canonical key (what `shared_answers` takes); null for a file-level gap. - `id` string, nullable: The market's own question id (what `answers[program_id]` takes). - `label` string, required - `message` string, 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. - `reason` string, nullable - `quote` FlowQuote - `quote_id` string, required - `kind` 'quote' | 'indication', required - `premium` number, nullable: Dollars. - `total` number, nullable: Dollars - `suggested` FlowSuggestion[], nullable - `program_id` string, uuid, required - `key` string, nullable - `id` string, required - `label` string, required - `value` unknown, required - `value_label` string, nullable - `message` string, required - `warnings` string[]: Non-fatal notices about an already-created submission (e.g. a background enqueue that needs attention). - `merged_into` string, uuid, nullable: 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. - `lines_added` string[]: 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. ## Other responses - `201`: Created - `409`: Same Idempotency-Key or client_reference already in flight - `422`: `{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 - `429`: API client per-minute write limit reached - `503`: `{code: setup_incomplete, submission_id}`: the file exists but its markets weren't set up. Retry the same request: the same `client_reference` or `Idempotency-Key` lands on that file and finishes it. ## Changes - **2026-10-30** `db75fb8812f5`: 1 info - added the non-success response with the status `503` - **2026-10-30** `0f8285056456`: 1 breaking, 1 warning, 12 info - the response property `marketing_status` became nullable for the status `201` - added the new `undefined` enum value to the `marketing_status` response property for the response status `201` - added the new optional request property `answers` - added the new optional request property `client_reference` - …10 more - **2026-10-22** `f51fe7503e9c`: 1 info - added the new optional request property `applicant/business_start_year` - **2026-10-10** `7c21970d5f33`: 2 info - added the optional property `lines_added` to the response with the `201` status - added the optional property `merged_into` to the response with the `201` status - **2026-09-28** `3156f892e627`: 3 info - added the new optional request property `mode` - added the new optional request property `partner_program_ids` - added the new optional request property `partner_reference` [Operation history](https://skmtc.dev/hedgespecialty/apis/hedge-submission-api/changes/broker/submissions/post.md) --- [API](https://skmtc.dev/hedgespecialty/apis/hedge-submission-api.md) - [All operations](https://skmtc.dev/hedgespecialty/apis/hedge-submission-api/llms.txt) - [OpenAPI document](https://skmtc.dev/hedgespecialty/apis/hedge-submission-api/revisions/beefa9cdc11c?raw)