HomeLight Partner API Documentation

HomeLight's API is centered around providing access to create leads in the HomeLight system.

Working with HomeLight's API

Before making any calls to the API you will need to acquire an API secret and token to be sent in with every request. To do so please reach out to your partnership point of contact or email support@homelight.com.

Environments

Test

https://staging.homelight.com
https://demo.homelight.com

Production

https://www.homelight.com

Endpoints

Creating a New Lead

Request

POST https://staging.homelight.com/api/partner_lead/v2

Parameters

Name	Type	Description
secret	string	Required. The secret key provided to you when you signed up for access to the HomeLight API.
token	string	Required. The secret token provided to you when you signed up for access to the HomeLight API.
leads	array	Required. An array of lead objects representing the leads to be created. See Lead Attributes section below for full definition of the lead object.

Lead Attributes

Name	Type	Description
address	string	Required if the user_type is "seller". The street address for a seller's house.
city	string	Required if zip_code and county is NULL. The city the client is looking to transact in. In format “City Name, State Abbreviation”. Ex. “San Francisco, CA”
zip_code	string	Required if city and county is NULL. Zip code of the house being bought or sold
county	string	Required if city and zip_code is NULL. County of the house being bought or sold. In the format of "County Name, State Abreviation". Ex. "San Francisco County, CA"
email	string	Required. The client’s primary email address.
phone	string	Required. The client's primary phone number, with or without formating.
user_type	string	Required. In list ["buyer", "seller"]
name	string	Required. Full name of the client
price	integer	Highly Recommended. The price the client wants to buy or sell for.
property_type	string	Highly Recommended. The type of property the client wants to buy or sell. In the following list ["single_family_home", "condominium", "townhomes", "tenancy_in_common", "coop", "mobile", "multi_family", "land", "commercial", "other", "rental", "not_sure"]
timeline	string	Highly Recommended. When is the client looking to transact. Value in ["asap", "2_months", "6_months", "10_months", "1_year", "unsure"]
already_has_agent	boolean	An indication of whether the client is in already working with an agent
interested_in_agent	boolean	Whether the client wants to be connected with an agent
bankruptcy	boolean	If the seller is in bankruptcy
baths	integer	The number of bathrooms in the house being sold, or number of desired bathrooms for buying
beds	integer	The number of bedrooms in the house being sold, or number of desired bedrooms for buying
client_notes	string	Any additional information the client wants us to know
credit_rating	integer	An approximate credit score for the client
down_payment	float	Planned down payment percent
email_alt	string	The clients secondary email address
house_underwater	boolean	If the seller's house is underwater
income	integer	Approximate income of the client
intro_requests	string	Optional. Comma separated list Agent's external_id (preferred agents - up to 3)
ip	string	Address of the client
most_important	string	Most important aspect of an agent in list of value ["experience", "top_dollar", "finds_bargains", "availability", "sells_fast"])
phone_alt	string	The client's secondary phone number, with or without formatting
prequalified	boolean	If the buyer is prequalified for a mortgage
sell_reason	string	Reason for selling current house
short_sale	boolean	Is the house being sold as part of a short sale
source_form	string	The form that generated the lead
source_page_type	string	The page type that generate the lead
square_footage	integer	Number of square feet in current house or desired house
supplimental_data	json	Additional data which doesn't belong in any other field here
timeframe	string	Best time for an agent to contact the client
utm_campaign	string	Reach out to your partnership point of contact or email support@homelight.com for this field
utm_content	string	Reach out to your partnership point of contact or email support@homelight.com for this field
utm_medium	string	Reach out to your partnership point of contact or email support@homelight.com for this field
utm_source	string	Reach out to your partnership point of contact or email support@homelight.com for this field
utm_term	string	Reach out to your partnership point of contact or email support@homelight.com for this field

Response Body

{
  "summary": {
    "failed_lead_indexes": [],
    "invalid_lead_indexes": [0],
    "leads_accepted": 1,
    "leads_rejected": 1,
    "leads_submitted": 2
  },
  "leads": [
    {
      "name": "Finn Mertens",
      "accepted": true
    },
    {
      "name": "John DiMaggio",
      "accepted": false,
      "reason": "invalid lead format, see documentation for correct format"
    }
  ]
}

Name	Type	Description
summary	object	An object containing a high level summary of the results of the call.
summary.leads_submitted	integer	The number of leads submitted in the request object.
summary.leads_rejected	integer	The number of leads rejected.
summary.leads_accepted	integer	The number of leads accepted.
summary.invalid_lead_indexes	array	An array of index numbers for leads that failed for validation reasons. You can use this to look up the leads in the response object. The indexes will likely match the input lead indexes, but this is not guaranteed so it is recommended to verify the lead by checking the name attribute.
summary.failed_lead_indexes	array	An array of index numbers for leads that failed for non-validation reasons. You can use this to look up the leads in the response object. The indexes will likely match the input lead indexes, but this is not guaranteed so it is recommended to verify the lead by checking the name attribute. These type of exceptions should be rare and you may need to contact support@homelight.com.
leads	array	An array of lead objects representing the result of each individual lead.
lead.name	string	The inputed name field for this lead. It is only returned to help find a particular lead in the inputed values. Must include first and last name.
lead.accepted	boolean	A boolean value (true or false) indicating if the lead was accepted into the HomeLight system. True means that the lead was accepted, false means that the lead was rejected.
lead.reason	string	The reason for the failing to be accepted. Only present when lead.accepted is false.

Examples

Create 1 lead

Input Format: JSON

curl 'https://staging.homelight.com/api/partner_lead/v2' -H 'Content-Type: application/json' -H 'Accept: application/json' -X POST -d '{'secret':'secret','token':'token','leads':[{'city':'San Francisco, CA','email':'daniel@homelight.com','name':'Daniel Duke','phone':'214.336.0515','price':'123456','property_type':'single_family_home','user_type':'buyer'}]}'

Output Format: JSON

{"summary":{"failed_lead_indexes":[],"invalid_lead_indexes":[],"leads_accepted":1,"leads_rejected":0,"leads_submitted":1},"leads":[{"name":"Daniel Duke","accepted":true}]}

Create 1 lead with 2 preferred agents (intro_request)

Input Format: JSON

curl "https://staging.homelight.com/api/partner_lead/v2" -H "Content-Type: application/json" -H "Accept: application/xml" -X POST -d '{"secret":"secret","token":"token","leads":[{"city":"San Antonio, TX","email":"mark@homelight.com","name":"Mark Johnson","phone":"972.288.6865","price":"300500","property_type":"single_family_home","user_type":"seller","address":"888 OFarrell", "intro_request":"3b003636-a830-4a24-a7b3-fa26202df259,8a502980-66c2-4976-a173-f71e0c62d5ba"}]}'

Output Format: JSON

{"summary": {"failed_lead_indexes": [], "invalid_lead_indexes": [], "leads_accepted": 1, "leads_rejected": 0, "leads_submitted": 1 }, "leads": [{ "name": "Daniel Duke", "accepted": true }] }

Create 2 leads

Input Format: JSON

curl "https://staging.homelight.com/api/partner_lead/v2" -H "Content-Type: application/json" -H "Accept: application/xml" -X POST -d '{"secret":"secret","token":"token","leads":[{"city":"San Francisco, CA","email":"daniel@homelight.com","name":"Daniel Duke","phone":"214.336.0515","price":"123456","property_type":"single_family_home","user_type":"buyer"},{"city":"San Antonio, TX","email":"mark@homelight.com","name":"Mark Johnson","phone":"972.288.6865","price":"300500","property_type":"single_family_home","user_type":"seller","address":"888 OFarrell"}]}'

Output Format: XML

<?xml version='1.0' encoding='UTF-8'?><partner_lead_response_v2><summary><failed_lead_indexes type='array'/><invalid_lead_indexes type='array'/><leads_accepted type='integer'>2</leads_accepted><leads_rejected type='integer'>0</leads_rejected><leads_submitted type='integer'>2</leads_submitted></summary><leads type='array'><lead><name>Daniel Duke</name><accepted type='boolean'>true</accepted></lead><lead><name>Mark Johnson</name><accepted type='boolean'>true</accepted></lead></leads></partner_lead_response_v2>

Create 1 lead

Input Format: XML

curl 'https://staging.homelight.com/api/partner_lead/v2' -H 'Content-Type: text/xml' -H 'Accept: application/json' -X POST -d '<?xml version="1.0" encoding="UTF-8"?><homelight-partner-lead-request><secret>secret</secret><token>token</token><leads type="array"><lead><city>San Francisco, CA</city><email>daniel@homelight.com</email><name>Daniel Duke</name><phone>214.336.0515</phone><price>123456</price><property-type>single_family_home</property-type><user-type>buyer</user-type></lead></leads></homelight-partner-lead-request>'

Output Format: JSON

{"summary":{"failed_lead_indexes":[],"invalid_lead_indexes":[],"leads_accepted":1,"leads_rejected":0,"leads_submitted":1},"leads":[{"name":"Daniel Duke","accepted":true}]}

Create 2 leads

Input Format: XML

curl 'https://staging.homelight.com/api/partner_lead/v2' -H 'Content-Type: text/xml' -H 'Accept: application/xml' -X POST -d '<?xml version="1.0" encoding="UTF-8"?><homelight-partner-lead-request><secret>secret</secret><token>token</token><leads type="array"><lead><city>San Francisco, CA</city><email>daniel@homelight.com</email><name>Daniel Duke</name><phone>214.336.0515</phone><price>123456</price><property-type>single_family_home</property-type><user-type>buyer</user-type></lead><lead><city>San Antonio, TX</city><email>mark@homelight.com</email><name>Mark Johnson</name><phone>972.288.6865</phone><price>300500</price><property-type>condo</property-type><user-type>seller</user-type><address>888 OFarrell</address></lead></leads></homelight-partner-lead-request>'

Output Format: XML

<?xml version="1.0" encoding="UTF-8"?><partner_lead_response_v2><summary><failed_lead_indexes type="array"/><invalid_lead_indexes type="array"/><leads_accepted type="integer">2</leads_accepted><leads_rejected type="integer">0</leads_rejected><leads_submitted type="integer">2</leads_submitted></summary><leads type="array"><lead><name>Daniel Duke</name><accepted type="boolean">true</accepted></lead><lead><name>Mark Johnson</name><accepted type="boolean">true</accepted></lead></leads></partner_lead_response_v2>

Creating a Simple Sale Lead

Request

POST https://staging.homelight.com/leads/partner_simple_sale_lead

Parameters

Name	Type	Description
secret	string	Required. The secret key provided to you when you signed up for access to the HomeLight API.
token	string	Required. The token provided to you when you signed up for access to the HomeLight API.
lead	object	Required. Lead object representing the lead to be created. See lead attributes below for full definition of the lead object.
lead.timeline	string	Required. Value in: [“asap”, “2_months”, “6_months”, “10_months”, “1_year”, "unsure"]
lead.property_type	string	Required. Value in: [“single_family_home”, “condominium”, “townhomes”, “other”]
lead.call_review_condition	string	Required. Value in: [“Needs Nothing”, “Needs A Little Work”, “Needs Significant Work”, “Tear Down”]
lead.call_review_year_built	string	Highly Recommended. Value in: [“2000 or later”, “1990s”, “1980s”, “1970s”, “1960s”, “Before 1960”]
lead.call_review_interested_in_agent	string	Optional. Value in: [true, false]
lead.sell_reason	string	Required. Value in: [“Relocating To New Market”, “Buying/Selling Investment Property”, “Buying/Selling Vacation Property”, “Probate Property”, “Other”]
lead.full_name	string	Required. Client’s full name
lead.email	string	Required. Client’s email
lead.phone	string	Required. Client’s primary phone number. With or without formatting
lead.address	string	Required. Client’s address. Ex.“100 1st Street, San Francisco, California 94105”
lead.marketing_channel	string	Reach out to your partnership point of contact or email support@homelight.com for this field
lead.marketing_source	string	Reach out to your partnership point of contact or email support@homelight.com for this field
lead.utm_source	string	Reach out to your partnership point of contact or email support@homelight.com for this field
lead.utm_medium	string	Reach out to your partnership point of contact or email support@homelight.com for this field
lead.utm_campaign	string	Reach out to your partnership point of contact or email support@homelight.com for this field

Response Body

{
  'validation_error': 'A request with invalid credentials was received and rejected. Please go to https://www.homelight.com and log in to retrieve valid credentials.','
  'token': '8dec6811defc43f793faf18bad2f734bb243023477bf0c844114800d2d1cf60a$$r3GjVgShkQMK0Kwsp8YFqUg=--9ddkRFzAeZ0t9Vl5--69qtSJWM/x00aYS1NPlvIQ=='
}

Name	Type	Description
validation_error	string	On lead creation failure. A description of the failure reason.
token	string	On lead creation success. The lead’s unique token.

Examples

Create Simple Sale lead

Input Format: JSON

curl 'https://staging.homelight.com/leads/partner_simple_sale_lead' -H 'Content-Type: application/json' -H 'Accept: application/json' -X POST -d '{'secret':'secret','token':'token','lead':{"timeline": "asap", "call_review_condition": "Needs Nothing", "property_type": "single_family_home", "call_review_year_built": "1990 or later", "full_name": "Daniel Duke", "email": "daniel@homelight.com", "phone": "(626) 823-9740", "address": "19 Clementina Street, San Francisco, California 94105", "marketing_channel": "partner", "marketing_source": "movoto", "utm_source": "movoto", "utm_medium": "partner", "utm_campaign": "1000050", "sell_reason": "Moving"}}'

Output Format: JSON

{:summary=>{:failed_lead_indexes=>[], :invalid_lead_indexes=>[], :leads_accepted=>1, :leads_rejected=>0, :leads_submitted=>1}, :leads=>[{:name=>"Daniel Duke", :accepted=>true}]}

Duplicate Lead Check

Request

POST https://staging.homelight.com/api/partner_dupe_lead_check

Parameters

Name	Type	Description
secret	string	Required. The secret key provided to you when you signed up for access to the HomeLight API.
token	string	Required. The secret token provided to you when you signed up for access to the HomeLight API.
full_name	string	Required if email and phone_number are blank. Lead's full name.
email	string	Required if full_name and phone_number are blank. Lead's email address.
phone_number	string	Required if full_name and email are blank. Lead's phone number.

Response Body

{
  "duplicate": true,
}

Name	Type	Description
duplicate	boolean	A boolean value (true or false) indicating if the lead is a duplicate. True means that the lead is a duplicate, false means that the lead is not a duplicate.

FAQs

Why is my request getting rejected?
There are a number of reasons a request is rejected, the primary ones are outlined below
1. Typos and Formatting
  Make sure your secret and token are exactly right and do not have extra spaces at the beginning or end.
  Are you using the correct secret/token? We provide different credentials for staging and production. You should use the secret/token that aligns with the correct URL.
  The URL for staging and production should include "www".
  Good: https://www.homelight.com/api/partner_lead/v2
  Bad: homelight.com/api/partner_lead/v2
  Request header should include:-H "Content-Type: text/xml"or-H "Content-Type: application/json"
2. Required attributes - The following attributes are required and if you do not include these in your request, it will be rejected.
  city or zip_code
  City should be formatted like “City Name, State Abbreviation”. Ex. “San Francisco, CA”
  address (Seller or Simple Sale leads)
  email
  phone
  user_type
  name
  timeline (Simple Sale leads only)
  call_review_year_built (Simple Sale leads only)
  call_review_condition (Simple Sale leads only)
  sell_reason (Simple Sale leads only)
3. Attributes that require specific answers - The following attributes require preset answers:
  user_type:
  "buyer"
  "seller"
  property_type:
  "single_family_home"
  "condominium"
  "townhomes"
  "tenancy_in_common"
  "coop"
  "mobile"
  "multi_family"
  "land"
  "commercial"
  "other"
  "rental"
  "not_sure"
  timeline:
  "asap"
  "2_months"
  "6_months"
  "10_months"
  "1_year"
  "unsure"
  call_review_condition (Simple Sale leads):
  “Needs Nothing”
  “Needs A Little Work”
  “Needs Significant Work”
  “Tear Down”
  call_review_year_built (Highly Recommended):
  “2000 or later”
  “1990s”
  “1980s”
  “1970s”
  “1960s”
  “Before 1960”
  sell_reason (Simple Sale leads):
  “Relocating To New Market”
  “Buying/Selling Investment Property”
  “Buying/Selling Vacation Property”
  “Probate Property”
  “Other”

HomeLight Partner API Documentation

Working with HomeLight's API

Environments

Test

Production

Endpoints

Creating a New Lead

Request

Parameters

Lead Attributes

Response Body

Examples

Create 1 lead

Create 1 lead with 2 preferred agents (intro_request)

Create 2 leads

Create 1 lead

Create 2 leads

Creating a Simple Sale Lead

Request

Parameters

Response Body

Examples

Create Simple Sale lead

Duplicate Lead Check

Request

Parameters

Response Body

FAQs

Why is my request getting rejected?