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)
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
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 Homeowner Set. Allowed values:
  • Yes
  • No
NO CabinetArea Set. Allowed values:
  • Kitchen
  • Bathroom
NO SidingMaterial Set. Allowed values:
  • Wood
  • Aluminum
  • Vinyl
  • Brick or Stone
  • Metal
NO Windows Set. Allowed values:
  • 1 Window
  • 2-3 Windows
  • 4 Windows
  • 4+ Windows
1 Window
YES ResponseType Set. Allowed values:
  • JSON
  • XML

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"?>
    <Match ValueType="promotionCode" HashType="plain">test code</Match>
    <Match ValueType="promotionCode" HashType="plain">12345</Match>
    <Selected_Partner_Hash ValueType="company" HashType="md5">ewd5692602fc4sa545e4feb0ew3964c5</Selected_Partner_Hash>
    <Selected_Partner_Hash ValueType="company" HashType="md5">f26e492602fc4b4077feb0d80d3964c5</Selected_Partner_Hash>

    "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 version="1.0" encoding="UTF-8"?>

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

<?xml version="1.0" encoding="UTF-8"?>

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

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

  "response": {
    "status": "Error",
    "error": "Required value First_Name is missing"
Name Description Note
error Error message Returned on error
status Status

About Us
Copyright © HomeContractors101