---
title: "Create a submission from documents and/or text (the portal's Upload documents)"
method: POST
path: "/broker/intake"
tags: ["Submissions"]
---

# Create a submission from documents and/or text (the portal's Upload documents)

`POST /broker/intake`

## Request

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

The API form of the portal's **Upload documents**. Send free text
(an email body, notes), documents (ACORDs, loss runs, supplements),
or both. Hedge reads them as the portal does (the insured, address,
NAICS, lines, effective date, locations), prefills a structured file
for **Hedge Instant Quote markets only** and returns the same
response as `POST /broker/submissions`: each market's state. Your
typed fields win over what Hedge read. Emails follow your brokerage's
notification settings; the defaults match the portal. The documents stay on the file and keep
feeding its prefill; identical files in one call are stored once.

When what Hedge read fits no instant market (or names no lines or
state) it returns 422 `no_instant_market` (or `missing_core`) with
`email_us` and `read` (what it could read), and creates nothing.

Requires `text`, `insured_name` or documents. Machine credentials
must name `producer_email`. `client_reference` and an
`Idempotency-Key` header make a retry return the saved file. Counts
toward the daily upload limit.

## Headers

- `Idempotency-Key` string

## Request body `multipart/form-data`

- object
  - `text` string: The risk as you would describe it in an email. Required unless insured_name is given.
  - `files` string[]: Up to 20 PDFs (ACORDs, loss runs, supplements), 15 MB each.
  - `insured_name` string
  - `effective_date` string, date
  - `lines_of_business` string: Comma-separated canonical slugs or common aliases (e.g. `gl,property`).
  - `primary_state` string: Primary risk state, 2-letter US code.
  - `producer_email` string: REQUIRED when authenticating with a machine credential; the active portal user this submission is attributed to.
  - `hold` boolean: Accepted and changes nothing for a connected app or machine credential.
  - `program_ids` string: Comma-separated Hedge Instant Quote program ids (default every one that fits).
  - `client_reference` string: Your reference; unique per brokerage (a repeat returns that file, 200).
  - `quote` boolean: Quote each market as soon as it is ready.

## Response `201`

Created; each instant market's state.

- IntakeCreated: Result of `POST /broker/intake`.
  - `submission_id` string, uuid, required
  - `state` string
  - `status_label` string, required
  - `marketing_status` 'matching' | 'awaiting_finalization' | 'null', nullable: Null for an instant-flow file (it never starts marketing).
  - `next_step` string, required
  - `client_reference` string, nullable
  - `automatic_quoting` boolean, nullable
  - `markets` FlowMarket[], nullable
    - `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
  - `documents` object[]: The originals stored on the submission, in upload order.
    - `id` string, uuid
    - `display_name` string
  - `applicant` object, required: What Hedge recorded for the insured — your fields, or the extractor's when you only sent text.
    - `insured_name` string, nullable
    - `dba_name` string, nullable
    - `entity_type` string, nullable
    - `business_phone` string, nullable
    - `business_email` string, nullable
    - `website` string, nullable
    - `naics` string, nullable
    - `nature_of_business` string, nullable
    - `contact_first_name` string, nullable
    - `contact_last_name` string, nullable
    - `contact_email` string, nullable
    - `contact_phone` string, nullable
    - `mailing_address` object, nullable
      - `line1` string
      - `line2` string, nullable
      - `city` string
      - `state` string
      - `zip` string
  - `warnings` string[]: Non-fatal notices (a file that was not stored, a background enqueue that needs attention, a replayed request).
  - `portal_url` string, uri, required

## Other responses

- `400`: A file is not a valid PDF/document
- `409`: Same Idempotency-Key already in flight
- `413`: A file is over the 15 MB limit
- `415`: Unsupported document type
- `422`: `{code: no_instant_market, email_us, read}` (nothing created); `{code: missing_core, fields, read}`; no text, insured_name or documents; missing producer_email for a machine credential; invalid date, state or line of business
- `429`: API client per-minute write or daily upload limit reached
- `503`: Text extraction is temporarily unavailable; your text is preserved

## Changes

- **2026-10-30** `0f8285056456`: 2 breaking, 1 warning, 7 info
  - the response property `marketing_status` became nullable for the status `201`
  - the response property `marketing_status` became optional 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 `client_reference`
  - …6 more
- **2026-09-20** `7928528d98b2`: 1 info
  - endpoint added

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