Poll a submission's market events (quotes, declines, progress)

GET

/broker/submissions/{submission_id}/events

const url = 'https://api.hedgespecialty.com/api/v1/broker/submissions/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/events?limit=50';
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request GET \
  --url 'https://api.hedgespecialty.com/api/v1/broker/submissions/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/events?limit=50' \
  --header 'Authorization: Bearer <token>'

The change feed for one submission; poll it to surface outcomes that arrive hours after submit on email/portal markets (a carrier quoting back, declining, or a market being engaged) without diffing the detail view. Events are ordered oldest-first with a stable cursor.

The end-of-stream signal is the cursor, never page length. A non-null next_cursor means more events may exist: store it and poll again with since=next_cursor until you receive a null. A page may hold fewer than limit events; or none at all; with a non-null cursor (internal audit rows are scanned but never returned, and a bounded per-request scan can stop early); never treat a short page as the tail. next_cursor is null only when the request proved your position is the tail of the currently-visible stream; resume later polls from your last non-null cursor. Event ids are stable, so re-reading an older cursor is always safe (dedupe by id).

type is a closed set:

market_attached; a market was engaged (sent to underwriter).
quote_received; a quote was received and relayed to you (the quote itself is on the submission detail / proposal).
status_changed; other movement, e.g. quote in progress or a market re-engaged.
declined, withdrawn, blocked; terminal outcomes for a market; detail carries the recorded rationale when there is one.
bound; coverage placed with that market.

Each event: {id, type, occurred_at, market: {name, lines, lane_id, category}, status, status_label, detail?}. category is the market’s Hedge category (instant_quote, binding, specialty) and lane_id matches rail.lanes[].submission_market_id. status/status_label use the same vocabulary as the submission detail’s markets roll-up. Events reflect what is currently visible to your brokerage; the same rules as the detail view (markets Hedge has actually engaged; quotes only once relayed).

Because visibility is evaluated at read time while the cursor is a position over the underlying log, a market that becomes visible later (e.g. its quote gets relayed after your cursor passed its early rows) can enter your stream mid-history; a quote_received without a preceding market_attached. Treat each event as self-contained rather than assuming lifecycle completeness, and read GET /broker/submissions/{submission_id} for authoritative current state. Re-reading from an older (or empty) cursor replays the full currently-visible history when you need to backfill.

Authorizations

brokerOAuth

Parameters

Path Parameters

submission_id

required

string format: uuid

Query Parameters

since

string

Opaque cursor from a previous page’s next_cursor; returns events strictly after it. Omit to read from the beginning.

limit

integer

default: 50

Max events per page (internal audit rows are not counted). Values outside [1, 100] are clamped, never rejected.

Responses

200

One page of events plus the follow-up cursor

application/json

object

events

Array<object>

object

string format: uuid

type

string

Allowed values: market_attached quote_received status_changed declined withdrawn blocked bound

occurred_at

string format: date-time

market

object

name

string

lines

Array<string>

lane_id

The market lane (same id as rail.lanes[].submission_market_id).

string format: uuid

nullable

category

The Hedge category of a market program, derived from how Hedge submits to it. instant_quote (“Hedge Instant Quote”): carrier API, Hedge fills gaps with favorable assumptions and quotes in minutes; every assumption is listed for the retail agent to confirm before bind. binding (“Hedge Binding”): carrier portal, Hedge quotes on your behalf. specialty (“Hedge Specialty”): email to an underwriter; completed ACORDs, program supplements and loss runs are needed and a human reads them, so Hedge does not assume.

string

Allowed values: instant_quote binding specialty

status

string

status_label

string

detail

string

nullable

next_cursor

string

nullable

Example

{
  "events": [
    {
      "type": "market_attached",
      "market": {
        "category": "instant_quote"
      }
    }
  ]
}

404

Not found (or not your brokerage’s)

422

Invalid since cursor