API Function - Ping Post Specification
This function has two modes.
- Ping mode: in "ping" mode you can submit partial lead information as defined in "Ping Required" column of the specification to check if lead can be matched.
- Post mode: Based on the "ping" response (matched, unmatched) you can then post the full lead info. Required fields are defined in "Post Required" column of the specification.
- Cost: optionally, a lead cost can be submitted in the ping request. It then overrides lead cost values in the system. Cost should be sent only in ping mode, in post mode it is ignored. It is also ignored if equal or less then zero value is sent.
Its inputs depend on the lead type configuration. Click on the lead type link to view respective function specification.
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 ping 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
| Ping Required | Post Required | Field name | Values | Example |
|---|---|---|---|---|
| YES | YES | Key | String (provided by site admin) | c65KascVo |
| NO | YES | LeadID | Lead ID number received in response of "ping" mode. | 1234 |
| YES | YES | TestLead | 1 (Only when testing) | 1 |
| NO | NO | Universal_Lead_ID | Unique string upto Varchar (100) | 12A34567-BC8D-890E-0F8G |
| YES | YES | SRC | Assigned by HomeContractors101 company | Test |
| NO | YES | LandingPage | Assigned by HomeContractors101 company | Landing |
| NO | YES | IPAddress | Varchar (100) | 75.2.92.149 |
| NO | NO | Sub_ID | Unique value upto Varchar(100) | 12 |
| NO | NO | Pub_ID | Unique value upto Varchar(100) | 12345 |
| YES | YES | TCPAAgreed | Set. Allowed values:
|
Yes |
| NO | YES | TCPAText | Text of TCPAAgreed upto Varchar (1000) | By clicking the button above you acknowledge... |
| NO | YES | FirstName | First name of user upto Varchar (100) | Sam |
| NO | YES | LastName | Last name of user upto Varchar (100) | Woods |
| NO | YES | Address | Address of user upto Varchar (100) | Street 123 |
| NO | YES | City | Valid US city name upto Varchar (100) | Chicago |
| YES | YES | State | Valid US state abbreviation. Varchar (2) | IL |
| YES | YES | Zip | Valid Zip. 5 digits | 60610 |
| NO | YES | HomePhone | Valid phone. 10 digits | 9999999999 |
| NO | NO | WorkPhone | Valid phone. 10 digits | 9999999999 |
| NO | NO | CellPhone | Valid phone. 10 digits | 9999999999 |
| NO | YES | EmailAddress | Valid email upto Varchar (100) | sam@gmail.com |
| YES | YES | ProjectType | Show All | Cabinet Refacing |
| NO | YES | Timeframe | Set. Allowed values:
|
Emergency Service |
| NO | YES | Residential | Set. Allowed values:
|
Yes |
| YES | YES | Homeowner | Set. Allowed values:
|
Yes |
| NO | NO | CabinetArea | Set. Allowed values:
|
Kitchen |
| NO | NO | SidingMaterial | Set. Allowed values:
|
Wood |
| NO | NO | Windows | Set. Allowed values:
|
1 Window |
| YES | YES | ResponseType | Set. Allowed values:
|
JSON |
| NO | NO | TrustedForm | Unique string upto Varchar (100) | 12A34567-BC8D-890E-0F8G |
| NO | NO | ProjectDescription | Description about the project work upto Varchar (1000) | Lorem Ipsum is simply dummy text of the printing and type setting industry. |
Project Types Sub Fields
| Project Types | Sub Field | Values |
|---|---|---|
| Cabinet Refacing | CabinetArea | Set. Allowed values:
|
| Siding | SidingMaterial | Set. Allowed values:
|
| Window Replacement of Multiple Windows | Windows | Set. Allowed values:
|
| Window Replacement of One Window | Windows | Set. Allowed values:
|
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/api_ping_xml.php XML Post URL: https://www.homecontractors101.com/api/api_post_xml.php XML Post URL: https://www.homecontractors101.com/api/api_ping_json.php XML Post URL: https://www.homecontractors101.com/api/api_post_json.phpNote: To use the Matches and/or Match_With_Partner_Hashes functionality, you must use the XML Post method of this API.
https://www.homecontractors101.com/api/pingapi.php?&Key=WL6msen1&TestLead=1&SRC=HCDemo&ResponseType=JSON&LandingPage=https%3A%2F%2Fwww.homecontractors101.com%2Fpartners%2Fthank-you&IPAddress=59.144.162.5&TCPAAgreed=Yes&TCPAText=By%20clicking%20Get%20Quotes&City=Carson&State=CA&Zip=90745&ProjectType=Cabinet%20Refacing&Timeframe=Emergency%20Service&Residential=Yes&Homeowner=Yes&CabinetArea=Yes
https://www.homecontractors101.com/api/postapi.php?&Key=WL6msen1&TestLead=1&SRC=HCDemo&ResponseType=JSON&LandingPage=https%3A%2F%2Fwww.homecontractors101.com%2Fpartners%2Fthank-you&IPAddress=59.144.162.5&TCPAAgreed=Yes&TCPAText=By%20clicking%20Get%20Quotes&FirstName=Will&LastName=Snow&Address=Street%20-%201&City=Carson&State=CA&Zip=90745&HomePhone=9999999999&EmailAddress=will.snow123@hotmail.com&ProjectType=Cabinet%20Refacing&Timeframe=Emergency%20Service&Residential=Yes&Homeowner=Yes&CabinetArea=Yes&LeadID=1008
Coming Soon
Coming Soon
Coming Soon
Coming Soon
Response Example
JSON
{
"Response": [{
"Status": "Matched",
"LeadID": "874",
"Price": "5.50"
}]
}
XML
<Response>
<Status>Matched</Status>
<LeadID>96</LeadID>
<Price>5.50</Price>
</Response>
Response - error
JSON
{
"Response":[{
"Status":"01",
"Errors":[{
"Error25":"Required value for field IPAddress is missing"
}]
}]
}
XML
<Response>
<Status>01</Status>
<Errors>
<Error25>Required value for field IPAddress is missing</Error25>
</Errors>
</Response>