{"openapi":"3.1.0","info":{"title":"99 Offers Home Seller Match API","version":"1.4.0","description":"Closed-pilot agent API for a free potential cash-buyer check: prepare one private homeowner request, update its facts before consent or matching, and read homeowner-safe status. Record selling preference separately from motivation and timeline; urgency never implies cash-sale interest or consent. A traditional-listing preference is saved, but no active listing service is connected. Every successful response includes agent_outcome, a factual milestone, not a home offer or guarantee. Ask only the returned critical questions. An exact homeowner-confirmed street address is required before a buyer check and must never be guessed. Every top-level homeowner, property, or intent value needs an equal accepted context_facts provenance record. The API cannot record permission, start a buyer check, or share contact information; the homeowner controls those actions on the private 99 Offers review page.","termsOfService":"https://99offers.io/terms"},"servers":[{"url":"https://sellhouse.99offers.io"}],"tags":[{"name":"Homeowner gateway"}],"security":[{"bearerAuth":[]}],"paths":{"/api/v1/homeowner/requests":{"post":{"operationId":"prepareHomeownerRequest","summary":"Prepare or recover a private homeowner request","description":"Send every relevant structured fact already known, never a raw transcript or memory export. For every field included under homeowner, property, or intent, include one accepted context_facts item with the same field path and equal value. Facts may be provided only in context_facts; accepted facts can fill otherwise omitted top-level fields. Obtain the exact street address from the homeowner or an authorized address tool and have the homeowner confirm it; never guess from device/profile location or old history. A successful response identifies only remaining critical gaps and includes agent_outcome as factual completion feedback. Reuse the same Idempotency-Key with the identical body to recover the same request. The returned confirmation_url is a private bearer capability: give it only to the homeowner, and never log, crawl, prefetch, or open it on the homeowner's behalf.","tags":["Homeowner gateway"],"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"Stable for one logical preparation attempt. Reuse only with the byte-equivalent logical request; use a new value after an expired review request is deliberately prepared again.","schema":{"type":"string","minLength":8,"maxLength":150},"example":"seller-context-0198f3e2"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PrepareHomeownerRequest"},"examples":{"groundedRequest":{"summary":"Current-message fields plus one historical property fact","value":{"source_agent":{"platform":"chatgpt","name":"Homeowner assistant","conversation_ref":"conversation-opaque-123"},"attribution":{"utm_source":"chatgpt","utm_medium":"ai-agent","utm_campaign":"home-seller-match"},"homeowner":{"role":"owner"},"property":{"address":"123 Example Ave","city":"Austin","state":"TX","zip":"78704","type":"single_family"},"intent":{"path":"compare"},"context_facts":[{"field":"homeowner.role","value":"owner","source":"current_message","confidence":1,"confirmed_by_homeowner":true},{"field":"property.address","value":"123 Example Ave","source":"homeowner_confirmation","confidence":1,"confirmed_by_homeowner":true},{"field":"property.city","value":"Austin","source":"current_message","confidence":1,"confirmed_by_homeowner":true},{"field":"property.state","value":"TX","source":"current_message","confidence":1,"confirmed_by_homeowner":true},{"field":"property.zip","value":"78704","source":"current_message","confidence":1,"confirmed_by_homeowner":true},{"field":"property.type","value":"single_family","source":"current_message","confidence":1,"confirmed_by_homeowner":true},{"field":"intent.path","value":"compare","source":"current_message","confidence":1,"confirmed_by_homeowner":true},{"field":"property.beds","value":3,"source":"historical_chat","confidence":0.86,"observed_at":"2026-08-15T10:00:00Z","confirmed_by_homeowner":false}]}}}}}},"responses":{"201":{"description":"Private draft prepared or idempotently recovered","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PreparedGatewayResponse"},"example":{"request_id":"0198f3e2-7c42-7b09-8bd4-8e4e70b2e111","status":"needs_information","status_message":"Review a few more details about your home and selling plans.","agent_outcome":{"code":"material_gaps_identified","message":"You organized the homeowner's request and identified exactly which material details still block matching.","buyer_signal":{"state":"not_checked","ping_eligible_buyer_account_count":null,"count_basis":null,"checked_at":null}},"missing_fields":["intent.timeline","intent.motivations","property.sqft","property.lot_size_acres","property.year_built","property.baths","property.condition","property.listed","property.occupancy","property.years_owned"],"questions":["Please share or confirm your ideal sale timeline, and the main reason you are considering selling?","Please share or confirm the property's condition, its occupancy, and whether it is currently listed?","Please share or confirm its approximate square footage, the lot size in acres (a best estimate is fine), the approximate year built, the bathroom count, and approximately how long it has been owned?"],"confirmation_url":"https://99offers.io/ai/home-seller-match/r/example-private-review-token","next_action":"provide_information","poll_after_seconds":null,"resolution_deadline":null,"property_summary":{"location":"Austin, TX, 78704","property_type":"single_family","bedrooms":3,"bathrooms":null,"square_feet":null,"lot_size_acres":null,"timeline":null,"preferred_path":"compare"},"privacy":{"contact_shared":false,"exact_address_shared":false,"contact_sharing_status":"private","future_sharing_revoked":false,"personal_data_deleted":false},"route_options":[{"type":"cash_buyer_match","status":"not_checked","label":"Check for potential cash-buyer matches"},{"type":"listing_expert","status":"not_available","label":"You are open to selling with a real-estate agent. Agent introductions are not available through this service yet."}],"contact_plan":{"who_may_contact":null,"preferred_channel":null,"preferred_time":null,"response_expectation":"No buyer or service provider may contact the homeowner through this request unless the homeowner separately approves contact sharing."},"updated_at":"2026-09-01T12:00:00.000Z"}}}},"400":{"description":"Malformed JSON or invalid idempotency key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"code":"invalid_json","message":"Request body must be valid JSON"}}}}},"401":{"description":"Missing or invalid closed-pilot integration key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"code":"unauthorized","message":"A valid agent API key is required"}}}}},"409":{"description":"The idempotency key was reused with a different request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"code":"idempotency_conflict","message":"This Idempotency-Key was already used with a different request body"}}}}},"413":{"description":"Request body exceeds 350,000 bytes","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"code":"payload_too_large","message":"Request payload is too large"}}}}},"422":{"description":"A field failed runtime validation or provenance enforcement","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorEnvelope"},"example":{"error":{"code":"validation_error","message":"Some submitted fields need attention.","details":{"field_violations":[{"field":"property.city","message":"Use a valid value."}]}}}}}},"429":{"description":"Per-IP preparation limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"code":"rate_limited","message":"Too many requests. Please wait a minute and retry."}}}}},"500":{"description":"Unexpected gateway failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"code":"internal_error","message":"99 Offers could not complete this request right now."}}}}}},"x-consent-boundary":"prepare-only","x-provenance-requirement":"Every supplied homeowner.*, property.*, and intent.* value requires an equal, accepted context_facts item."}},"/api/v1/homeowner/requests/{requestId}":{"patch":{"operationId":"updateHomeownerRequest","summary":"Add or correct facts in the same private homeowner request","description":"Merge selected facts into this integration's existing draft before any homeowner match or contact consent or route check. Omitted facts and the request identity are preserved. Every supplied top-level value requires an equal accepted context_facts provenance item. Keep selling preference separate from motivation and timeline; urgency never implies cash interest or permission. Reuse the same Idempotency-Key and identical body after a timeout; a changed body needs a new key. REST and MCP updates share the same key namespace per client and request. Never create another draft to add missing answers. This endpoint cannot record consent, run matching, share contact data, or return the private review capability. confirmation_url is always null; retain the original link privately for the homeowner. Once agent edits are closed, let the homeowner correct facts on that review page.","tags":["Homeowner gateway"],"parameters":[{"name":"requestId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","required":true,"description":"Stable for one logical update. Reuse with identical facts after a timeout; use a new key for changed facts.","schema":{"type":"string","minLength":8,"maxLength":150}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateHomeownerRequest"}}}},"responses":{"200":{"description":"Updated safe status and remaining questions; confirmation_url is null","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StatusGatewayResponse"}}}},"400":{"description":"Malformed JSON or invalid idempotency key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"code":"invalid_idempotency_key","message":"Idempotency-Key must be 8-150 characters"}}}}},"401":{"description":"Missing or invalid closed-pilot integration key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"code":"unauthorized","message":"A valid agent API key is required"}}}}},"404":{"description":"The request does not exist or belongs to another integration","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"code":"not_found","message":"Request not found"}}}}},"409":{"description":"Changed facts under the same key, concurrent edits, or agent updates closed after homeowner consent/matching; retain the existing request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"code":"a2a_task_read_only","message":"This request can no longer accept agent updates. The homeowner controls the next step on 99 Offers."}}}}},"410":{"description":"The request or review link expired, or personal data was deleted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"code":"request_expired","message":"Request expired"}}}}},"413":{"description":"Request body exceeds 350,000 bytes","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"code":"payload_too_large","message":"Request payload is too large"}}}}},"422":{"description":"Invalid request ID, empty update, unsupported fields, or missing accepted provenance","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"code":"validation_error","message":"Some submitted fields need attention."}}}}},"429":{"description":"Per-IP update limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"code":"rate_limited","message":"Too many updates. Please wait a minute and retry."}}}}},"500":{"description":"Unexpected gateway failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"code":"internal_error","message":"99 Offers could not complete this request right now."}}}}}},"x-consent-boundary":"draft-update-only","x-provenance-requirement":"Every supplied homeowner.*, property.*, and intent.* value requires an equal, accepted context_facts item."},"get":{"operationId":"getHomeownerRequestStatus","summary":"Read and safely reconcile homeowner request status","description":"Returns homeowner-safe status plus agent_outcome and may reconcile an already-started, homeowner-approved contact handoff through a read-only provider lookup. eligible_route_found is current PING eligibility, handoff_delivered is 99 Offers acceptance, and buyer_route_activated requires the purchase callback; never collapse those stages or promise call timing. It never starts a new match check, creates a new provider submission, records permission, or returns contact PII, exact street address, provider economics, or a reusable homeowner review token. confirmation_url is always null on this endpoint.","tags":["Homeowner gateway"],"parameters":[{"name":"requestId","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"example":"0198f3e2-7c42-7b09-8bd4-8e4e70b2e111"}],"responses":{"200":{"description":"Current safe status; confirmation_url is deliberately null","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StatusGatewayResponse"},"example":{"request_id":"0198f3e2-7c42-7b09-8bd4-8e4e70b2e111","status":"needs_information","status_message":"Review a few more details about your home and selling plans.","agent_outcome":{"code":"material_gaps_identified","message":"You organized the homeowner's request and identified exactly which material details still block matching.","buyer_signal":{"state":"not_checked","ping_eligible_buyer_account_count":null,"count_basis":null,"checked_at":null}},"missing_fields":["intent.timeline","intent.motivations","property.sqft","property.lot_size_acres","property.year_built","property.baths","property.condition","property.listed","property.occupancy","property.years_owned"],"questions":["Please share or confirm your ideal sale timeline, and the main reason you are considering selling?","Please share or confirm the property's condition, its occupancy, and whether it is currently listed?","Please share or confirm its approximate square footage, the lot size in acres (a best estimate is fine), the approximate year built, the bathroom count, and approximately how long it has been owned?"],"confirmation_url":null,"next_action":"provide_information","poll_after_seconds":null,"resolution_deadline":null,"property_summary":{"location":"Austin, TX, 78704","property_type":"single_family","bedrooms":3,"bathrooms":null,"square_feet":null,"lot_size_acres":null,"timeline":null,"preferred_path":"compare"},"privacy":{"contact_shared":false,"exact_address_shared":false,"contact_sharing_status":"private","future_sharing_revoked":false,"personal_data_deleted":false},"route_options":[{"type":"cash_buyer_match","status":"not_checked","label":"Check for potential cash-buyer matches"},{"type":"listing_expert","status":"not_available","label":"You are open to selling with a real-estate agent. Agent introductions are not available through this service yet."}],"contact_plan":{"who_may_contact":null,"preferred_channel":null,"preferred_time":null,"response_expectation":"No buyer or service provider may contact the homeowner through this request unless the homeowner separately approves contact sharing."},"updated_at":"2026-09-01T12:00:00.000Z"}}}},"401":{"description":"Missing or invalid closed-pilot integration key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"code":"unauthorized","message":"A valid agent API key is required"}}}}},"404":{"description":"The request does not exist or belongs to another integration","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"code":"not_found","message":"Request not found"}}}}},"410":{"description":"The request expired or its personal data was deleted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"code":"request_expired","message":"Request expired"}}}}},"429":{"description":"Per-IP status-read limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"code":"rate_limited","message":"Too many status checks. Please wait and retry."}}}}},"500":{"description":"Unexpected gateway failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"code":"internal_error","message":"99 Offers could not complete this request right now."}}}}}},"x-consent-boundary":"status-and-reconciliation-only"}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Static 99 Offers integration key issued out of band for a named, closed-pilot client. This is not public OAuth client registration and must not be embedded in homeowner-facing code. Production partners should use a server-side secret store and rotate compromised keys."}},"schemas":{"SourceAgent":{"type":"object","additionalProperties":false,"required":["platform"],"properties":{"platform":{"type":"string","enum":["chatgpt","claude","gemini","other"],"description":"The authenticated agent platform. 99offers_web is reserved for the separate first-party web-start endpoint and is rejected here."},"name":{"type":"string","minLength":1,"maxLength":300},"conversation_ref":{"type":"string","minLength":1,"maxLength":300,"description":"Opaque client reference only; never place transcript text or contact data here."}}},"Attribution":{"type":"object","additionalProperties":false,"description":"Optional campaign metadata only. Never put homeowner facts or contact data here.","properties":{"utm_source":{"type":"string","minLength":1,"maxLength":100},"utm_medium":{"type":"string","minLength":1,"maxLength":100},"utm_campaign":{"type":"string","minLength":1,"maxLength":100},"referrer_host":{"type":"string","minLength":1,"maxLength":253,"description":"Hostname only, not a full URL."}}},"Homeowner":{"type":"object","additionalProperties":false,"description":"Optional selected values. Every supplied field must be duplicated by an equal accepted context_facts provenance item.","properties":{"role":{"type":"string","enum":["owner","co_owner","executor","agent","unknown"]},"first_name":{"type":"string","minLength":1,"maxLength":100},"last_name":{"type":"string","minLength":1,"maxLength":100},"phone":{"type":"string","minLength":7,"maxLength":30},"email":{"type":"string","format":"email","maxLength":254},"preferred_contact":{"type":"string","enum":["call","text","email","either"]},"preferred_contact_time":{"type":"string","enum":["morning","afternoon","evening","anytime"]}}},"Property":{"type":"object","additionalProperties":false,"description":"Optional selected values. Every supplied field must be duplicated by an equal accepted context_facts provenance item.","properties":{"address":{"type":"string","minLength":3,"maxLength":300,"description":"Exact property street address. Required before route checking, stored encrypted, and excluded from the anonymous PING. It must come from the homeowner/current message or be homeowner-confirmed after an authorized address lookup; never guess it."},"city":{"type":"string","minLength":1,"maxLength":100},"state":{"type":"string","minLength":2,"maxLength":30},"zip":{"type":"string","pattern":"^\\d{5}(?:-\\d{4})?$"},"type":{"type":"string","enum":["single_family","condo","townhouse","mobile_owned_land","mobile_rented_land","multifamily","duplex","land","commercial","other","unknown"]},"beds":{"type":"integer","minimum":0,"maximum":50},"baths":{"type":"number","minimum":0,"maximum":50,"multipleOf":0.5},"sqft":{"type":"integer","minimum":0,"maximum":100000},"lot_size_acres":{"type":"number","exclusiveMinimum":0,"maximum":100000,"description":"Approximate lot size in acres. Required before a cash-buyer route check."},"year_built":{"type":"integer","minimum":1800,"maximum":2100},"years_owned":{"type":"number","minimum":0,"maximum":200},"occupancy":{"type":"string","enum":["owner","tenant","vacant","family","unknown"]},"listed":{"type":"string","enum":["yes","no","unknown"]},"condition":{"type":"string","enum":["move_in","cosmetic","remodel","full_gut","unknown"]},"repair_notes":{"type":"string","maxLength":1600,"description":"Concise extracted repair summary only; raw conversation turns are rejected."}}},"Intent":{"type":"object","additionalProperties":false,"description":"Optional selected values. Every supplied field must be duplicated by an equal accepted context_facts provenance item.","properties":{"path":{"type":"string","enum":["cash","listing","compare","unsure"],"description":"Explicit selling preference, separate from motivation and urgency. cash: cash offer; listing: sell with a real-estate agent; compare: open to cash or an agent; unsure: not decided. No active listing service is connected and compare does not promise two sets of offers."},"timeline":{"type":"string","enum":["asap","1_month","2_3_months","4_5_months","6_plus_months","exploring"],"description":"When the homeowner wants to sell. Never infer selling preference or consent from this."},"motivations":{"type":"array","maxItems":8,"items":{"type":"string","enum":["preforeclosure","emergency","financial","vacant","sell_and_rent","death_in_family","no_showings","inherited","downsizing","tired_landlord","closer_to_family","relocating","retirement","upgrading","leaving_us","behind_on_payments","old_age","divorce","health","job_loss","other_personal_reason"]},"description":"The homeowner's reasons for considering a sale. Record independently of selling preference; reasons never imply consent."},"notes":{"type":"string","maxLength":1600,"description":"Concise extracted selling context only; raw conversation turns are rejected."}}},"ContextFactValue":{"description":"One structured value whose type and allowed values must match field. Text content, including joined string-array text, is limited to 1600 characters; raw conversation turns are rejected.","oneOf":[{"type":"string","maxLength":1600},{"type":"number"},{"type":"boolean"},{"type":"null"},{"type":"array","maxItems":30,"items":{"oneOf":[{"type":"string","maxLength":500},{"type":"number"}]}}]},"ContextFact":{"type":"object","additionalProperties":false,"required":["field","value","source","confidence"],"properties":{"field":{"type":"string","enum":["homeowner.role","homeowner.first_name","homeowner.last_name","homeowner.phone","homeowner.email","homeowner.preferred_contact","homeowner.preferred_contact_time","property.address","property.city","property.state","property.zip","property.type","property.beds","property.baths","property.sqft","property.lot_size_acres","property.year_built","property.years_owned","property.occupancy","property.listed","property.condition","property.repair_notes","intent.path","intent.timeline","intent.motivations","intent.notes"],"description":"Allowlisted homeowner.*, property.*, or intent.* field path."},"value":{"$ref":"#/components/schemas/ContextFactValue"},"source":{"type":"string","enum":["current_message","historical_chat","public_record","homeowner_confirmation","agent_inference"]},"confidence":{"type":"number","minimum":0,"maximum":1},"observed_at":{"type":"string","format":"date-time","description":"RFC 3339 timestamp with an explicit UTC offset."},"confirmed_by_homeowner":{"type":"boolean","default":false}},"x-acceptance-rules":["confidence must be at least 0.6","unconfirmed agent_inference is rejected","current-sensitive facts may require current-message provenance or homeowner confirmation","property.address is current-sensitive and cannot be satisfied by unconfirmed historical, public-record, or inferred context","the value must pass field-specific runtime validation"]},"PrepareHomeownerRequest":{"type":"object","additionalProperties":false,"required":["source_agent"],"properties":{"source_agent":{"$ref":"#/components/schemas/SourceAgent"},"attribution":{"$ref":"#/components/schemas/Attribution"},"homeowner":{"$ref":"#/components/schemas/Homeowner"},"property":{"$ref":"#/components/schemas/Property"},"intent":{"$ref":"#/components/schemas/Intent"},"context_facts":{"type":"array","maxItems":100,"default":[],"items":{"$ref":"#/components/schemas/ContextFact"}}},"x-provenance-requirement":"For each supplied homeowner.*, property.*, or intent.* field, context_facts must contain an accepted item with the same field path and equal value."},"UpdateHomeownerRequest":{"type":"object","additionalProperties":false,"minProperties":1,"description":"At least one supplied homeowner/property/intent value or context fact is required. Omitted facts are preserved. Agent identity, attribution, and consent fields cannot be changed here.","properties":{"homeowner":{"$ref":"#/components/schemas/Homeowner"},"property":{"$ref":"#/components/schemas/Property"},"intent":{"$ref":"#/components/schemas/Intent"},"context_facts":{"type":"array","maxItems":100,"items":{"$ref":"#/components/schemas/ContextFact"}}},"anyOf":[{"required":["homeowner"],"properties":{"homeowner":{"minProperties":1}}},{"required":["property"],"properties":{"property":{"minProperties":1}}},{"required":["intent"],"properties":{"intent":{"minProperties":1}}},{"required":["context_facts"],"properties":{"context_facts":{"minItems":1}}}],"x-provenance-requirement":"For each supplied homeowner.*, property.*, or intent.* field, context_facts must contain an accepted item with the same field path and equal value."},"PropertySummary":{"type":"object","additionalProperties":false,"required":["location","property_type","bedrooms","bathrooms","square_feet","lot_size_acres","timeline","preferred_path"],"properties":{"location":{"type":["string","null"]},"property_type":{"type":["string","null"],"enum":["single_family","condo","townhouse","mobile_owned_land","mobile_rented_land","multifamily","duplex","land","commercial","other","unknown",null]},"bedrooms":{"type":["integer","null"],"minimum":0,"maximum":50},"bathrooms":{"type":["number","null"],"minimum":0,"maximum":50,"multipleOf":0.5},"square_feet":{"type":["integer","null"],"minimum":0,"maximum":100000},"lot_size_acres":{"type":["number","null"],"exclusiveMinimum":0,"maximum":100000},"timeline":{"type":["string","null"],"enum":["asap","1_month","2_3_months","4_5_months","6_plus_months","exploring",null]},"preferred_path":{"type":["string","null"],"enum":["cash","listing","compare","unsure",null]}}},"PrivacyStatus":{"type":"object","additionalProperties":false,"required":["contact_shared","exact_address_shared","contact_sharing_status","future_sharing_revoked","personal_data_deleted"],"properties":{"contact_shared":{"type":"boolean"},"exact_address_shared":{"type":"boolean"},"contact_sharing_status":{"type":"string","enum":["private","in_progress","delivery_unknown","confirmed_shared"]},"future_sharing_revoked":{"type":"boolean"},"personal_data_deleted":{"type":"boolean"}}},"RouteOption":{"type":"object","additionalProperties":false,"required":["type","status","label"],"properties":{"type":{"type":"string","enum":["cash_buyer_match","listing_expert"]},"status":{"type":"string","enum":["available","checking","not_available","not_checked"]},"label":{"type":"string"},"url":{"type":"string","format":"uri"}}},"ContactPlan":{"type":"object","additionalProperties":false,"required":["who_may_contact","preferred_channel","preferred_time","response_expectation"],"properties":{"who_may_contact":{"type":["string","null"]},"preferred_channel":{"type":["string","null"],"enum":["call","text","email","either",null]},"preferred_time":{"type":["string","null"],"enum":["morning","afternoon","evening","anytime",null]},"response_expectation":{"type":"string"}}},"BuyerSignal":{"type":"object","additionalProperties":false,"required":["state","ping_eligible_buyer_account_count","count_basis","checked_at"],"properties":{"state":{"type":"string","enum":["not_checked","checking","eligible_route_found","no_current_route","handoff_in_progress","handoff_delivered","buyer_route_activated","reversed","rejected","unknown"],"description":"Evidence stage. eligible_route_found is anonymous PING eligibility, handoff_delivered is 99 Offers acceptance, and buyer_route_activated requires the purchase callback."},"ping_eligible_buyer_account_count":{"type":["integer","null"],"minimum":0,"description":"Point-in-time count of distinct funded buyer accounts whose Automatch programs passed the anonymous property and routing filters available during PING. Because PING excludes phone and exact address, later duplicate/conflict checks can still change the outcome. Null when the deployed provider contract did not return a truthful count. This is not a count of people or companies and does not prove view, acceptance, purchase, or contact."},"count_basis":{"type":["string","null"],"enum":["distinct_funded_buyer_accounts_passing_anonymous_ping_filters",null]},"checked_at":{"type":["string","null"],"format":"date-time","description":"Provider timestamp for the point-in-time eligibility check when supplied."}}},"AgentOutcome":{"type":"object","additionalProperties":false,"required":["code","message","buyer_signal"],"description":"Stable, factual completion feedback for the calling agent. Present message once per new code + updated_at, then obey next_action. It never grants homeowner consent or expands the buyer claim beyond buyer_signal.state.","properties":{"code":{"type":"string","enum":["request_started","material_gaps_identified","review_ready","selling_preference_recorded","buyer_check_not_available","route_check_started","route_check_completed","potential_route_found","sharing_choice_ready","approved_handoff_started","approved_handoff_recorded","delivery_verification_started","buyer_route_activated","buyer_transaction_reversed","handoff_not_accepted","privacy_choice_completed","permission_revoked","safe_retry_available","manual_review_preserved","security_stop_recorded"]},"message":{"type":"string"},"buyer_signal":{"$ref":"#/components/schemas/BuyerSignal"}}},"GatewayResponseBase":{"type":"object","additionalProperties":false,"required":["request_id","status","status_message","agent_outcome","missing_fields","questions","confirmation_url","next_action","poll_after_seconds","resolution_deadline","property_summary","privacy","route_options","contact_plan","updated_at"],"properties":{"request_id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["draft","needs_information","ready_for_match","checking","no_match","match_available","awaiting_contact_consent","posting","submitted","submission_unknown","purchased","refunded","rejected","kept_private","revoked","error"]},"status_message":{"type":"string"},"agent_outcome":{"$ref":"#/components/schemas/AgentOutcome"},"missing_fields":{"type":"array","items":{"type":"string","maxLength":200}},"questions":{"type":"array","maxItems":3,"items":{"type":"string"}},"confirmation_url":{"type":["string","null"],"format":"uri","description":"Present only as a private URL on the original successful prepare response; authenticated status reads return null."},"next_action":{"type":"string","enum":["provide_information","confirm_match","wait","confirm_contact","complete","retry","none"]},"poll_after_seconds":{"type":["integer","null"],"minimum":1,"description":"Minimum server-recommended delay before the next status read. Poll only when next_action is wait; otherwise this is null."},"resolution_deadline":{"type":["string","null"],"format":"date-time","description":"Deadline for automatic reconciliation of a previously approved contact handoff. Never resubmit. If the deadline ends in next_action none or a manual-review message, stop polling and leave the request for 99 Offers review."},"property_summary":{"$ref":"#/components/schemas/PropertySummary"},"privacy":{"$ref":"#/components/schemas/PrivacyStatus"},"route_options":{"type":"array","items":{"$ref":"#/components/schemas/RouteOption"}},"contact_plan":{"$ref":"#/components/schemas/ContactPlan"},"updated_at":{"type":"string","format":"date-time"}}},"PreparedGatewayResponse":{"allOf":[{"$ref":"#/components/schemas/GatewayResponseBase"},{"type":"object","required":["confirmation_url"],"properties":{"confirmation_url":{"type":"string","format":"uri","description":"Private expiring bearer capability for the homeowner. Never log, crawl, prefetch, or open it for the homeowner."}}}]},"StatusGatewayResponse":{"allOf":[{"$ref":"#/components/schemas/GatewayResponseBase"},{"type":"object","required":["confirmation_url"],"properties":{"confirmation_url":{"type":"null","description":"Always null on authenticated status reads; retain the original prepare response privately."}}}]},"ErrorEnvelope":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"object","additionalProperties":false,"required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"description":"Optional safe structured error details; shape depends on the error code."}}}}},"ValidationErrorEnvelope":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"object","additionalProperties":false,"required":["code","message","details"],"properties":{"code":{"type":"string","const":"validation_error"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":false,"required":["field_violations"],"properties":{"field_violations":{"type":"array","maxItems":20,"items":{"type":"object","additionalProperties":false,"required":["field","message"],"properties":{"field":{"type":"string"},"message":{"type":"string"}}}}}}}}}}}},"x-99offers-agent-entrypoints":{"a2aAgentCard":"https://sellhouse.99offers.io/.well-known/agent-card.json","a2aJsonRpc":"https://sellhouse.99offers.io/a2a","mcp":"https://sellhouse.99offers.io/mcp","homeownerLandingPage":"https://sellhouse.99offers.io/ai/home-seller-match","fullAgentGuidance":"https://sellhouse.99offers.io/llms-full.txt"},"x-polling-policy":{"pollOnlyWhenNextAction":"wait","honorPollAfterSeconds":true,"backoffSeconds":[10,20,30,60],"maximumAutomatedChecks":10,"submissionUnknownRule":"Never resubmit. Stop when next_action is none, the status message requires manual review, resolution_deadline passes, or the polling budget is exhausted."}}