---
title: "Poll the delegated umbrella session so the user can stay in chat."
method: POST
path: "/api/agent/umbrella/status"
---

# Poll the delegated umbrella session so the user can stay in chat.

`POST /api/agent/umbrella/status`

## Request

- Base URL: `https://api.coveragecat.com`
- URL: `https://api.coveragecat.com/api/agent/umbrella/status`
- Auth: HTTP bearer

Returns the current chat-manageable state for the delegated umbrella session, including quote selection, bind-stage follow-up questions, declarations-upload, declarations-review, payment, waiting-on-carrier, info-requested, blocked, and bound states. Chosen and waiting responses may include `offers_url` so the user can review the selected offer on Coverage Cat without leaving the normal workflow. If the session is back at `ready_for_review`, render the same single review page described on the draft endpoint. When `documents_pending_review` includes `poll_after_seconds`, wait that long before polling again unless the user asks for an update sooner. PaymentTransition: follow `chosen -> documents_needed -> documents_pending_review -> payment_needed -> waiting_on_carrier -> bound`. For Monoline and Markel, `documents_pending_review` means Coverage Cat has the declarations upload on file and is processing the chosen offer; `payment_needed` usually appears within about 5-10 minutes and includes a secure `payment_url`. Sandbox delegated umbrella sessions use this endpoint to rehearse the mocked draft/review/quote loop after offers are returned.

PaymentTransition: follow `chosen -> documents_needed -> documents_pending_review -> payment_needed -> waiting_on_carrier -> bound`. For Monoline and Markel, `documents_pending_review` means Coverage Cat has the declarations upload on file and is processing the chosen offer with the insurer; `payment_needed` usually appears within about 5-10 minutes and means the current checkout price shown came directly from the insurer while Coverage Cat is down to final declarations verification before charging the card, alongside a secure `payment_url`.

## Headers

- `Coverage-Cat-API-Version` 'v1'
- `Idempotency-Key` string

## Request body

- object
  - `sandbox` boolean: Optional mocked-mode flag. Once a delegated umbrella session is created with `sandbox: true`, later `status` calls may omit it because the uid stays sandbox-scoped.
  - `uid` string, required

## Response `200`

Current delegated umbrella status.

- StatusResponse
  - `agent_instructions` string[]
  - `compare_details_url` string, uri
  - `credit_consent_question` string: Present when Coverage Cat needs the real user's consent for a soft credit check before binding an offer, typically returned from `select` with `status: credit_consent_required`.
  - `fallback_step` FallbackStep
    - `display_note` string
    - `type` 'dashboard'
    - `url` string, uri
  - `field_estimates` UmbrellaFieldEstimate[]
    - `confidence` 'low' | 'medium' | 'high'
    - `confirmed_by_user` boolean: Whether a later draft update re-sent the same value as a confirmed answer.
    - `estimated_at` string, date-time
    - `field` string: Intake dot-path for the estimated answer.
    - `review_path` string[]: Path to the same value inside the `review` object.
    - `source` string: Provenance label for the estimate.
    - `value` string: Current serialized intake value for the estimated field.
  - `known_summary` object: Current delegated umbrella application summary. This may include PII such as applicant name, email, phone number, and address; do not treat it as safe-to-log telemetry.
  - `next_action` NextAction
    - `display_note` string
    - `type` 'bind'
  - `next_question` NextQuestion
    - `display_note` string
    - `fields` QuestionField[]
      - `description` string
      - `enum` unknown[]
        - unknown
      - `format` string
      - `label` string
      - `path` string[]
      - `type` string
    - `item_index` integer, nullable
    - `prompt` string
    - `schema` object
    - `scope` string
    - `title` string
  - `offers` AgentOffer[]
    - `annual_price` integer
    - `carrier` string
    - `choice_guidance` string
    - `coverage_limit` string
    - `display_notes` string[]
    - `is_estimate` boolean
    - `price_range` object, nullable
      - `high` integer
      - `low` integer
    - `rank` integer
    - `recommended` boolean
    - `sample_policy_url` string, uri: Public specimen-policy PDF for this carrier in the shopper's state, when Coverage Cat has one on file.
    - `selection_token` string
  - `offers_url` string, uri: Secure link to the Coverage Cat offers page for this delegated session.
  - `payment_url` string, uri: Secure payment-setup link, returned only when Coverage Cat is ready to collect payment.
  - `policy` object
  - `poll_after_seconds` integer
  - `post_choose` object
  - `required_upload_types` string[]
  - `response_summary` string
  - `review` object: Review JSON for the latest ready-for-review state.
  - `review_token` string
  - `sandbox` boolean: True when this delegated umbrella status payload is mocked sandbox data.
  - `selected_offer` OfferSnapshot
    - `annual_price` integer
    - `carrier` string
    - `coverage_limit` string
    - `is_estimate` boolean
    - `price_range` object, nullable
      - `high` integer
      - `low` integer
  - `selection_guidance` object
  - `status` 'ineligible' | 'needs_more_info' | 'ready_for_review' | 'quoted' | 'no_quotes' | 'needs_more_info_to_bind' | 'ready_to_finalize' | 'documents_needed' | 'documents_pending_review' | 'payment_needed' | 'waiting_on_carrier' | 'info_requested' | 'bound' | 'blocked'
  - `uid` string

## Other responses

- `400`: Invalid request.
- `401`: Invalid or missing API key.
- `404`: Unknown delegated umbrella session.
- `429`: Too many failed authentication attempts or delegated-agent requests. Honor the Retry-After header before retrying.

---

[API](https://skmtc.dev/coveragecat/apis/coverage-cat-delegated-insurance-purchase-apis.md) · [All operations](https://skmtc.dev/coveragecat/apis/coverage-cat-delegated-insurance-purchase-apis/llms.txt) · [OpenAPI document](https://skmtc.dev/coveragecat/apis/coverage-cat-delegated-insurance-purchase-apis/revisions/b80fe29790dc?raw)