• Home
  • /
  • Direct Post Specification

API Function - Direct Post Specification

Our Direct Post is a single-step integration process. Commonly, it is referred to as direct post, i.e. you send us a 'direct post' (including all PII) and we purchase the lead (we would respond with our payout) or we reject the lead.

Please review the following to complete the integration. When you believe you are ready, please follow the steps below to test your integration.

Direct Post Request Using HTTP/1.1 POST

Our POST URL is https://www.homecontractors101.com/api/api.php. Please do not begin posting with lead_mode=1 until we have manually verified your test data (in addition to our automatic validation process), and we've explicitly notified you that your campaign has been activated within our system. Any leads posted to the live address while your campaign is still in test mode will return an error and neither be counted nor returned.

The data in the request should be URLENCODED to ensure it is received as intended.

Gateway URL for Get/Post methods: https://www.homecontractors101.com/api/api.php

Spec URL: https://www.homecontractors101.com/partners/view-specification-document
 


When buying leads on a direct post basis you will need to provide the Vendor with the following in addition to these Specs:
  • SRC: Source of the lead
  • Partner API Key: Identifies the Partner passing the request


Leadtype: Home Contractors

Post Required Field name Values Example
YES Key String (provided by site admin) c65KascVo
YES TestLead 1 (Only when testing) 1
NO Universal_Lead_ID Unique string upto Varchar (100) 12A34567-BC8D-890E-0F8G-999999999H0I
YES SRC Assigned by HomeContractors101 company Test
YES LandingPage Assigned by HomeContractors101 company Landing
YES IPAddress Varchar (100) 75.2.92.149
NO Sub_ID Unique value upto Varchar(100) 12
NO Pub_ID Unique value upto Varchar(100) 12345
YES TCPAAgreed Set. Allowed values:
  • Yes
  • No
Yes
NO TCPAText Text of TCPAAgreed upto Varchar (1000) By clicking the button above you acknowledge...
YES FirstName First name of user upto Varchar (100) Sam
YES LastName Last name of user upto Varchar (100) Woods
YES Address Address of user upto Varchar (100) Street 123
YES City Valid US city name upto Varchar (100) Chicago
YES State Valid US state abbreviation. Varchar (2) IL
YES Zip Valid Zip. 5 digits 60610
YES HomePhone Valid phone. 10 digits 9999999999
NO WorkPhone Valid phone. 10 digits 9999999999
NO CellPhone Valid phone. 10 digits 9999999999
YES EmailAddress Valid email upto Varchar (100) sam@gmail.com
YES ProjectType Show All Cabinet Refacing
YES Timeframe Set. Allowed values:
  • Emergency Service
  • Timing Flexible
  • Within 1 Week
  • 1 or 2 Weeks
  • More Than 2 Weeks
 Emergency Service
YES Residential Set. Allowed values:
  • Yes
  • No
 Yes
YES Homeowner Set. Allowed values:
  • Yes
  • No
Yes
NO CabinetArea Set. Allowed values:
  • Kitchen
  • Bathroom
Kitchen
NO SidingMaterial Set. Allowed values:
  • Wood
  • Aluminum
  • Vinyl
  • Brick or Stone
  • Metal
 Wood
NO Windows Set. Allowed values:
  • 1 Window
  • 2-3 Windows
  • 4 Windows
  • 4+ Windows
 1 Window
YES ResponseType Set. Allowed values:
  • JSON
  • XML
JSON




You can send the data as XML or JSON post. You can send the XML or JSON data to the following URLs.

XML Post URL: https://www.homecontractors101.com/api/apiXML.php

Note: To use the Matches and/or Match_With_Partner_Hashes functionality, you must use the XML Post method of this API.


XML Post 
<?xml version="1.0" encoding="utf-8"?>
<Request>
  <Key/>
  <API_Action/>
  <Mode/>
  <Cost/>
  <Allowed_Times_Sold/>
  <Return_Hash_Type/>
  <Return_Hash_Value_Type/>
  <Lead_ID/>
  <Skip_Partner_ID/>
  <TYPE/>
  <Skip_XSL/>
  <Match_With_Partner_ID/>
  <Redirect_URL/>
  <Data>
    <Universal_Lead_ID/>
    <SRC/>
    <Landing_Page/>
    <IP_Address/>
    <Sub_ID/>
    <Pub_ID/>
    <Optout/>
    <Unique_Identifier/>
    <TCPAAgreed/>
    <TCPAText/>
    <FirstName/>
    <LastName/>
    <Address/>
    <City/>
    <State/>
    <Zip/>
    <HomePhone/>
    <WorkPhone/>
    <CellPhone/>
    <EmailAddress/>
    <ProjectType/>
    <Timeframe/>
    <Residential/>
    <Homeowner/>
    <CabinetArea/>
    <SidingMaterial/>
    <Windows/>
  </Data>
  <Matches>
    <Match ValueType="promotionCode" HashType="plain">test code</Match>
    <Match ValueType="promotionCode" HashType="plain">12345</Match>
  </Matches>
  <Match_With_Partner_Hashes>
    <Selected_Partner_Hash ValueType="company" HashType="md5">ewd5692602fc4sa545e4feb0ew3964c5</Selected_Partner_Hash>
    <Selected_Partner_Hash ValueType="company" HashType="md5">f26e492602fc4b4077feb0d80d3964c5</Selected_Partner_Hash>
  </Match_With_Partner_Hashes>
</Request>

JSON Post 
{
    "Request": {
        "Key": "",
        "API_Action": "",
        "Mode": "",
        "Cost": "",
        "Allowed_Times_Sold": "",
        "Return_Hash_Type": "",
        "Return_Hash_Value_Type": "",
        "Lead_ID": "",
        "Skip_Partner_ID": "",
        "TYPE": "",
        "Skip_XSL": "",
        "Match_With_Partner_ID": "",
        "Redirect_URL": "",
        "Universal_Lead_ID": "",
        "SRC": "",
        "Landing_Page": "",
        "IP_Address": "",
        "Sub_ID": "",
        "Pub_ID": "",
        "Optout": "",
        "Unique_Identifier": "",
        "TCPAAgreed": "",
        "TCPAText": "",
        "FirstName": "",
        "LastName": "",
        "Address": "",
        "City": "",
        "State": "",
        "Zip": "",
        "HomePhone": "",
        "WorkPhone": "",
        "CellPhone": "",
        "EmailAddress": "",
        "ProjectType": "",
        "Timeframe": "",
        "Residential": "",
        "Homeowner": "",
        "CabinetArea": "",
        "SidingMaterial": "",
        "Windows": ""
    }
}

Response Matched Example

XML 
<?xml version="1.0" encoding="UTF-8"?>
<response>
	<status>Matched</status>
	<lead_id>874</lead_id>
	<price>25</price>
</response>

JSON 
{
  "response": {
    "status": "Matched",
    "lead_id": "874",
    "price": "25"
  }
}
Response Matched Example with Allowed_Times_Sold used

XML 
<?xml version="1.0" encoding="UTF-8"?>
<response>
	<status>Matched</status>
	<lead_id>874</lead_id>
	<matches>5</matches>
</response>

JSON 
{
  "response": {
    "status": "Matched",
    "lead_id": "874",
    "matches": "5"
  }
}
Response - error

XML 
<?xml version="1.0" encoding="UTF-8"?>
<response>
	<status>Error</status>
	<error>Required value First_Name is missing</error>
</response>

JSON 
{
  "response": {
    "status": "Error",
    "error": "Required value First_Name is missing"
  }
}
Name Description Note
error Error message Returned on error
status Status
Request example
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. nisi ut aliquip ex ea commodo consequat.


About Us
Copyright © HomeContractors101