HomeAdvisor JSON Lead Feed

HomeAdvisor provides a simple JSON mechanism for delivering customer leads to a partner endpoint. The leads will be delivered in real-time when a lead is assigned to your account.

Partner Requirements

Testing Endpoint URL:

Please define the secure URL you would like us to post the leads to for testing integration.

Production Endpoint URL:

Please define the secure URL you would like us to post live leads to once the process has been tested.

Handling the Response:

Once we post to your URL, we expect an HTTP Response code "200" back with a message in the body of the response indicating the success or failure of a particular post. Anything other than a success message or a 200 will result in a retry.

Success string:

Please define a word pattern/string that we can search for indicating that the posting was a success. This can be anything you like, and the contents of the response will be stored, so any unique job numbers or other points of data that can be cross referenced are preferred. As an example, a quasi XML response like: <success>job number 12345</success> is suitable.

Errors/Retry:

In the event that we experience an error we will retry the lead 3 times with a 15-minute interval in between retries. Please ensure that these retries do not create duplicate content issues with your system:

Errors include:

  • a response code other than 200
  • a server time-out
  • a 200 with content that doesn't match the "success string"
Field Name Example Data Required Description
name Fancy Nancy Y Homeowner's full name
firstName Fancy Y Homeowner's first name
lastName Nancy Y Homeowner's last name
address 123 Main Y Homeowner's address
city USAville Y Homeowner's city
stateProvince PA Y Homeowner's state / Province code
postalCode 12345 Y Homeowner's ZIP / FSA
primaryPhone 5558675309 Y Homeowner's primary phone ** Please note that this will be your assigned call reporting number if you are participating in the call reporting program.
secondaryPhone 5558675308 N Homeowner's secondary phone, if provided. ** Please note that this will be your assigned call reporting number if you are participating in the call reporting program.
phoneExt 1234 Y Homeowner's extension, if provided. ** Please note that this will be the assigned call reporting extension unique to the homeowner's primary phone number.
secondaryPhoneExt 1234 N Homeowner's secondary extension, if provided. ** Please note that this will be the assigned call reporting extension unique to the homeowner's secondary phone number.
email fancy.nancy@gmail.com Y Homeowner's email
srOid 12345 N Homeadvisor's unique job identifier
leadOid 135911130 N
taskOid 60410 N HomeAdvisor's objective product identifier
taskName Cleaning Services Y HomeAdvisor's readable product name (for presentation only)
interview N An array of the questions and associated answers that are provided by the homeowner during the process of submitting a service request to HomeAdvisor's system. Note that the set of questions and answers varies for different HomeAdvisor task types and is subject to change at any time. ** Please note that the set of questions and answers varies for different HomeAdvisor task types and is subject to change at any time.
interview.question What kind of location is this? N Question presented to the homeowner during the HomeAdvisor service request interview.
interview.answer Home/Residence N Answer provided by the homeowner.
matchType Exact N Exact or Market
leadDescription Instant Booking N Lead Type
comments I'm looking for recurring cleaning services, please. N Comments entered in by the homeowner at the time they requested the service. ** Please be aware that the values here can be blank/empty.
spEntityId 88888888 N The unique business identifier identifying your business account(s) in the HomeAdvisor system.
spCompanyName Maid Service Cleaning, LLC N Your business name in the HomeAdvisor system.
spPartnerId x1x2x3x4x5 N The unique business identifier identifying your business account(s) in your system. A franchise number for example.
crmKey abcdef123456 N The system can pass through a unique CRM platform identifier. It is alpha-numeric and can be up to 256 characters long.
appointment N Included only when a homeowner books an appointment to perform the requested service. ** Please note that you must be participating in the InstantBooking program to receive appointments.
appointment.appointmentOid 1234 Y, If appointment present HomeAdvisor's unique appointment identifier
appointment.status Confirmed Y, If appointment present Status of the appointment (Confirmed, Cancelled, Rescheduled, etc.)
appointment.type Service Y, If appointment present Type of appointment (Service, Estimate, Emergency, etc.)
appointment.start 2015-06-09T12:00:00.000-07:00 Y, If appointment present Appointment start date & time. RFC-3339 formatted dateTime.
appointment.end 2015-06-09T14:00:00.000-07:00 Y, If appointment present Appointment end date & time. RFC-3339 formatted dateTime.
appointment.external_id HA-b97290e2-1441-466a-abb3-e2fda9a94cbc.ics Y, If appointment present HomeAdvisor-specific identifier for this appointment. ** This data is passed in when the appointment is created and must be persisted by you and included with this appointment.

Example Posts:

Without Appointment: 
{
"name":"Fancy Nancy",
"firstName":"Fancy",
"lastName":"Nancy",
"address":"123 Main St",
"city":"USAville",
"stateProvince":"PA",
"postalCode":"12345",
"primaryPhone":"5558675309",
"phoneExt":"1234",
"secondaryPhone":"5558675308",
"secondaryPhoneExt":"1234",
"email":"fancy.nancy@edify.com",
"srOid":87654321,
"leadOid":135911130,
"taskOid":40006,
"taskName":"Maid Service",
"spPartnerId":"54321",
"crmKey":"abcd-12345",
"comments":"I'm looking for recurring cleaning services, please.",
"interview":[
   {
   "question":"What kind of location is this?",
   "answer":"Home/Residence"
   },
   {
   "question":"Cleaning Type Needed",
   "answer":"Recurring Service"
   },
   {
   "question":"Request Stage",
   "answer":"Ready to Hire"
   },
   {
   "question":"Desired Completion Date",
   "answer":"Within 1 week"
   }
],
"matchType":"exact",
"leadDescription":"Exact Match",
"spEntityId":88888888,
"spCompanyName":"Maid Service Cleaning, LLC"
}
With Appointment: 
{
"name":"Fancy Nancy",
"firstName":"Fancy",
"lastName":"Nancy",
"address":"123 Main St",
"city":"USAville",
"stateProvince":"PA",
"postalCode":"12345",
"primaryPhone":"5558675309",
"phoneExt":"1234",
"secondaryPhone":"5558675308",
"secondaryPhoneExt":"1234",
"email":"fancy.nancy@edify.com",
"srOid":87654321,
"leadOid":135911130,
"taskOid":40006,
"taskName":"Maid Service",
"spPartnerId":"54321",
"crmKey":"abcd-12345",
"comments":"I'm looking for recurring cleaning services, please.",
"interview":[
   {
   "question":"What kind of location is this?",
   "answer":"Home/Residence"
   },
   {
   "question":"Cleaning Type Needed",
   "answer":"Recurring Service"
   },
   {
   "question":"Request Stage",
   "answer":"Ready to Hire"
   },
   {
   "question":"Desired Completion Date",
   "answer":"Within 1 week"
   }
],
"matchType":"exact",
"leadDescription":"Exact Match",
"spEntityId":88888888,
"spCompanyName":"Maid Service Cleaning, LLC",
"appointment":{
   "appointmentOid":8668,
   "status":"Confirmed",
   "type":"Service",
   "start":"2015-06-09T12:00:00.000-07:00",
   "end":"2015-06-09T14:00:00.000-07:00",
   "external_id":"HA-b97290e2-1441-466a-abb3-e2fda9a94cbc.ics"
   }
}