Astoria Company Home Improvement Integration Instructions


Contents

IMPORTANT NOTE: PLEASE ENSURE YOU CAREFULLY FOLLOW THE TESTING INSTRUCTIONS ONCE YOU'VE COMPLETED THE INTEGRATION!




Introduction to Ping/Post

Home Improvement is a two-step integration process. Commonly, it is referred to as ping/post, i.e. first you send us a 'ping' (all data EXCEPT PII) and we respond with a bid (or outright rejection). Assuming we are the winning bidder, you would then 'post' the lead data (this time including PII), along with the <confirmation> code you received in the ping response.

Please review the following to complete the integration. When you believe you are ready, please follow these steps to test your integration, and then email us at tech@astoriacompany.com

Back to contents




Help / Support

For help or support, or if you have any questions during the integration, please email us at tech@astoriacompany.com

Back to contents




Ping:

What is a Ping?

A Ping is a call to our API with all of the lead data EXCEPT the PII. It's purpose is to determine if there is any interest in purchasing the lead, and if there is, to establish the price we would be willing to pay if a subsequent Post for the same lead is accepted.

IMPORTANT NOTE: TO ENSURE YOUR ACCOUNT IS NOT TEMPORARILY SUSPENDED BY OUR AUTO-THROTTLING MECHANISM, PLEASE DO NOT EXCEED 300 PINGS IN ANY 5 MINUTE PERIOD.

Field names and acceptable values

The absence of any required field (Required) will result in an error. If you do not collect the data for a required field, please refer to the 'Suggested Default' column.
Preferred fields (Preferred) may be omitted, but doing so could reduce a lead's chances of finding a buyer.
Optional fields (Optional) can be omitted without any major impact.

Field Contents Suggested Default Required?
lead_type Determines the type of lead.
MUST be '18' for Home Improvement
18 Required
lead_mode Determines if the lead should be treated as a test lead or a live lead.
0 = TEST LEAD
1 = LIVE LEAD
Click here for full testing instructions.
Required
vendor_id This is the VID code you were provided by Astoria; if you do not know it, please contact us.
Please ensure you are using the correct code, otherwise your leads may be credited to another partner!
Required
sub_id Code of your choosing for your own tracking purposes, e.g. '123-ABC'
This should enable us to distinguish your lead sources from each other, so that we can optimize lead flow to buyers.
There is a maximum length of 35 characters, and it may only contain letters, numbers, underscores and hyphens.
Required
tcpa_optin Indicates whether or not the consumer was presented with, and accepted, unambiguous consent to be contacted via automated telephone systems pursuant to TCPA requirements.
0 = No
1 = Yes
Click here for more information.
0 Required
tcpa_text Contains the TCPA language the consumer was presented with on the form where their information was submitted,
e.g. 'By submitting this form…'
Click here for more information.
Required
universal_leadid Unique LeadiD as generated by LeadiD.com,
e.g. '16488153-2843-2AF1-5E26-5335CD0FE810'
Required
origination_datetime Date/time when lead was submitted by consumer, in format 'YYYY-MM-DD hh:mm:ss',
e.g. '2019-09-21 06:34:07'
Required
origination_timezone The timezone for the date/time passed in origination_datetime.
1 = EST / EDT
2 = CST / CDT
3 = MST / MDT
4 = PST / PDT
Required
ipaddress Applicants IP address, e.g. '35.175.191.150' Preferred
user_agent The user agent string for the browser used by the applicant when their information was submitted,
e.g. 'CCBot/2.0 (https://commoncrawl.org/faq/)'
Preferred
vendor_lead_id Your internal ID for this lead (useful if we need to contact you about a specific lead and when processing returns),
e.g. '66095509'
Preferred
url URL of form where lead was generated, e.g. 'http://ratechecker.com/home-improvement/' Preferred
minimum_price Minimum price you would accept for this lead, no $ symbol or commas, e.g. '2.00'
NOTE: For test leads (i.e. where lead_mode=0), our 'buyers' return very low prices (for safety). If you choose to include this optional parameter, then please set it to just '0.01' when testing to ensure you receive the expected responses.
WARNING: Setting a minimum_price will cause you to sell fewer leads!
Optional
zip Valid 5-digit US Zip Code.
Can be used when lead_mode=0 to influence test results.
Click here for full testing instructions.
Required
project Project Code - see See Current Project Values Required
task Task Code - see See Current Task Values Preferred

If project = 91 (Solar) then the following highlighted fields are REQUIRED!

current_provider Consumers current electricity provider - see Electricity Company Values 1 Required
monthly_bill Consumers current electricity monthly bill:
1 = $0-50
2 = $51-100
3 = $101-150
4 = $151-200
5 = $201-300
6 = $301-400
7 = $401-500
8 = $501-600
9 = $601-700
10 = $701-800
11 = $801+
3 Required
property_type Property Type.
1 = Single Family
2 = Multi-Family
3 = Townhome
4 = Condominium
5 = Duplex
6 = Mobile Home
7 = Other
1 Required
roof_type Type of roof on the propery:
1 = Unsure/Other
2 = Clay Or Slate Tile
3 = Composite Shingle
4 = Curved Tile - Concrete
5 = Flat Tile - Concrete
6 = Flat - Rolled Composite / Tar And Gravel
7 = Ground Mount
8 = Membrane Or Foam
9 = Metal Shingle
10 = Shake - Wood; Fiber; Plastic
11 = Sheet Metal
12 = Standing Seam Metal
1 Required
roof_shade How much shade is typical for this roof:
0 = No Shade
1 = A Little Shade
2 = A Lot Of Shade
3 = Uncertain
3 Required
credit_rating The consumers self-assessed credit rating:
1 = Excellent
2 = Good
3 = Fair
4 = Poor
2 Required
timeframe Timeframe Code
1 = Timing is Flexible
2 = 1 to 2 Weeks
3 = 3 to 4 Weeks
4 = 5 to 6 Weeks
5 = 7 to 8 Weeks
6 = 9 to 12 Weeks
1 Required
home_owner Does consumer own their home?
0 = No
1 = Yes
2 = Commercial Property
1 Required
project_status Project Status Code
1 = Ready to Hire
2 = Planning and Budgeting
1 Required
additional_info Any additional information provided by the consumer. Optional

Sending a Ping Request

Ping Request Using HTTP/1.1 POST

Our PING URL is https://api.astoriacompany.com/v2/ping/. 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.

Example Request

URL: https://api.astoriacompany.com/v2/ping/
Content-Type: application/x-www-form-urlencoded

lead_type=18&lead_mode=0&vendor_id=76&sub_id=6&tcpa_optin=1&tcpa_text=By+submitting+this+form...&universal_leadid=16488153-2843-2AF1-5E26-5335CD0FE810&origination_datetime=2019-09-21+06%3A34%3A07&origination_timezone=1&ipaddress=35.175.191.150&user_agent=CCBot%2F2.0+%28https%3A%2F%2Fcommoncrawl.org%2Ffaq%2F%29&vendor_lead_id=66095509&url=http%3A%2F%2Fratechecker.com%2Fhome-improvement%2F&zip=35222&project=96&task=128&timeframe=1&home_owner=1&project_status=1&additional_info=I%27d+like+to+have+all+my+windows+replaced+before+the+next+storm+rolls+in%21

Back to contents




Ping Responses

This is exact text that will definitely be present.
This indicates variable data, or nodes that may or may not be present.

Accept:

NOTE: An 'Accept' response on the PING does NOT indicate we purchased the lead, but ONLY that the lead has passed validation, has not been identified as a duplicate, and that we are responding with a bid for that lead. The 'Response' tag will always contain 'Accepted', but the 'Confirmation' code and the 'Price' will differ for each response.

<PingResponse>
<Response>Accepted</Response>
<Confirmation>12345678901</Confirmation>
<Price>6.00</Price>
</PingResponse>

Reject:

NOTE: There are many reasons why we might reject a ping - below you will see all the possible rejection responses. The 'Response' tag will always contain 'Rejected', and the 'Price' will always be '0.00'. The 'Confirmation' code will differ for each response.

For rejected responses, we also add two extra tags: 'Reason' tells you why the lead was rejected, and 'Message' gives some more descriptive text.

Also, where 'Reason' is 'Errors Detected', we add an 'Errors' section with a separate 'Error' node for each error - see the example below! This is designed to help you troubleshoot and fix any errors found.

<PingResponse>
<Response>Rejected</Response>
<Confirmation>12345678901</Confirmation>
<Price>0.00</Price>
<Reason>No Buyers Found</Reason>
<Message>There were no buyers available to bid on this lead</Message>
</PingResponse>

<PingResponse>
<Response>Rejected</Response>
<Confirmation>12345678901</Confirmation>
<Price>0.00</Price>
<Reason>No Buyers Found</Reason>
<Message>Bids do not meet minimum_price requirement</Message>
</PingResponse>

<PingResponse>
<Response>Rejected</Response>
<Confirmation>12345678901</Confirmation>
<Price>0.00</Price>
<Reason>Maintenance Mode</Reason>
<Message>Our system is currently in maintenance mode</Message>
</PingResponse>

<PingResponse>
<Response>Rejected</Response>
<Confirmation>12345678901</Confirmation>
<Price>0.00</Price>
<Reason>Post data is empty</Reason>
<Message>Please check your integration</Message>
</PingResponse>

<PingResponse>
<Response>Rejected</Response>
<Confirmation>12345678901</Confirmation>
<Price>0.00</Price>
<Reason>Invalid lead_type</Reason>
<Message>Please pass a valid lead_type as per our specs</Message>
</PingResponse>

<PingResponse>
<Response>Rejected</Response>
<Confirmation>12345678901</Confirmation>
<Price>0.00</Price>
<Reason>Invalid lead_type for this vendor_id</Reason>
<Message>You are not currently approved to send leads of the given lead_type</Message>
</PingResponse>

<PingResponse>
<Response>Rejected</Response>
<Confirmation>12345678901</Confirmation>
<Price>0.00</Price>
<Reason>Invalid lead_mode</Reason>
<Message>Please ensure lead_mode is either '0' for TEST or '1' for LIVE</Message>
</PingResponse>

<PingResponse>
<Response>Rejected</Response>
<Confirmation>12345678901</Confirmation>
<Price>0.00</Price>
<Reason>Invalid vendor_id</Reason>
<Message>Please check the vendor_id is correct</Message>
</PingResponse>

<PingResponse>
<Response>Rejected</Response>
<Confirmation>12345678901</Confirmation>
<Price>0.00</Price>
<Reason>Provided vendor_id is in TEST MODE</Reason>
<Message>Please contact us if you believe your account should be in LIVE MODE</Message>
</PingResponse>

<PingResponse>
<Response>Rejected</Response>
<Confirmation>12345678901</Confirmation>
<Price>0.00</Price>
<Reason>Daily Cap Exhausted</Reason>
<Message>Please contact us to increase your daily cap</Message>
</PingResponse>

<PingResponse>
<Response>Rejected</Response>
<Confirmation>12345678901</Confirmation>
<Price>0.00</Price>
<Reason>Per Minute Cap Exhausted</Reason>
<Message>Please contact us to increase your per minute cap</Message>
</PingResponse>

<PingResponse>
<Response>Rejected</Response>
<Confirmation>12345678901</Confirmation>
<Price>0.00</Price>
<Reason>Errors Detected</Reason>
<Message>The following errors were detected in this lead:</Message>
<Errors>
<Error>1</Error>
<Error>2</Error>
<Error>3</Error>
</Errors>
</PingResponse>

<PingResponse>
<Response>Rejected</Response>
<Confirmation>12345678901</Confirmation>
<Price>0.00</Price>
<Reason>Duplicate Lead</Reason>
<Message>Lead was identified as a duplicate in our system</Message>
</PingResponse>

<PingResponse>
<Response>Rejected</Response>
<Confirmation>12345678901</Confirmation>
<Price>0.00</Price>
<Reason>Blacklisted Data</Reason>
<Message>The lead matches data on our internal blacklist - please investigate the lead source</Message>
</PingResponse>

Back to contents




Sample Ping Code

Here is some sample PHP code to help you create your call to our API. This is simple stuff, so you should be able to readily convery it into another programming language if necessary.

$apiUrl = 'https://api.astoriacompany.com/v2/ping/';

$headers = array('Content-Type: application/x-www-form-urlencoded');

$request = 'lead_type=18&lead_mode=0&vendor_id=76&sub_id=6&tcpa_optin=1&tcpa_text=By+submitting+this+form...&universal_leadid=16488153-2843-2AF1-5E26-5335CD0FE810&origination_datetime=2019-09-21+06%3A34%3A07&origination_timezone=1&ipaddress=35.175.191.150&user_agent=CCBot%2F2.0+%28https%3A%2F%2Fcommoncrawl.org%2Ffaq%2F%29&vendor_lead_id=66095509&url=http%3A%2F%2Fratechecker.com%2Fhome-improvement%2F&zip=35222&project=96&task=128&timeframe=1&home_owner=1&project_status=1&additional_info=I%27d+like+to+have+all+my+windows+replaced+before+the+next+storm+rolls+in%21';

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $apiUrl);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, 0);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, 0);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $request);

$response = curl_exec($ch);
curl_close($ch);

Back to contents




Post:

What is a Post?

A Post is a call to our API with all of the lead data INCLUDING the PII. It's purpose is to attempt delivery of the actual lead to us, for the price established on the ping.

Field names and acceptable values

The absence of any required field (Required) will result in an error. If you do not collect the data for a required field, please refer to the 'Suggested Default' column.
Preferred fields (Preferred) may be omitted, but doing so could reduce a lead's chances of finding a buyer.
Optional fields (Optional) can be omitted without any major impact.

To make things easier for you, we have highlighted in green the additional fields that were not included in the Ping, but need to be added for the Post to pass validation.

Field Contents Suggested Default Required?
confirmation_id Astoria provided <Confirmation> code from corresponding ping repsonse.
MUST be provided on Post, else it will be treated as a fresh Ping.
Required
lead_type Determines the type of lead.
MUST be '18' for Home Improvement
18 Required
lead_mode Determines if the lead should be treated as a test lead or a live lead.
0 = TEST LEAD
1 = LIVE LEAD
Click here for full testing instructions.
Required
vendor_id This is the VID code you were provided by Astoria; if you do not know it, please contact us.
Please ensure you are using the correct code, otherwise your leads may be credited to another partner!
Required
sub_id Code of your choosing for your own tracking purposes, e.g. '123-ABC'
This should enable us to distinguish your lead sources from each other, so that we can optimize lead flow to buyers.
There is a maximum length of 35 characters, and it may only contain letters, numbers, underscores and hyphens.
Required
tcpa_optin Indicates whether or not the consumer was presented with, and accepted, unambiguous consent to be contacted via automated telephone systems pursuant to TCPA requirements.
0 = No
1 = Yes
Click here for more information.
0 Preferred
tcpa_text Contains the TCPA language the consumer was presented with on the form where their information was submitted,
e.g. 'By submitting this form…'
Click here for more information.
Preferred
universal_leadid Unique LeadiD as generated by LeadiD.com,
e.g. '16488153-2843-2AF1-5E26-5335CD0FE810'
Preferred
origination_datetime Date/time when lead was submitted by consumer, in format 'YYYY-MM-DD hh:mm:ss',
e.g. '2019-09-21 06:34:07'
Required
origination_timezone The timezone for the date/time passed in origination_datetime.
1 = EST / EDT
2 = CST / CDT
3 = MST / MDT
4 = PST / PDT
Required
ipaddress Applicants IP address, e.g. '35.175.191.150' Required
user_agent The user agent string for the browser used by the applicant when their information was submitted,
e.g. 'CCBot/2.0 (https://commoncrawl.org/faq/)'
Preferred
vendor_lead_id Your internal ID for this lead (useful if we need to contact you about a specific lead and when processing returns),
e.g. '66095509'
Preferred
url URL of form where lead was generated, e.g. 'http://ratechecker.com/home-improvement/' Preferred
minimum_price Minimum price you would accept for this lead, no $ symbol or commas, e.g. '2.00'
NOTE: For test leads (i.e. where lead_mode=0), our 'buyers' return very low prices (for safety). If you choose to include this optional parameter, then please set it to just '0.01' when testing to ensure you receive the expected responses.
WARNING: Setting a minimum_price will cause you to sell fewer leads!
Optional
first_name Applicants first name. Required
last_name Applicants last name. Required
email Email address Required
address Street Address Required
zip Valid 5-digit US Zip Code.
Can be used when lead_mode=0 to influence test results.
Click here for full testing instructions.
Required
primary_phone Primary phone number, exactly 10 digits (3 For PhoneAreaCode, 3 For PhoneExchange and 4 For PhoneSuffix ) no (), -, or spaces Required
secondary_phone Secondary phone number, exactly 10 digits (3 For PhoneAreaCode, 3 For PhoneExchange and 4 For PhoneSuffix ) no (), -, or spaces Optional
project Project Code - see See Current Project Values Required
task Task Code - see See Current Task Values Preferred

If project = 91 (Solar) then the following highlighted fields are REQUIRED!

current_provider Consumers current electricity provider - see Electricity Company Values 1 Required
monthly_bill Consumers current electricity monthly bill:
1 = $0-50
2 = $51-100
3 = $101-150
4 = $151-200
5 = $201-300
6 = $301-400
7 = $401-500
8 = $501-600
9 = $601-700
10 = $701-800
11 = $801+
3 Required
property_type Property Type.
1 = Single Family
2 = Multi-Family
3 = Townhome
4 = Condominium
5 = Duplex
6 = Mobile Home
7 = Other
1 Required
roof_type Type of roof on the propery:
1 = Unsure/Other
2 = Clay Or Slate Tile
3 = Composite Shingle
4 = Curved Tile - Concrete
5 = Flat Tile - Concrete
6 = Flat - Rolled Composite / Tar And Gravel
7 = Ground Mount
8 = Membrane Or Foam
9 = Metal Shingle
10 = Shake - Wood; Fiber; Plastic
11 = Sheet Metal
12 = Standing Seam Metal
1 Required
roof_shade How much shade is typical for this roof:
0 = No Shade
1 = A Little Shade
2 = A Lot Of Shade
3 = Uncertain
3 Required
credit_rating The consumers self-assessed credit rating:
1 = Excellent
2 = Good
3 = Fair
4 = Poor
2 Required
timeframe Timeframe Code
1 = Timing is Flexible
2 = 1 to 2 Weeks
3 = 3 to 4 Weeks
4 = 5 to 6 Weeks
5 = 7 to 8 Weeks
6 = 9 to 12 Weeks
1 Required
home_owner Does consumer own their home?
0 = No
1 = Yes
2 = Commercial Property
1 Required
project_status Project Status Code
1 = Ready to Hire
2 = Planning and Budgeting
1 Required
additional_info Any additional information provided by the consumer. Optional

Sending a Post Request

Post Request Using HTTP/1.1 POST

Our POST URL is https://api.astoriacompany.com/v2/post/. 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.

Example Request

URL: https://api.astoriacompany.com/v2/post/
Content-Type: application/x-www-form-urlencoded

lead_type=18&lead_mode=0&vendor_id=76&sub_id=6&tcpa_optin=1&tcpa_text=By+submitting+this+form...&universal_leadid=16488153-2843-2AF1-5E26-5335CD0FE810&origination_datetime=2019-09-21+06%3A34%3A07&origination_timezone=1&ipaddress=35.175.191.150&user_agent=CCBot%2F2.0+%28https%3A%2F%2Fcommoncrawl.org%2Ffaq%2F%29&vendor_lead_id=66095509&url=http%3A%2F%2Fratechecker.com%2Fhome-improvement%2F&zip=35222&project=96&task=128&timeframe=1&home_owner=1&project_status=1&additional_info=I%27d+like+to+have+all+my+windows+replaced+before+the+next+storm+rolls+in%21&confirmation_id=12345&first_name=John&last_name=Smith&email=test%40test.com&address=123+High+Street&primary_phone=6105551212

Back to contents




Post Responses

This is exact text that will definitely be present.
This indicates variable data, or nodes that may or may not be present.

Accept:

NOTE: An 'Accept' response on the POST indicates we HAVE purchased the lead. The 'Response' tag will always contain 'Accepted', but the 'Confirmation' code and the 'Price' will differ for each response.

<PostResponse>
<Response>Accepted</Response>
<Confirmation>12345678901</Confirmation>
<Price>6.00</Price>
</PostResponse>

Reject:

NOTE: There are many reasons why we might reject a post - below you will see all the possible rejection responses. The 'Response' tag will always contain 'Rejected', and the 'Price' will always be '0.00'. The 'Confirmation' code will differ for each response.

For rejected responses, we also add two extra tags: 'Reason' tells you why the lead was rejected, and 'Message' gives some more descriptive text.

Also, where 'Reason' is 'Errors Detected', we add an 'Errors' section with a separate 'Error' node for each error - see the example below! This is designed to help you troubleshoot and fix any errors found.

<PostResponse>
<Response>Rejected</Response>
<Confirmation>12345678901</Confirmation>
<Price>0.00</Price>
<Reason>Unable to Monetize</Reason>
<Message>All buyers rejected this lead (IF POSSIBLE, WE WILL ATTEMPT TO EXPLAIN WHY HERE)</Message>
</PostResponse>

<PostResponse>
<Response>Rejected</Response>
<Confirmation>12345678901</Confirmation>
<Price>0.00</Price>
<Reason>Unable to Monetize</Reason>
<Message>Bids do not meet minimum_price requirement</Message>
</PostResponse>

<PostResponse>
<Response>Rejected</Response>
<Confirmation>12345678901</Confirmation>
<Price>0.00</Price>
<Reason>Maintenance Mode</Reason>
<Message>Our system is currently in maintenance mode</Message>
</PostResponse>

<PostResponse>
<Response>Rejected</Response>
<Confirmation>12345678901</Confirmation>
<Price>0.00</Price>
<Reason>Post data is empty</Reason>
<Message>Please check your integration</Message>
</PostResponse>

<PostResponse>
<Response>Rejected</Response>
<Confirmation>12345678901</Confirmation>
<Price>0.00</Price>
<Reason>Invalid Confirmation ID</Reason>
<Message>You have passed a confirmation_id which is invalid</Message>
</PostResponse>

<PostResponse>
<Response>Rejected</Response>
<Confirmation>12345678901</Confirmation>
<Price>0.00</Price>
<Reason>Invalid lead_type</Reason>
<Message>Please pass a valid lead_type as per our specs</Message>
</PostResponse>

<PostResponse>
<Response>Rejected</Response>
<Confirmation>12345678901</Confirmation>
<Price>0.00</Price>
<Reason>Invalid lead_type for this vendor_id</Reason>
<Message>You are not currently approved to send leads of the given lead_type</Message>
</PostResponse>

<PostResponse>
<Response>Rejected</Response>
<Confirmation>12345678901</Confirmation>
<Price>0.00</Price>
<Reason>Invalid lead_mode</Reason>
<Message>Please ensure lead_mode is either '0' for TEST or '1' for LIVE</Message>
</PostResponse>

<PostResponse>
<Response>Rejected</Response>
<Confirmation>12345678901</Confirmation>
<Price>0.00</Price>
<Reason>Invalid vendor_id</Reason>
<Message>Please check the vendor_id is correct</Message>
</PostResponse>

<PostResponse>
<Response>Rejected</Response>
<Confirmation>12345678901</Confirmation>
<Price>0.00</Price>
<Reason>Provided vendor_id is in TEST MODE</Reason>
<Message>Please contact us if you believe your account should be in LIVE MODE</Message>
</PostResponse>

<PostResponse>
<Response>Rejected</Response>
<Confirmation>12345678901</Confirmation>
<Price>0.00</Price>
<Reason>Daily Cap Exhausted</Reason>
<Message>Please contact us to increase your daily cap</Message>
</PostResponse>

<PostResponse>
<Response>Rejected</Response>
<Confirmation>12345678901</Confirmation>
<Price>0.00</Price>
<Reason>Per Minute Cap Exhausted</Reason>
<Message>Please contact us to increase your per minute cap</Message>
</PostResponse>

<PostResponse>
<Response>Rejected</Response>
<Confirmation>12345678901</Confirmation>
<Price>0.00</Price>
<Reason>Errors Detected</Reason>
<Message>The following errors were detected in this lead:</Message>
<Errors>
<Error>1</Error>
<Error>2</Error>
<Error>3</Error>
</Errors>
</PostResponse>

<PostResponse>
<Response>Rejected</Response>
<Confirmation>12345678901</Confirmation>
<Price>0.00</Price>
<Reason>Duplicate Lead</Reason>
<Message>Lead was identified as a duplicate in our system</Message>
</PostResponse>

<PostResponse>
<Response>Rejected</Response>
<Confirmation>12345678901</Confirmation>
<Price>0.00</Price>
<Reason>Blacklisted Data</Reason>
<Message>The lead matches data on our internal blacklist - please investigate the lead source</Message>
</PostResponse>

Back to contents




Sample Post Code

Here is some sample PHP code to help you create your call to our API. This is simple stuff, so you should be able to readily convery it into another programming language if necessary.

$apiUrl = 'https://api.astoriacompany.com/v2/post/';
$headers = array('Content-Type: application/x-www-form-urlencoded');

$request = 'lead_type=18&lead_mode=0&vendor_id=76&sub_id=6&tcpa_optin=1&tcpa_text=By+submitting+this+form...&universal_leadid=16488153-2843-2AF1-5E26-5335CD0FE810&origination_datetime=2019-09-21+06%3A34%3A07&origination_timezone=1&ipaddress=35.175.191.150&user_agent=CCBot%2F2.0+%28https%3A%2F%2Fcommoncrawl.org%2Ffaq%2F%29&vendor_lead_id=66095509&url=http%3A%2F%2Fratechecker.com%2Fhome-improvement%2F&zip=35222&project=96&task=128&timeframe=1&home_owner=1&project_status=1&additional_info=I%27d+like+to+have+all+my+windows+replaced+before+the+next+storm+rolls+in%21&confirmation_id=12345&first_name=John&last_name=Smith&email=test%40test.com&address=123+High+Street&primary_phone=6105551212';

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $apiUrl);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, 0);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, 0);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $request);

$response = curl_exec($ch);
curl_close($ch);

Back to contents




Common Mistakes

  • Values must be URL encoded. For example, james.doe@example.com should be james.doe%40example.com and 4 Pennsylvania Plaza should be 4+Pennsylvania+Plaza.
  • All field names and explicitly allowed values (employment_in_month, is_rented, income_payment_type, etc.) are case-sensitive.
  • Passing unlisted values (for example: family for reference_relationship1) will result in errors. Likewise, do not pass empty fields; instead omit the fields.
  • Out-of-range or logically impossible values, like stay_in_month=100, or stay_in_year=100 when dob=1980, will fail.
  • Remember to set lead_mode=1 when you go live!

Back to contents




Testing

For testing, i.e. when lead_mode=0, please attempt at least three different leads, each with a different zip code. One should end with and even number, one should end with an odd number, and one should end with a 0 (zero). The responses generated will vary based on the zip code used, as follows:

  • If you PING a test lead with a zip code that ends with a ZERO (e.g. 19460), you will receive the 'No Coverage' response, i.e. it will be REJECTED on the PING.
  • If you PING a test lead with a zip code that ends with an ODD number (e.g. 19461), you will receive a bid, i.e. it will be ACCEPTED on the PING. When you POST that same lead to us, it will be REJECTED on the POST.
  • If you PING a test lead with a zip code that ends with an EVEN number (e.g. 19462), you will receive a bid. When you POST that same lead to us, it will be ACCEPTED on the POST.

Please email all of the ping and post requests AND their corresponding responses to tech@astoriacompany.com so that we can verify the tests and activate your account.

Testing via a Third Party Service

If you are having issues getting the response you expect, please use hurl.it or a similar service to hit our API with the following settings (refer to this image):

  1. Go to: hurl.it
  2. Select 'POST' in the first dropdown
  3. For the URL, enter: https://api.astoriacompany.com/v2/ping/ (or https://api.astoriacompany.com/v2/post/ if testing a post)
  4. Add a Header: 'Content-Type' with a value of 'application/x-www-form-urlencoded'
  5. Paste your ping or post request into the 'Parameters' text area
  6. Click: Launch Request

Back to contents




Parameter Values

Field Contents Values Allowed Required?
project Project Description 60 => Additions and Remodels
61 => Appraisers and Home Inspectors
62 => Architects
63 => Bathroom Remodeling
64 => Cabinets and Countertops
65 => Carpentry
66 => Carpet
67 => Cleaning
68 => Concrete and Masonry
69 => Custom Homes
70 => Decks and Porches
71 => Decorators and Designers
72 => Doors
73 => Drywall
74 => Electrical
75 => Engineers
76 => Fences
77 => Flooring
78 => Foundations
79 => Garage Doors
80 => Handyman
97 => Home Security
81 => HVAC
125 => Insulation
82 => Kitchen Remodeling
83 => Landscaping
84 => Moving
85 => Painting
86 => Pest Control
87 => Plumbing
88 => Roofing
89 => Siding
90 => Small Projects and Repairs
91 => Solar Energy
92 => Sunrooms
93 => Swimming Pools
94 => Tile Work
95 => Walls
96 => Windows
Required
task Task Description 60 .Additions and Remodels
       1. Additions - Closet
       2. Additions - Garage
       3. Additions - To Existing Structure
       4. Remodel - Accommodate a Disability
       5. Remodel - Basement
       6. Remodel - Garage
       7. Remodel - Multiple Rooms
       8. Other
61 .Appraisers and Home Inspectors
       9. Appraisers - Real Estate
       10. Inspection - General Home
       11. Inspection - Roofing
       12. Other
62 .Architects
63 .Bathroom Remodeling
64 .Cabinets and Countertops
       13. Cabinets - Custom Build
       14. Cabinets - Install
       15. Cabinets - Reface
       16. Cabinets - Refinish
       17. Countertops - Install Stone
       18. Other
65 .Carpentry
       19. Built-In Furniture - Construct
       20. Exterior Trim - Install
       21. Framing - Install
       22. Interior Trim & Moldings - Install
       23. Other
66 .Carpet
       24. Carpet Cleaning
       25. Install Carpets
       26. Other
67 .Cleaning
       27. Building Site - Preparation and Clearing
       28. Cleaning - Exterior
       29. Cleaning - Interior
       30. Toxicity and Mold Removal
       31. Other
68 .Concrete and Masonry
       32. Brick and Stone Patios, Walks & Steps
       33. Driveways & Floors - Install
       34. Driveways & Floors - Install Interlocking Paving
       35. Patios, Walks & Steps - Install Interlocking Paving
       36. Stamped Concrete - Install
       37. Other
69 .Custom Homes
70 .Decks and Porches
       38. Build or Replace
       39. Repair
71 .Decorators and Designers
       40. Designer - Bathroom
       41. Designer - Building
       42. Designer - Interior Lighting Plan
       43. Designer - Kitchen
       44. Designer - Landscape
       45. Designer - Residential
       46. Interior Decorator
       47. Stage a Home
       48. Other
72 .Doors
       49. Install Exterior Doors
       50. Install Interior Doors
       51. Install Sliding Door(s)
73 .Drywall
       52. Install Drywall
       53. Repair Drywall
74 .Electrical
       54. Electrical Wiring or Panel Upgrade
       55. Install a Generator
       56. Install Electrical for Home Addition or Remodel
       57. Install Home Automation System
       58. Install Home Theater Surround Sound
       59. Install Home Theater System or Media Center
       60. Install Home Theater Wiring
       61. Other
75 .Engineers
76 .Fences
       62. Install Aluminum or Steel Fence
       63. Install Wood Fence
       64. Repair Wood Fence
       65. Other
77 .Flooring
       66. Install Simulated Wood or Stone Laminate Flooring
       67. Install Wood Flooring
       68. Refinish Wood Flooring
       69. Other
78 .Foundations
       70. Concrete Foundation - Repair
79 .Garage Doors
80 .Handyman
97 .Home Security
       132. Residential Alarm or Security System - Install
       133. Surveillance Cameras - Install or Repair
       134. Residential Alarm or Security System - Monitor
       135. Other
       136. Business Alarm or Security System - Install
81 .HVAC
       71. Install Central A/C
       72. Install Gas or Electric Boiler or Radiator
       73. Install Gas or Electric Furnace
       74. Install Heat Pump
       75. Install Oil Boiler or Radiator
       76. Install Oil Furnace
       77. Install Swamp Cooler
       78. Other
125 .Insulation
       137. Install Batt, Rolled or Reflective Insulation
       138. Install Blown-In Insulation
       139. Install Soundproofing Insulation
       140. Install Spray Foam Insulation
       141. Other
82 .Kitchen Remodeling
83 .Landscaping
       79. Foundation Drainage Install
       80. Fountain or Waterfall Install
       81. Gazebo or Freestanding Porch - Build or Install
       82. Greenhouse or Conservatorium - Build
       83. Landscaping for Yard or Garden
       84. Pond Install
       85. Retaining Walls Over 3 ft
       86. Retaining Walls Under 3 ft
       87. Other
84 .Moving
       88. Professional Moving Service - Long Distance / Out of State
       89. Other
85 .Painting
       90. Exterior Painting
       91. Interior Painting
       92. Specialty Painting - Faux Finishes
       93. Specialty Painting - Textures
       94. Other
86 .Pest Control
87 .Plumbing
       95. Install a Water Heater
       96. Install or Replace a Sewer Main
       97. Install or Replace a Water Main
       98. Install Plumbing for an Addition or Remodel
       99. Plumbing Repair
       100. Other
88 .Roofing
       101. Install Asphalt Shingle Roofing
       102. Install Flat, Foam, or Single Ply Roofing
       103. Install Gutters
       104. Install Metal Roofing
       105. Install Natural Slate Roofing
       106. Install Traditional Tile Roofing
       107. Install Wood or Composite Roofing
       108. Roofing Repair
       109. Other
89 .Siding
       110. Install Brick or Stone Siding
       111. Install Metal Siding
       112. Install Stucco Siding
       113. Install Vinyl Siding
       114. Install Wood or Fiber-Cement Siding
       115. Other
90 .Small Projects and Repairs
91 .Solar Energy
       116. Solar Electrical
       117. Solar Thermal
92 .Sunrooms
93 .Swimming Pools
       118. Build or Install a Swimming Pool
       119. Remodel a Swimming Pool
       120. Other
94 .Tile Work
       121. Install Ceramic & Porcelain Tile
       122. Install Natural Stone Tile
       123. Tile Repair
       124. Other
95 .Walls
       125. Install Brick, Stone or Block Wall
       126. Install Plaster
       127. Other
96 .Windows
       128. Install Multiple Windows
       129. Install One Window
       130. Install Storm Windows
       131. Window Cleaning
Preferred
Field Contents Values Allowed Required?
current_provider Current Provider Name 1 = Unsure/Not Listed
2 = AECO (Alabama Electric Company)
3 = Alabama Power
4 = Alameda Municipal Power
5 = Alaska Villages Electric Cooperative
6 = Allegheny Power
7 = Alliant Energy
8 = Ambit Energy
9 = Ameren
10 = American Electric Power
11 = Amigo Energy
12 = Anaheim Public Utilities
13 = Appalachian Power
14 = Arizona Public Service
15 = Ashland Electric
16 = Atlantic City Electric
17 = Austin Energy
18 = Avista Utilities
19 = Azusa Light & Water
20 = Baltimore Gas & Electric
21 = Bangor Hydro Electric
22 = Basin Electric Power Cooperative
23 = Batavia Municipal Electric
24 = Bear Valley Electric
25 = Beauregard Electric CO-OP
26 = Benton PUD
27 = Berea Municipal Utilities
28 = Berkeley Electric Cooperative
29 = Berkshire Company
30 = Big Rivers Electric Corporation
31 = Black Hills Energy
32 = Black Hills Power
33 = Blue Grass Energy
34 = Blue Ridge Electrical Membership Corp.
35 = Borough of Ellwood City
36 = Bounce Energy
37 = Braintree Electric Light Department
38 = Brigham City Public Power
39 = Brunswick EMC
40 = Bryan Texas Utilities
41 = Burbank Water & Power
42 = Caddo Electric Cooperative
43 = California Public Utilities Commission
44 = Calpine
45 = Canby Electric
46 = Carteret-Craven Electric Cooperative
47 = CenterPoint Energy
48 = Central Electric Power Cooperative
49 = Central Hudson Gas & Electric
50 = Central Maine Power
51 = Central Montana Electric Power Cooperative
52 = Central Power Electric Cooperative
53 = Central Vermont Public Service
54 = CH Energy Group
55 = Champion Energy Services
56 = Chariton Valley Electric Cooperative
57 = Chelan County Public Utility District
58 = Cherokee Electric Cooperative
59 = Cheyenne Light Fuel & Power
60 = Choptank Electric Cooperative
61 = Chugach Electric Association
62 = Cincinnati Bell Energy
63 = Cirro Energy
64 = Citizens Choice Energy Jamestown BPU
65 = Citizens Electric of Lewisburg
66 = Citizens Utilities Board
67 = City & County of San Francisco
68 = City of Dover Electric Department
69 = City of Milford Electric Department
70 = City of Palo Alto Utilities
71 = City of Rock Hill
72 = City of Safford Electric Department
73 = City of Tallahassee Utilities
74 = City of Vero Beach
75 = City Utilities of Springfield
76 = Claverack REC
77 = Clay Electric Co-op
78 = Clearwater Power
79 = CLECO
80 = Cleveland Electric Illuminating Company
81 = Coast Electric
82 = College Station Utilities
83 = Colorado Springs Utilities
84 = Colton Public Utilities Glendale Public Service Department
85 = Columbia REA
86 = Columbia River Public Utility District
87 = ComEd Electric Company
88 = Connecticut Light & Power
89 = Connecticut Natural Gas
90 = Consolidated Edison Company of New York (Con Edison)
91 = Consolidated Electric Cooperative
92 = Consumers Energy
93 = Copper Valley Electric Association
94 = Coserv Electric
95 = Coweta Fayette EMC
96 = CPS Energy
97 = Dairyland Power Co-op
98 = Danville Utilities
99 = Dayton Power & Light
100 = Delaware Electric Cooperative
101 = Delmarva Power
102 = DEMCO
103 = Denton Municipal Electric
104 = Direct Energy
105 = Dominion Virginia Power
106 = Douglas County Public Utility District
107 = dPi Energy
108 = DTE Energy (Detroit Edison)
109 = Duke Energy
110 = Duke Energy Indiana
111 = Duke Energy Kentucky
112 = Duke Energy NC
113 = Duke Energy Ohio
114 = Duke Energy SC
115 = Duncan Valley Electric Cooperative
116 = Duquesne Light
117 = East River Electric Cooperative
118 = East River Electric Power Co-op
119 = Eau Claire Energy Cooperative
120 = El Paso Electric
121 = Electric Database Publishing
122 = Electric Power Board
123 = Electrical District No. 2
124 = ElectriCities
125 = Emerald PUD
126 = Empire District Electric Company
127 = Entergy
128 = Entrust Energy
129 = Eugene Water & Electric Board
130 = Everything Energy
131 = Excel Energy
132 = Farmers Electrical Cooperative
133 = Farmington Electric Utility System
134 = First Electric Cooperative
135 = First Texas Energy Corporation
136 = FirstEnergy
137 = Fleming-Mason Energy Cooperative
138 = Flint Energies
139 = Florida Municipal Power Agency
140 = Florida Power & Light
141 = Florida Public Utility Company Palm Beach
142 = Gainesville Regional Utilities
143 = Garland Power and Light
144 = Georgetown Utility Services (GUS)
145 = Georgia EMC
146 = Georgia Power
147 = Gexa Energy
148 = Golden Valley Electric Association
149 = Granite State Electric
150 = Grant County Public Utility District
151 = Great River Energy
152 = Green Island Power Authority
153 = Green Mountain Energy
154 = Green Mountain Power
155 = Gridley Municipal Utilities
156 = Guadalupe Valley Electric Cooperative
157 = Gulf Power
158 = GVEC
159 = Halifax Electric Membership
160 = Hawaiian Electric Company (HECO)
161 = Hawaiian Electric Industries
162 = Healdsburg Municipal Electric Department
163 = Henderson Municipal Power and Light
164 = High Plains Power
165 = High West Energy
166 = Highline Electric Association
167 = Holden Municipal Light Department
168 = Holland Board of Public Works
169 = Holy Cross Energy Company
170 = Howard Electric Cooperative
171 = Hutchinson Utilities Commission
172 = Hyrum City Power & Light
173 = IDACORP
174 = Idaho Power
175 = Imperial Irrigation District
176 = Independence Power and Light
177 = Indianapolis Power & Light
178 = Intermountain Power Agency
179 = Intermountain Rural Electric Association
180 = International Electric Power (IEP)
181 = Interstate Power and Light Company
182 = ITC Midwest
183 = Jackson
184 = JEA
185 = Jersey Central Power and Light Company
186 = Jones-Onslow EMC
187 = Just Energy
188 = Kansas City Board of Public Utilities
189 = Kansas City Power & Light
190 = Kauai Island Utility Cooperative (KIUC)
191 = Kaysville City
192 = Kenergy Corp
193 = Kentucky Utilities
194 = Kingsport Power (Appalachian Power)
195 = Kissimmee Utility Authority
196 = Klickitat Public Utility District
197 = Knoxville Utilities Board
198 = Kodiak Electric Association
199 = L&O Power Co-op
200 = La Plata Electric Association
201 = Lafayette Utilities System
202 = Lake Country Power
203 = Lake Worth Utilities
204 = Lakeland Electric
205 = Lamar Light and Power
206 = Lansing Board of Water & Light
207 = LCEC
208 = Lenoir City Utilities Board
209 = Little River Electric Co-Op
210 = Lodi Electric Utility
211 = Long Island Power Authority (LIPA)
212 = Lorain Medina Rural Electric Cooperative
213 = Los Angeles Department of Water and Power
214 = Louisville Gas & Electric
215 = Lower Colorado River Authority
216 = Lower Valley Energy
217 = Lumbee River EMC
218 = Luminant
219 = Madison Gas and Electric
220 = Magic Valley
221 = Magnolia Electric
222 = Mansfield Municipal Electric
223 = Marblehead Electric Light Department
224 = Marshall Municipal Utilities
225 = Mason County Public Utility District 3
226 = Massachusetts Electric
227 = Massachusetts Municipal Wholesale Electric Company (MMWEC)
228 = Massena Electric Department
229 = Maui Electric Company
230 = MDU
231 = Memphis Light Gas and Water
232 = Met-Ed
233 = MidAmerican Energy
234 = Midwest Energy
235 = Minnesota Power
236 = Minnkota Power Cooperative
237 = Mississippi Power Company
238 = Missouri River Energy Services
239 = Modesto Irrigation District
240 = Mojave Electric Cooperative
241 = Montana Electric Cooperatives' Association
242 = Montana-Dakota Utilities
243 = Mountain Utilities
244 = Municipal Light & Power
245 = Nantucket Electric
246 = Narragansett Electric
247 = Nashville Electric Service
248 = National Grid
249 = Navopache Electric Cooperative
250 = Nebraska Public Power District
251 = Nevada Power
252 = New York Power Authority (NYPA)
253 = New York State Electric & Gas (NYSEG)
254 = New-Mac Electric
255 = Norris Electric Cooperative
256 = North Carolina Electric Membership Corp.
257 = North Little Rock Electric
258 = Northeast Utilities
259 = Northern Indiana Public Service Company
260 = Northern Neck Electric Cooperative
261 = Northwestern Energy
262 = NOVEC
263 = NRG Energy
264 = NSTAR
265 = NV Energy
266 = Ocala Electric
267 = Ohio Edison
268 = Oklahoma Gas & Electric
269 = Omaha Public Power District
270 = Oncor Electric (Formerly TXU)
271 = Orange & Rockland
272 = Orlando Utilities Commission
273 = Otter Tail Power Company
274 = Overton Power District No 5
275 = Owensboro Municipal Utilities
276 = Pacific Gas & Electric
277 = PacifiCorp
278 = PacifiCorp (Pacific Power)
279 = PacifiCorp (Rocky Mountain Power)
280 = Pasadena Water & Power
281 = Peabody Municipal Light Plant
282 = PECO
283 = Pedernales Electric Cooperative
284 = Penelec
285 = Penn Power
286 = Pennywise Power
287 = People
288 = PEPCO
289 = Pike County Light & Power Company
290 = Portland General Electric
291 = Potomoc Edison (FirstEnergy)
292 = PowerSouth Energy Cooperative
293 = PPL
294 = Progress Energy Carolinas
295 = Progress Energy Florida
296 = Public Service Company of New Mexico
297 = Public Service Company of Oklahoma
298 = Public Service Electric and Gas Company (PSE&G)
299 = Public Service of NH
300 = Puget Sound Energy
301 = PWC Fayetteville
302 = Randolph Electric Membership Corp
303 = Rappahannock Electric Cooperative
304 = Redding Electric Utility (REU)
305 = Reliant Energy
306 = River Falls Municipal Utility
307 = Riverside Public Utilities
308 = Rochester Gas & Electric
309 = Rochester Public Utilities
310 = Rural Valley Electric Co.
311 = Rushmore Electric Cooperative
312 = Sacramento Municipal Utility District
313 = Salem Electric
314 = Salt River Electric
315 = Salt River Project
316 = Sam Houston Electric
317 = San Diego Gas & Electric
318 = Santee Cooper
319 = Sawnee EMC
320 = Seattle City Light
321 = SELCO
322 = Shenandoah Valley Electric Cooperative
323 = Sierra Pacific Power
324 = Sierra-Pacific Power
325 = Silicon Valley Power
326 = SLECMO
327 = Snohomish County Public Utility District (PUD)
328 = Source Power and Gas
329 = South Carolina Electric & Gas Company
330 = South Central Power Company
331 = Southern California Edison
332 = Southern California Public Power Authority
333 = Southern Maryland Electric Cooperative
334 = Southern Rivers Energy
335 = Southwest Mississippi Electric Power Association
336 = Southwestern Electric Power Company (SWEPCO)
337 = Springfield City Water Light & Power
338 = Star Tex Power
339 = Sterling Municipal Light Department
340 = Stream Energy
341 = Sulphur Springs Valley Electric Cooperative
342 = Summer Energy
343 = Superior Plus Utility
344 = Surprise Valley Power
345 = Sussex Rural Electric Cooperative
346 = SWEPCO
347 = Tacoma Power
348 = Tara Energy
349 = TECO
350 = Tennessee Jackson Energy Authority
351 = Tennessee Valley Authority
352 = Texas Electric Service Company
353 = Tideland EMC
354 = Tillamook PUD
355 = Toledo Edison
356 = Town of Vienna
357 = Tri Eagle Energy
358 = Trico Electric Cooperative
359 = Tri-County Electric
360 = Trinity PUD
361 = Trinity Valley Electric Cooperative
362 = Tucson Electric Power
363 = Turlock Irrigation District (TID)
364 = UGI Utilities
365 = UniSource Energy Services
366 = United Cooperative Services
367 = United Illuminating
368 = United Power Inc
369 = Unitil Corporation
370 = Upper Missouri G&T Cooperative
371 = Upper Peninsula Power Company
372 = Valley Electric Association
373 = Vernon Light & Power
374 = Vineland Municipal Electric Utility
375 = Wake Electric
376 = Wakefield Municipal Gas and Light Department
377 = Wallingford Electric
378 = Wasco Electric
379 = Washington - St. Tammany Electric Cooperative
380 = We Energies
381 = Weakley County Municipal Electric System
382 = Wellsboro Electric Company
383 = West Oregon Electric Cooperative
384 = Westar Energy
385 = Western Massachusetts Electric
386 = Wheeling Electric Power (AEP Ohio)
387 = WIlson Energy
388 = Wiregrass Electric Cooperative
389 = Wisconsin Power and Light Company
390 = Wisconsin Public Service Corporation
391 = Withlacoochee River Electric Cooperative
392 = WTU Retail Energy
393 = Wyandotte Municipal Services
394 = Xcel Energy
395 = XOOM Energy
Preferred