HEhedgespecialty
Submissions

Create a submission for Hedge Instant Quote markets

Changed on

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.

post/broker/submissions

Request

  • Base URL
    https://api.hedgespecialty.com/api/v1
  • 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

Headers

Idempotency-Keystring

Request body

narrativestring required

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

lines_of_businessstring[]

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

effective_datestring date
primary_statestring

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_emailstring

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

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

requested_coveragesstring[]

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_totalinteger

Total insured property value, whole dollars.

auto_vehicle_countinteger
wc_total_annual_payrollinteger

Total annual payroll, whole dollars.

line_target_premiumsobject

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

structure_to_targetboolean

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

holdboolean

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_idsstring[]

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_answersobject

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.

answersobject

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_referencestring

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.

quoteboolean

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_idsstring[]

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_referencestring

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

Response

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

submission_idstring uuid
application_workflow_versionstring

structured_v1 for an instant-flow file.

statestring
status_labelstring
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_stepstring

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

client_referencestring nullable
portal_urlstring nullable
automatic_quotingboolean nullable

Created with quote: true.

warningsstring[]

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

merged_intostring 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_addedstring[]

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.

Changes

  • db75fb8812f5Revision changes
    • info

      added the non-success response with the status

  • 0f8285056456Revision changes
    • breaking

      the response property became nullable for the status

    • warning

      added the new undefined enum value to the response property for the response status

    • info

      added the new optional request property

    • info

      added the new optional request property

    • info

      added the new optional request property

    • info

      added the new optional request property

    • info

      added the new optional request property

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the success response with the status