openapi: 3.1.0
info:
title: Homeward Offer Estimate API
version: 1.0.0
description: >-
The Homeward Offer Estimate API is for Homeward cash-offer digital partners.
A partner posts a seller lead (property + customer + agent details) and
Homeward responds with a Homeward Offer Estimate — an offer amount, an
opinion-of-value range, a link to the Offer Estimate PDF, and a
finalization link. Additional endpoints return the full offer breakdown,
check whether a property is within Homeward's "buybox," update the agent on
a request, and finalize a lead. Access is by invitation: contact
api@homeward.com for testing and production tokens.
contact:
name: Homeward API
email: api@homeward.com
url: https://api-docs.homeward.com/
x-apisjson-source: postman/homeward-offer-estimate-postman.json
x-generated: '2026-07-19'
x-method: derived
servers:
- url: https://api.homeward.com
description: Production API host (BASE_URL)
tags:
- name: Offer Requests
description: Create, read, and update partner offer requests
- name: Buybox
description: Property eligibility checks
- name: Finalization
description: Finalize a lead in the Homeward application
paths:
/api/1.0.0/partner/offer-request/:
post:
operationId: createOfferRequest
tags: [Offer Requests]
summary: Create an offer request
description: >-
An Offer Request is a request from a partner to receive a Homeward Offer
Estimate. Posted from partner to Homeward. On success Homeward returns
the offer estimate details; if the property is denied, reason_for_denial
is populated and the offer fields are null.
security:
- tokenAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/OfferRequest'
responses:
'201':
description: Offer request created successfully
content:
application/json:
schema:
$ref: '#/components/schemas/OfferEstimate'
'400':
description: Homeward request is invalid
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'401':
description: Missing or invalid authentication token
/api/1.0.0/estimate/sell/{preliminary_offer_id}/:
get:
operationId: getOfferEstimate
tags: [Offer Requests]
summary: Offer Estimate Information
description: >-
Returns the full offer breakdown for a preliminary offer so partners can
display and explain the Homeward Offer (opinion of value, milestones,
net proceeds, fees, program details).
security:
- tokenAuth: []
parameters:
- name: preliminary_offer_id
in: path
required: true
schema: { type: string, format: uuid }
- name: fmt
in: query
required: false
schema: { type: string, enum: [json] }
responses:
'200':
description: Preliminary Offer Information
content:
application/json:
schema:
$ref: '#/components/schemas/OfferBreakdown'
'401':
description: Missing or invalid authentication token
/api/1.0.0/partner/offer-request/{offer_request_id}/agent/:
patch:
operationId: updateOfferRequestAgent
tags: [Offer Requests]
summary: Update offer request agent
description: >-
Update the real estate agent details for a partner offer request. The
offer_request_id may be the partner_offer_request_id supplied at
creation or the homeward_offer_id returned at creation. All fields are
optional but the entire agent resource is replaced with what is
provided.
security:
- tokenAuth: []
parameters:
- name: offer_request_id
in: path
required: true
schema: { type: string }
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Agent'
responses:
'200':
description: Offer request agent updated
content:
application/json:
schema:
$ref: '#/components/schemas/OfferEstimateWithAgent'
'400':
description: The request is invalid
'401':
description: Missing or invalid authentication token
/buybox/:
post:
operationId: checkBuyboxEligibility
tags: [Buybox]
summary: Buybox eligibility check
description: >-
Quick check of whether a property is likely within Homeward's buybox.
Not a definitive determination. Per the docs this endpoint is separate
from the rest of the API, requires no credential, and uses a different
base URL / path format. Only state is required; more values improve
accuracy.
security: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/BuyboxRequest'
responses:
'200':
description: Eligibility result
content:
application/json:
schema:
$ref: '#/components/schemas/BuyboxResult'
'422':
description: Unprocessable request (validation failed)
/agents/finalize-lead/{lead_id}/:
post:
operationId: finalizeOfferRequest
tags: [Finalization]
summary: Finalize an offer request
description: >-
Finalize a Homeward Offer Estimate via the link returned by
createOfferRequest. Redirects the user into the Homeward application,
which may require additional information. Served from the Homeward
front-end host (FE_URL), not the API host.
servers:
- url: https://app.homeward.com
description: Homeward front-end host (FE_URL)
parameters:
- name: lead_id
in: path
required: true
schema: { type: string }
responses:
'302':
description: Redirect to the Homeward application
components:
securitySchemes:
tokenAuth:
type: apiKey
in: header
name: Authentication
description: >-
Token authentication. Provide the testing or production token issued by
Homeward in the Authentication header. Contact api@homeward.com to
obtain tokens.
schemas:
OfferRequest:
type: object
required:
- partner_offer_request_id
- street_one
- city
- state
- postal_code
- customer_first_name
- customer_last_name
- customer_email
properties:
partner_offer_request_id: { type: string, description: Unique ID configured by the partner }
street_one: { type: string, description: Street address }
street_two: { type: string, description: Unit information }
city: { type: string }
state: { type: string, description: Standard 2-letter state abbreviation }
postal_code: { type: string, description: Postal code only, no +4 identifier }
customer_first_name: { type: string }
customer_last_name: { type: string }
customer_email: { type: string, format: email, description: Must be a unique email }
customer_phone: { type: string }
agent_first_name: { type: string }
agent_last_name: { type: string }
agent_email: { type: string, format: email }
agent_phone: { type: string }
bedrooms: { type: integer }
bathrooms: { type: string }
home_size_sq_ft: { type: integer }
outstanding_loan_amount: { type: integer }
agent_opinion_of_value: { type: integer }
home_listing_status:
type: string
description: If already listed on MLS
enum: [Coming Soon, Listed, Expired, Withdrawn, Cancelled, Under Contract, Sold]
home_stories: { type: integer }
master_on_main: { type: boolean }
additions_made: { type: boolean }
addition_sqft: { type: integer }
has_basement: { type: boolean }
basement_sqft: { type: integer }
kitchen_countertop_type:
type: string
enum: [corian, formica, granite, granite tile, other tile, Quartz]
garage_spaces_count: { type: integer }
hvac_age: { type: integer, description: Age of the HVAC system in years }
repair_or_update_detail: { type: string }
photos:
type: array
items: { type: string }
property_type:
type: string
enum: [Single Family, Unknown, Multi-Family, Luxury, Condo, Lot, Other, Commercial, Mobile Home, Townhouse, Timeshare]
has_solar_panels: { type: boolean }
year_built: { type: integer }
lot_size_acres: { type: integer }
OfferEstimate:
type: object
properties:
partner_offer_request_id: { type: string }
homeward_offer_id: { type: string, format: uuid }
offer_amount: { type: [integer, 'null'] }
opinion_of_value_min: { type: [integer, 'null'] }
opinion_of_value_max: { type: [integer, 'null'] }
expiration_date: { type: [string, 'null'], format: date }
preliminary_offer_pdf: { type: [string, 'null'], format: uri }
offer_finalization_link: { type: [string, 'null'], format: uri }
reason_for_denial: { type: [string, 'null'] }
preliminary_offer_id: { type: [string, 'null'], format: uuid }
OfferEstimateWithAgent:
allOf:
- $ref: '#/components/schemas/OfferEstimate'
- type: object
properties:
agent: { $ref: '#/components/schemas/Agent' }
Agent:
type: object
properties:
first_name: { type: string }
last_name: { type: string }
email: { type: string, format: email }
phone: { type: string, description: '10-digit phone with area code; accepts 999-888-7777, (999) 888-7777, 999.888.7777, 9998887777' }
OfferBreakdown:
type: object
properties:
opinion_of_value: { type: integer }
opinion_of_value_min: { type: integer }
opinion_of_value_max: { type: integer }
address: { $ref: '#/components/schemas/EstimateAddress' }
milestone_one: { type: integer }
milestone_two: { type: integer }
milestone_three: { type: integer }
milestone_four: { type: integer }
milestone_five: { type: integer }
net_offer_price: { type: integer }
net_offer_price_min: { type: integer }
net_offer_price_max: { type: integer }
homeward_partial_program_fee: { type: integer }
homeward_program_fee_adjustment: { type: integer }
incremental_sale_proceeds: { type: integer }
listing_cost_adjustment: { type: integer }
listing_cost_credit: { type: integer }
net_proceeds_from_homeward_purchase: { type: integer }
net_proceeds_from_homeward_sale: { type: integer }
offer_price_percentage: { type: integer }
program_fee: { type: number }
program_fee_base: { type: integer }
sale_price_estimate: { type: integer }
seller_expenses: { type: integer }
seller_upside_percentage: { type: integer }
standard_closing_costs: { type: integer }
total_program_proceeds: { type: integer }
total_program_proceeds_min: { type: integer }
total_program_proceeds_max: { type: integer }
total_commission_percentage: { type: string }
id: { type: string }
lead_id: { type: string }
EstimateAddress:
type: object
properties:
street: { type: string }
unit: { type: string }
city: { type: string }
state: { type: string }
zip: { type: string }
BuyboxRequest:
type: object
required: [property_address]
properties:
property_address:
type: object
required: [state]
properties:
street_one: { type: string }
street_two: { type: string }
city: { type: string }
state: { type: string, description: Standard 2-letter state abbreviation }
postal_code: { type: string }
opinion_of_value: { type: integer }
lot_size_acres: { type: integer }
property_type:
type: string
enum: [Single Family, Unknown, Multi-Family, Luxury, Condo, Lot, Other, Commercial, Mobile Home, Townhouse, Timeshare]
listing_status:
type: string
enum: [Listed, Not Listed, Unknown]
year_built:
type: [integer, string]
BuyboxResult:
type: object
required: [is_eligible]
properties:
is_eligible: { type: boolean }
reason_for_denial:
type: [string, 'null']
description: >-
One of: Property lot size is outside of buybox; Year built is
outside of buybox; Listing status is outside of buybox; Estimated
sale price outside of buybox; Property type is outside of buybox;
Property address outside of buybox
ErrorEnvelope:
type: object
properties:
status: { type: integer }
data: { type: string, description: Human-readable error detail }