---
title: "Create a consumer-prefill umbrella handoff."
method: POST
path: "/api/consumer/umbrella/prefill"
---

# Create a consumer-prefill umbrella handoff.

`POST /api/consumer/umbrella/prefill`

## Request

- Base URL: `https://api.coveragecat.com`
- URL: `https://api.coveragecat.com/api/consumer/umbrella/prefill`
- Auth: none required

Accepts the fullest consumer umbrella application or estimate you can assemble, stores it at Coverage Cat's one-shot review checkpoint, and returns the handoff `uid`, a rotating `intake_access_token` for direct API follow-up, a short-lived `resume_url` browser fallback, and a coarse public `polling_token`. On a cold start, call this before you question the shopper. On the initial consumer umbrella handoff, prefer sending only `intake`; add top-level `field_estimates` only when you are certain each `field` already matches a current umbrella review field path. Use canonical consumer umbrella keys such as `address.street`, `address.city`, `address.state`, `address.zip`, `license_state`, `license_number`, `approximate_asset_value` or `net_worth_numeric`, `desired_coverage_limit`, `required_coverage_e_limit`, and `vehicle_count` or `umbrella_details.motorized_vehicle_count` for umbrella counts. Avoid top-level `street`/`city`/`state`/`zip`, `drivers_license_state`, `drivers_license_number`, `net_worth`, or `desired_umbrella_liability_limit`. Do not send `vehicles` rows before submission. Use `vehicle_count` or `umbrella_details.motorized_vehicle_count` for the household vehicle count; actual vehicle details are collected later only if a selected offer requires them, such as a Markel bind follow-up. Optional consumer sandbox: set top-level `sandbox: true` only on this first prefill call when you want a fully synthetic shopper rehearsal. That same consumer sandbox uid can then keep using `/api/intake/{uid}/issues`, `/api/intake/{uid}`, `/api/intake/{uid}/select`, `/api/intake/{uid}/bind`, `/api/intake/{uid}/attach`, `/api/intake/{uid}/payment`, `/api/intake/{uid}/policy`, `/api/intake/{uid}/service`, and `/api/consumer/status` with synthetic quotes, uploads, payment credentials, policy outcomes, and service-request results only. Until a later follow-up response shows quote progress, the application is not submitted yet. Coverage Cat may answer with a staged `review_summary.review` plus a bundled `review_summary.next_question` so the assistant can collect the shopper-owned details it still needs, such as full name, email, phone, full address, birthday, marital status, driver's license state, driver's license number, net worth, and any corrections, in one turn instead of drifting into a field-by-field questionnaire. When that happens, tell the shopper explicitly that Coverage Cat has not submitted the application yet, ask for those remaining items in plain English, and render the gathered details plus remaining items as short labeled bullets or sections rather than a prose paragraph. If any shown value is estimated, mark each estimated bullet label or value with `*`, include the short note `* = estimated` once above and once below the list, and do not prefix every estimated line with `[Estimated]`. If the staged review shows a wrong estimated umbrella count from context, patch the canonical `umbrella_details.*` count field before you show the final review. Coverage Cat will not resume or expose a prior consumer umbrella draft based on email alone. Continue an existing consumer draft only through the issued `uid` plus the current hidden MCP session or latest `intake_access_token` handoff. If the shopper replies with a birthday in MM-DD-YYYY form, normalize it to YYYY-MM-DD before the follow-up patch. Successful direct follow-up responses rotate a fresh `intake_access_token`; always reuse the newest token you have. Credit consent is not required here — Coverage Cat collects the soft-credit pull authorization after the user chooses an offer.

## Headers

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

## Request body

- ConsumerPrefillRequest
  - `credit_consent_pending` true, required: Must be true. Signals that the user has not yet been shown the review page. Homeowners handoffs collect consent for a soft credit check on that review turn; umbrella handoffs defer credit consent until the user chooses an offer at `select`.
  - `field_estimates` object[]: Optional estimate metadata for values that are defensible but not yet directly confirmed by the user. On the initial consumer umbrella handoff, prefer sending only `intake`; add top-level `field_estimates` only when you are certain each `field` already matches a current umbrella review field path.
  - `intake` object, required: Fullest currently known consumer application patch assembled from the user's own context before any piecemeal follow-up. Use canonical consumer umbrella keys such as `address.street`, `address.city`, `address.state`, `address.zip`, `license_state`, `license_number`, `approximate_asset_value` or `net_worth_numeric`, `desired_coverage_limit`, `required_coverage_e_limit`, and `vehicle_count` or `umbrella_details.motorized_vehicle_count` for umbrella counts. Avoid top-level `street`/`city`/`state`/`zip`, `drivers_license_state`, `drivers_license_number`, `net_worth`, or `desired_umbrella_liability_limit`. Do not send `vehicles` rows before submission. Use `vehicle_count` or `umbrella_details.motorized_vehicle_count` for the household vehicle count; actual vehicle details are collected later only if a selected offer requires them, such as a Markel bind follow-up. `current_auto_coverages` is a banded enum, not free text: send one of `unsure` for I'm not sure; `500k/1m` for $500k/$1 Million/$100k or higher; `500k/500k` for $500k/$500k/$100k or $500k CSL; `300k/300k` for $250k/$500k/$100k or $300k/$300k/$100k or $300k CSL; `100k/300k` for $100k/$300k/$100k or lower. Coverage Cat rejects the shopper's raw limits, so translate them into the strongest band those limits fully satisfy. Underlying auto limits gate umbrella eligibility, so reserve `unsure` for limits the shopper genuinely does not know rather than using it to skip the translation.
    - `current_auto_coverages` 'unsure' | '500k/1m' | '500k/500k' | '300k/300k' | '100k/300k': Band for the shopper's current underlying auto liability limits: `unsure` means I'm not sure; `500k/1m` means $500k/$1 Million/$100k or higher; `500k/500k` means $500k/$500k/$100k or $500k CSL; `300k/300k` means $250k/$500k/$100k or $300k/$300k/$100k or $300k CSL; `100k/300k` means $100k/$300k/$100k or lower. Choose the strongest band the shopper's actual limits fully satisfy. Underlying auto limits gate umbrella eligibility, so reserve `unsure` for limits the shopper genuinely does not know.
  - `sandbox` boolean: Optional. Set true only on the first consumer umbrella prefill call when you want a fully synthetic shopper rehearsal. That same consumer sandbox uid can then continue through issues, patch, select, bind, attach, payment, and status with synthetic quotes, uploads, payment credentials, and policy results.

## Response `200`

Consumer umbrella handoff prepared.

- ConsumerPrefillResponse
  - `expires_at` string, date-time, required: When the returned consumer handoff credentials expire.
  - `intake_access_token` string, required: Short-lived direct follow-up bearer for `/api/intake/{uid}`.
  - `polling_token` string, required: Opaque coarse-status polling token for `/api/consumer/status`.
  - `resume_url` string, uri, required: Short-lived browser continuation for the same consumer handoff.
  - `review_summary` object, required: Current non-authoritative pre-submit checkpoint the agent may summarize before continuing in chat or opening a browser fallback. Unless a later follow-up response shows quote progress, treat this application as not submitted yet. If any shown value is estimated, mark that bullet or value with `*`, include the short note `* = estimated` once above and once below the list, and do not prefix every estimated line with `[Estimated]`.
    - `poll_after_seconds` integer
    - `documents` object[]
      - `content_type` string
      - `download_url` string, uri: Short-lived browser continuation for this policy document.
      - `label` string
      - `name` string
      - `type` string
    - `payment_setup` object
      - `environment` 'test' | 'live'
      - `payment_method_types` string[]
      - `provider` string
      - `setup_intent_id` string
      - `usage` string
    - `required_upload_types` string[]
    - `payment_ui` object
      - `availability` 'ready' | 'unknown' | 'unsupported'
      - `fallback_reason` string
      - `mode` string
    - `payment_url` string, uri: Coverage Cat browser URL for secure payment fallback.
    - `known_summary` object: Structured facts Coverage Cat can safely summarize at this stage.
    - `compare_details_url` string, uri: Coverage Cat browser URL for compare-details follow-up.
    - `uploaded_count` integer
    - `response_summary` string
    - `schema` object: Supplemental schema hints for homeowners review payloads.
    - `user_action_required` string
    - `agent_instructions` string[]
    - `review_token` string: Opaque review token for delegated review-style submit paths.
    - `status` 'abandoned' | 'blocked' | 'bound' | 'cancelled' | 'chosen' | 'credit_consent_pending' | 'credit_consent_required' | 'dev_success' | 'documents_needed' | 'documents_pending_review' | 'email_sent' | 'in_review' | 'ineligible' | 'info_requested' | 'needs_more_info' | 'needs_more_info_to_bind' | 'no_policy' | 'no_chosen_offer' | 'no_quotes' | 'no_selection' | 'ok' | 'payment_collection_ready' | 'payment_needed' | 'pending' | 'pending_quotes' | 'queued' | 'quote_rate_limited' | 'quoted' | 'ready_for_review' | 'ready_for_submission' | 'ready_to_finalize' | 'review_pending' | 'service_preview' | 'service_requested' | 'sandbox_unsupported' | 'stale_selection' | 'verifying_documents' | 'waiting_on_carrier' | 'waiting_on_documents' | 'waiting_on_payment', required
    - `selected_offer` object
      - `address` object
        - `city` string
        - `state` string
        - `street` string
        - `zip` string
      - `annual_price` number
      - `carrier` string
      - `coverage_limit` string
      - `coverage_summary` object: Homeowners or umbrella coverage details Coverage Cat can safely summarize.
      - `deductible` number
      - `dwelling_coverage` number
      - `is_estimate` boolean
      - `minimum_auto_limits` object: Underlying auto-limit requirements for this offer.
      - `personal_liability` number
      - `policy_subtype` string
      - `policy_subtype_display` string
      - `price_range` object
        - `high` number
        - `low` number
      - `quote_number` string
      - `recommended` boolean
      - `sample_policy_url` string, uri
      - `selection_guidance` object: Offer-specific same-reply requirements and guidance.
      - `selection_token` string
      - `um_uim_selection` object: Optional excess UM/UIM election details for this offer.
    - `support` object
      - `contact_url` string, uri: Coverage Cat support route for billing, cancellations, and quote follow-up.
      - `email` string
      - `phone` string
    - `purchase_preview` object
      - `action_summary` string
      - `approval_required` boolean
      - `carrier_conditions` string[]
      - `coverage_summary` object: Coverage details tied to the current previewed offer.
      - `effective_date` string, date
      - `effective_period` object
        - `ends_on` string, date
        - `starts_on` string, date
      - `payment_timing` string
      - `price` object
        - `annual_premium` number
        - `currency` string
        - `payment_method` string
      - `status` string
      - `uncertainty` string
    - `service_request` object
      - `action_summary` string
      - `billing_effect` string
      - `carrier_conditions` string[]
      - `coverage_effect` string
      - `details` string
      - `estimated_refund_status` 'not_applicable' | 'unknown_pending_review'
      - `final_outcome` object: Final carrier or billing outcome once Coverage Cat can confirm it.
      - `reason` string
      - `request_id` string
      - `request_type` 'policy_cancellation' | 'refund_request' | 'support_case'
      - `requested_at` string, date-time
      - `requested_effective_date` string, date
      - `status` 'pending_review' | 'completed'
      - `uncertainty` string
    - `conversation` object
      - `messages` object[]
        - `author_label` string
        - `delivery_state` 'received' | 'queued' | 'sent'
        - `direction` 'incoming' | 'outgoing'
        - `medium` 'email' | 'app' | 'sms'
        - `message_id` integer
        - `subject` string
        - `text` string
        - `timestamp` string, date-time
      - `reply_pending` boolean
      - `reply_supported` boolean
      - `reply_to_message_id` integer
      - `reply_via` string
    - `offers_url` string, uri: Coverage Cat browser URL for the selected offer or offer-tracking page.
    - `service_requests` object[]
      - `action_summary` string
      - `billing_effect` string
      - `carrier_conditions` string[]
      - `coverage_effect` string
      - `details` string
      - `estimated_refund_status` 'not_applicable' | 'unknown_pending_review'
      - `final_outcome` object: Final carrier or billing outcome once Coverage Cat can confirm it.
      - `reason` string
      - `request_id` string
      - `request_type` 'policy_cancellation' | 'refund_request' | 'support_case'
      - `requested_at` string, date-time
      - `requested_effective_date` string, date
      - `status` 'pending_review' | 'completed'
      - `uncertainty` string
    - `payment_collection_supported` boolean
    - `review_estimates` object[]
    - `notification_channel` object
      - `customer_owned_inbox_required` boolean
      - `destination_hint` string
      - `events` string[]
      - `registered` boolean
      - `role` string
      - `type` string
    - `credit_consent_question` string
    - `next_action` object: A structured hint for the next allowed tool or endpoint action.
    - `application_submitted` boolean
    - `uploaded` object[]
      - `filename` string
      - `type` string
    - `review` object: Structured review card or selected-offer review block.
    - `missing_fields` object[]: Structured missing-value hints for homeowners pre-submit review.
    - `next_question` object: The current shopper-owned question bundle or bind-stage question.
    - `sandbox` boolean: True when Coverage Cat is returning consumer sandbox test data rather than a live shopper workflow.
    - `selection_guidance` object: Guidance for completing an offer choice in one shopper-facing reply.
    - `review_items` object[]
      - `description` string
      - `display_value` string
      - `enum` string[]
      - `label` string
      - `number` integer
      - `path` union[]
        - union
          - string
          - integer
      - `suggested_value` unknown
    - `payment_status` object
      - `channel` string
      - `customer_owned_inbox_required` boolean
      - `destination_hint` string
      - `payment_intent_id` string
      - `payment_method_saved_at` string, date-time
      - `provider` string
      - `state` string
      - `timing` string
    - `preview_token` string: Opaque bind-preview token for the next homeowners bind confirmation.
    - `offers` object[]
      - `address` object
        - `city` string
        - `state` string
        - `street` string
        - `zip` string
      - `annual_price` number
      - `carrier` string
      - `coverage_limit` string
      - `coverage_summary` object: Homeowners or umbrella coverage details Coverage Cat can safely summarize.
      - `deductible` number
      - `dwelling_coverage` number
      - `is_estimate` boolean
      - `minimum_auto_limits` object: Underlying auto-limit requirements for this offer.
      - `personal_liability` number
      - `policy_subtype` string
      - `policy_subtype_display` string
      - `price_range` object
        - `high` number
        - `low` number
      - `quote_number` string
      - `recommended` boolean
      - `sample_policy_url` string, uri
      - `selection_guidance` object: Offer-specific same-reply requirements and guidance.
      - `selection_token` string
      - `um_uim_selection` object: Optional excess UM/UIM election details for this offer.
    - `service_preview` object
      - `action_summary` string
      - `approval_required` boolean
      - `billing_effect` string
      - `carrier_conditions` string[]
      - `coverage_effect` string
      - `details` string
      - `estimated_refund_status` 'not_applicable' | 'unknown_pending_review'
      - `reason` string
      - `request_type` 'policy_cancellation' | 'refund_request' | 'support_case'
      - `requested_effective_date` string, date
      - `status` 'preview'
      - `uncertainty` string
    - `post_choose` object: Structured post-choose state after a quoted umbrella offer is selected.
    - `pending_fields` object[]: Structured missing-value hints for umbrella pre-submit review.
    - `offer_summary` object
      - `cheapest_annual_premium` number
      - `cheapest_carrier` string
      - `quote_count` integer
      - `recommended_annual_premium` number
      - `recommended_carrier` string
    - `policy` object
      - `cancellation_note` string
      - `cancelled_at` string, date
      - `carrier` string
      - `confirmation_timestamp` string, date-time
      - `coverage_summary` object: Carrier-confirmed policy coverage details Coverage Cat can safely return.
      - `effective_date` string, date
      - `effective_period` object
        - `ends_on` string, date
        - `starts_on` string, date
      - `policy_number` string
      - `state` 'bound' | 'cancelled'
    - `field_estimates` object[]
  - `sandbox` boolean: True when Coverage Cat is returning consumer sandbox test data rather than a live shopper workflow.
  - `uid` string, required: Coverage Cat intake uid for follow-up.

## Other responses

- `400`: Invalid request body.
- `429`: Too many consumer handoff or public polling requests. Honor the Retry-After header before retrying.
- `500`: Coverage Cat could not prepare the consumer umbrella handoff.

---

[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)