This document outlines the Homeward API for seller leads and is exclusively for use by Homeward cash offer digital partners.
\nHave questions? Email us at api@homeward.com
\nFor testing endpoint credentials email us at: api@homeward.com
\nHomeward Delivery of Offer Estimate PDF for partner use: Upon receiving the offer request, we respond to the API submission with Homeward Offer Estimate details for the partner to display in-app with a link to Homeward Offer Estimate PDF.
\nWe use token authentication. Contact us using the methods described above to get a testing and production token, which you can use in an Authentication header to use all of the endpoints below.
\n","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","toc":[],"owner":"15642299","collectionId":"ff69a921-d947-4a29-8586-d4740f01f643","publishedId":"2sA3Qwaopm","public":true,"customColor":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"374759"},"publishDate":"2024-06-13T17:10:59.000Z"},"item":[{"name":"Create an offer request","id":"0d45286c-58d1-4226-9e78-f6866974ef8a","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"bearer","bearer":{"token":"{{bearerToken}}"},"isInherited":false},"method":"POST","header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"body":{"mode":"raw","raw":"{\n \"partner_offer_request_id\": \"123456\",\n \"street_one\": \"123 Main St\",\n \"street_two\": \"\",\n \"city\": \"Austin\",\n \"state\": \"TX\",\n \"postal_code\": \"78704\",\n \"customer_first_name\": \"FirstName\",\n \"customer_last_name\": \"LastName\",\n \"customer_email\": \"email@email.com\",\n \"customer_phone\": \"555-444-3333\",\n \"agent_first_name\": \"AgentFirstName\",\n \"agent_last_name\": \"AgentLastName\",\n \"agent_email\": \"email@email.com\",\n \"agent_phone\": \"222-333-4444\",\n \"bedrooms\": 4,\n \"bathrooms\": \"2.5\",\n \"home_size_sq_ft\": 1300,\n \"outstanding_loan_amount\": 300000,\n \"agent_opinion_of_value\": 450000,\n \"home_listing_status\": \"Not Listed\",\n \"home_stories\": 2,\n \"master_on_main\": true,\n \"additions_made\": false,\n \"addition_sqft\": 0,\n \"has_basement\": true,\n \"basement_sqft\": 400,\n \"kitchen_countertop_type\": \"granite\",\n \"has_kitchen_been_remodeled\": false,\n \"garage_spaces_count\": 2,\n \"hvac_age\": 7,\n \"repair_or_update_detail\": \"Repair or update details here.\",\n \"photos\": [\n \"http://www.photos.com/photo1.jpg\",\n \"http://www.photos.com/photo2.jpg\"\n ],\n \"property_type\": \"Single Family\",\n \"has_solar_panels\": false,\n \"year_built\": 1988,\n \"lot_size_acres\": 0.85\n}","options":{"raw":{"headerFamily":"json","language":"json"}}},"url":"https://{{BASE_URL}}/api/1.0.0/partner/offer-request/","description":"An Offer Request is defined as a request from a partner to receive a Homeward Offer Estimate. This is posted from Partner to Homeward.
\n2xx - everything is OK
4xx - the request Homeward made was invalid
5xx - the request may have been valid, but something went wrong on our side
If an address is denied an offer estimate, the reason_for_denial field will contain a string with information on why the address was rejected. In this case, the offer_amount, expiration_date, preliminary_offer_pdf, and offer_finalization_link fields will also be null. If an offer estimate is created, the reason_for_denial will be null and the other fields will contain values.
reason_for_denial can be any of the following:
\nEstimated sale price is outside of buybox
\nProperty lot size is outside of buybox
\nProperty type is outside of buybox
\nYear built it outside of buybox
\nProperty type 'Townhouse' is outside of buybox
\nProperty type 'Multi-Family' is outside of buybox
\nProperty type 'Luxury' is outside of buybox
\nProperty type 'Condo' is outside of buybox
\nProperty type 'Lot' is outside of buybox
\nProperty type 'Other is outside of buybox
\nProperty type 'Commercial' is outside of buybox
\nProperty type 'MobileHome' is outside of buybox
\nProperty type 'Timeshare' is outside of buybox
\nProperty type 'Unknown' is outside of buybox
\nListing status is outside of buybox
\nThe offer_finalization_link field above has the following two url options:
\nIf agent information was provided, the link will create a viewable application within the agent’s Homeward dashboard and route that agent to their dashboard. If the agent does not have an account with Homeward, it will prompt them to create an account.
\nIf no agent information was provided, the link will send the agent to a Homeward page prompting the agent to either sign-in or create an account with Homeward. This process will add the agent to the offer and route them to their Homeward dashboard.
\nThese JSON fields are helpful if you want to leverage various components of the offer breakdown to better display and explain the Homeward Offer. Please partner with Homeward's Product & Sales teams to best scope out the intended display on your portal or website.
\n","urlObject":{"protocol":"https","path":["api","1.0.0","estimate","sell",":preliminary_offer_id",""],"host":["{{BASE_URL}}"],"query":[{"description":{"content":"The desired format you want to receive the offer estimate details. Valid options are pdf or json.
\n","type":"text/plain"},"key":"fmt","value":"json"}],"variable":[{"description":{"content":"The ID of the offer estimate, which can be found in the response from the initial offer request creation payload.
\n","type":"text/plain"},"type":"any","value":"UUID","key":"preliminary_offer_id"}]}},"response":[{"id":"65a46869-243d-426b-a280-4037aa618e22","name":"Preliminary Offer Information","originalRequest":{"method":"GET","header":[],"url":{"raw":"https://{{BASE_URL}}/api/1.0.0/estimate/sell/:preliminary_offer_id/","protocol":"https","host":["{{BASE_URL}}"],"path":["api","1.0.0","estimate","sell",":preliminary_offer_id",""],"variable":[{"key":"preliminary_offer_id","value":""}]}},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Date","value":"Mon, 24 Jun 2024 21:09:57 GMT"},{"key":"Content-Type","value":"application/json"},{"key":"Content-Length","value":"949"},{"key":"Connection","value":"keep-alive"},{"key":"server","value":"waitress"},{"key":"apigw-requestid","value":"Z5AJ5hx2IAMEJBA="},{"key":"allow","value":"GET, PATCH"},{"key":"Cross-Origin-Opener-Policy","value":"same-origin"},{"key":"referrer-policy","value":"same-origin"},{"key":"vary","value":"Origin"},{"key":"x-content-type-options","value":"nosniff"},{"key":"x-frame-options","value":"DENY"}],"cookie":[],"responseTime":null,"body":"{\n \"opinion_of_value\": 250000,\n \"opinion_of_value_min\": 238000,\n \"opinion_of_value_max\": 260000,\n \"address\": {\n \"street\": \"123 Main St\",\n \"unit\": \"\",\n \"city\": \"Austin\",\n \"state\": \"TX\",\n \"zip\": \"78704\"\n },\n \"milestone_one\": 250000,\n \"milestone_two\": 240000,\n \"milestone_three\": 230000,\n \"milestone_four\": 220000,\n \"milestone_five\": 210000,\n \"net_offer_price\": 210000,\n \"net_offer_price_min\": 205000,\n \"net_offer_price_max\": 215000,\n \"homeward_partial_program_fee\": 16250,\n \"homeward_program_fee_adjustment\": 0,\n \"incremental_sale_proceeds\": 27500,\n \"listing_cost_adjustment\": 1650,\n \"listing_cost_credit\": 13350,\n \"net_proceeds_from_homeward_purchase\": 190979,\n \"net_proceeds_from_homeward_sale\": 25182,\n \"offer_price_percentage\": 84,\n \"program_fee\": 0.07,\n \"program_fee_base\": 17500,\n \"sale_price_estimate\": 250000,\n \"seller_expenses\": 668,\n \"seller_upside_percentage\": 16,\n \"standard_closing_costs\": 1921,\n \"total_program_proceeds\": 216161,\n \"total_program_proceeds_min\": 205000,\n \"total_program_proceeds_max\": 225000,\n \"total_commission_percentage\": \"0.0600\",\n \"id\": \"estimate-id\",\n \"lead_id\": \"lead-id\"\n}"}],"_postman_id":"a9eb3f13-b2eb-44ad-8073-53d4afbebc7b"},{"name":"Finalize an offer request","id":"21774711-82f9-4cfa-b595-0baf44647574","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"noauth","isInherited":false},"method":"POST","header":[],"url":"https://{{FE_URL}}/agents/finalize-lead/:lead_id/","description":"A Homeward Offer Estimate can be finalized through the link provided in the response from the offer estimate creation endpoint. This link redirects users to the Homeward application that may require additional information from the user.
\n","urlObject":{"protocol":"https","path":["agents","finalize-lead",":lead_id",""],"host":["{{FE_URL}}"],"query":[],"variable":[{"description":{"content":"(Required) Unique Homeward ID for the lead
\n","type":"text/plain"},"type":"any","value":"We’ve created this endpoint as a way to do a quick check on whether or not a given property is within Homeward’s buybox. This is not meant to provide a definitive determination, but instead is to provide a method for partners to quickly determine whether or not a property is likely within Homeward’s buybox.
\nThe reasons an Offer Estimate eligibility outcome could be different is incomplete data provided here (eg, optional fields not provided), or from different values in the underlying datasets Homeward uses to evaluate properties, in which case Homeward will always rely on our trusted data sources for Offer Estimate outcomes.
\nNote: Due to its high-traffic nature, this endpoint is totally separate from the rest of our API, does not require a credential, and has a different base url and path format than the rest of the API.
\nAll fields in the payload are optional, with the exception of the state field, which is required. The more values provided, the more accurate the buy-box eligibility will be.
\nIf the request is successful, the response will always include a field called is_eligible that is set to a Boolean, along with reason_for_denial, which will only be populated, if we are unable to validate any of the property information, the reason will be included in the field reason_for_denial.
reason_for_denial can be any of the following:
\nProperty lot size is outside of buybox
\nYear built is outside of buybox
\nListing status is outside of buybox
\nEstimated sale price outside of buybox
\nProperty type is outside of buybox
\nProperty address outside of buybox
\nThis endpoint allows updating the real estate agent details for a specific partner offer request. The provided offer_request_id can be the partner_offer_request_id provided when creating the Offer Request resource, or the homeward_offer_id returned with the creation of the Offer Request.
\nAll fields in the request are optional, but the entire agent resource will be replaced with the information provided.
\n200 - the resource was updated
4XX - the request is invalid
5XX - the request may have been valid, but something went wrong on our side
The response will be a JSON object that includes all the information from the Offer Request POST response, but with the following included:
\nagent (object): An object containing the updated agent details with the following properties:
first_name (string): The first name of the agent.
last_name (string): The last name of the agent.
email (string): The email address of the agent.
phone (string): The phone number of the agent.
The response of this request can be documented as a JSON schema.
\n","urlObject":{"protocol":"https","path":["api","1.0.0","partner","offer-request",":offer_request_id","agent",""],"host":["{{BASE_URL}}"],"query":[],"variable":[{"type":"any","value":"","key":"offer_request_id"}]}},"response":[{"id":"86758573-d70d-4257-8590-2d6facdf0660","name":"Update offer request agent","originalRequest":{"method":"PATCH","header":[{"key":"Content-Type","value":"application/json","type":"text"},{"key":"Accept","value":"application/json","type":"text"},{"key":"Authorization","value":"Bearer