---
title: "Answer the file's gaps (shared and per market)"
method: PATCH
path: "/broker/submissions/{submission_id}/answers"
tags: ["Requirements"]
---

# Answer the file's gaps (shared and per market)

`PATCH /broker/submissions/{submission_id}/answers`

## Request

- Base URL: `https://api.hedgespecialty.com/api/v1`
- URL: `https://api.hedgespecialty.com/api/v1/broker/submissions/{submission_id}/answers`
- 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`

`shared_answers` by canonical key are written to the file and refill
every market that asks them (a later answer corrects an earlier one,
as in the portal; a key no market on the file asks is ignored and
named in `warnings[]`); `answers[program_id]` go to that
market's application (a question's `id`, or its canonical `key`; a
row's question as `rows[record_id].field`, or inside a row's rows
as `rows[record_id].inner[record_id].field`, exactly as `missing[].id`
names it, e.g. EMPLOYERS' class payroll). A market still
`preparing` takes its answers once prepared. `confirm_suggestions:
true` confirms each class Hedge suggested (`suggested[]`) as it
stands; to pick another class, answer it.

All or nothing: any refused answer returns 422 `invalid_answers`
with `errors[]` (`program_id`, `key`, `message`) and nothing is
saved. Submit scope; `producer_email` with a machine credential.

## Path parameters

- `submission_id` string, uuid, required

## Request body

- object
  - `shared_answers` object
  - `answers` object
  - `confirm_suggestions` boolean
  - `producer_email` string

## Response `200`

The file's state after the answers

- FileState
  - `submission_id` string, uuid, required
  - `client_reference` string, nullable
  - `portal_url` string, required
  - `automatic_quoting` boolean, required: Created with `quote: true`: each market quotes as soon as it is ready.
  - `markets` FlowMarket[], required
    - `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[], required
    - `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[], required

## Other responses

- `409`: `not_instant_flow`: the file was not created through this flow
- `422`: `invalid_answers` with `errors[]`

## Changes

- **2026-10-30** `0f8285056456`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/hedgespecialty/apis/hedge-submission-api/changes/broker/submissions/:submission_id/answers/patch.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)