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

# Create a consumer-prefill homeowners handoff.

`POST /api/consumer/homeowners/prefill`

## Request

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

Accepts the fullest consumer homeowners application you can assemble, prepares Coverage Cat's one-shot review and soft-credit consent checkpoint, and returns the handoff `uid`, a rotating `intake_access_token` for direct API follow-up, a short-lived `/intake?resume=...` browser fallback URL, and a coarse public `polling_token`. On a cold start, ask only for the shopper's full name, email, property address, and whether the property should be treated as standard homeowners, condo, or landlord coverage first. The initial `intake.home[0]` data must preserve that distinction by sending `home_ownership: owned_rental` or a rented `rental_status` for landlord coverage, `property_type: condo` for condo coverage, or both a non-rental `home_ownership` and a non-condo `property_type` for standard homeowners coverage. Then recover core shopper and occupancy facts such as date of birth, marital status, and owner-occupied vs new-purchase from user-controlled context before calling this endpoint. Until a later follow-up response shows quote progress, the application is not submitted yet. Coverage Cat can then estimate many reviewable home fields for the review card. Stay on the same consumer follow-up loop through long-lag quote polling, `/api/intake/{uid}/select`, `/api/intake/{uid}/bind`, and later `/api/intake/{uid}/policy` plus `/api/intake/{uid}/service`; do not switch to delegated operator endpoints just to keep the shopper moving. Homeowners quotes or carrier bind follow-up may take up to 48 hours, so keep polling and keep the registered customer email channel on file. Coverage Cat does not collect first-party homeowners payment in chat; any carrier payment or signing link goes directly to the customer's email on file. On the review turn, tell the shopper explicitly that Coverage Cat has not submitted the application yet, ask for any remaining items or the soft-credit Yes/No in plain English, and render 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]`. Successful direct follow-up responses rotate a fresh `intake_access_token`; always reuse the newest token you have.

## Headers

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

## Request body

- ConsumerHomeownersPrefillRequest
  - `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 homeowners application patch assembled from the user's own context before any piecemeal follow-up. The first create call must already identify whether the property is standard homeowners, condo, or landlord coverage.
    - `home` union, required: Initial product-selection row for the first create call. Send a single object or an array, and make sure the first home row already distinguishes standard homeowners, condo, or landlord coverage.
      - union: Initial homeowners home row. Coverage Cat needs this row to distinguish standard homeowners, condo, or landlord coverage before it can assemble the rest of the application.
        - object: Standard homeowners coverage. Send both a non-rental home_ownership and a non-condo property_type.
          - `home_ownership` 'owned_primary' | 'owned_seasonal' | 'under_construction', required
          - `property_type` 'single_family' | 'duplex' | 'triplex' | 'quadplex' | 'apartment' | 'townhouse' | 'manufacture_or_mobile', required
        - object: Condo coverage. Send property_type: condo.
          - `property_type` 'condo', required
        - object: Landlord coverage. Send home_ownership: owned_rental.
          - `home_ownership` 'owned_rental', required
        - object: Landlord coverage. A rented rental_status also counts when home_ownership is not yet known.
          - `rental_status` 'room' | 'attached_unit' | 'detached_unit', required
      - ConsumerHomeownersInitialHome[]
        - union: Initial homeowners home row. Coverage Cat needs this row to distinguish standard homeowners, condo, or landlord coverage before it can assemble the rest of the application.
          - object: Standard homeowners coverage. Send both a non-rental home_ownership and a non-condo property_type.
            - `home_ownership` 'owned_primary' | 'owned_seasonal' | 'under_construction', required
            - `property_type` 'single_family' | 'duplex' | 'triplex' | 'quadplex' | 'apartment' | 'townhouse' | 'manufacture_or_mobile', required
          - object: Condo coverage. Send property_type: condo.
            - `property_type` 'condo', required
          - object: Landlord coverage. Send home_ownership: owned_rental.
            - `home_ownership` 'owned_rental', required
          - object: Landlord coverage. A rented rental_status also counts when home_ownership is not yet known.
            - `rental_status` 'room' | 'attached_unit' | 'detached_unit', required

## Response `200`

Consumer homeowners 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 homeowners 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)