Astoria Company Payday Short Form Integration Instructions

Introduction to Direct Post
Help / Support
Direct Post
Sending a Direct Post Request
Direct Post Responses
Sample Direct Post Code
Common Mistakes

Introduction to Direct Post

Payday Short Form 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.

Field names and acceptable values

The absence of any required field () 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 () may be omitted, but doing so could reduce a lead's chances of finding a buyer.
Optional fields () can be omitted without any major impact.

Field	Contents	Suggested Default
lead_type	Determines the type of lead. MUST be '31' for Payday Short Form	31
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!
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
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.
origination_datetime	Date/time when lead was submitted by consumer, in format 'YYYY-MM-DD hh:mm:ss', e.g. '2019-05-19 14:20:01'
origination_timezone	The timezone for the date/time passed in origination_datetime. 1 = EST / EDT 2 = CST / CDT 3 = MST / MDT 4 = PST / PDT
ipaddress	Applicants IP address, e.g. '18.234.88.196'
first_name	Applicants first name.
last_name	Applicants last name.
email	Email address
address	Street Address
zip	Valid 5-digit US Zip Code. Can be used when lead_mode=0 to influence test results.
primary_phone	Primary phone number, exactly 10 digits (3 For PhoneAreaCode, 3 For PhoneExchange and 4 For PhoneSuffix ) no (), -, or spaces

Sending a Direct Post Request

Direct Post Request Using HTTP/1.1 POST

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

Example Request

URL: https://api.astoriacompany.com/v2/shortform/

				Content-Type: application/x-www-form-urlencoded

				

				lead_type=31&vendor_id=76&tcpa_optin=1&tcpa_text=By+submitting+this+form...&origination_datetime=2019-05-19+14%3A20%3A01&origination_timezone=1&ipaddress=18.234.88.196&first_name=John&last_name=Smith&email=test%40test.com&address=123+High+Street&zip=35222&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 will differ for each response.

<PostResponse>
<Response>Accepted</Response>
<Confirmation>12345678901</Confirmation>
<Message>Email and SMS sent Successfully</Message>
</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'. 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>
<Reason>Maintenance Mode</Reason>
<Message>Our system is currently in maintenance mode</Message>
</PostResponse>

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

<PostResponse>
<Response>Rejected</Response>
<Confirmation>12345678901</Confirmation>
<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>
<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>
<Reason>Invalid vendor_id</Reason>
<Message>Please check the vendor_id is correct</Message>
</PostResponse>

<PostResponse>
<Response>Rejected</Response>
<Confirmation>12345678901</Confirmation>
<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>
<Reason>Daily Cap Exhausted</Reason>
<Message>Please contact us to increase your daily cap</Message>
</PostResponse>

<PostResponse>
<Response>Rejected</Response>
<Confirmation>12345678901</Confirmation>
<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>
<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>
<Reason>Duplicate Lead</Reason>
<Message>Lead was identified as a duplicate in our system</Message>
</PostResponse>

<PostResponse>
<Response>Rejected</Response>
<Confirmation>12345678901</Confirmation>
<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/shortform/';


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



$request = 'lead_type=31&vendor_id=76&tcpa_optin=1&tcpa_text=By+submitting+this+form...&origination_datetime=2019-05-19+14%3A20%3A01&origination_timezone=1&ipaddress=18.234.88.196&first_name=John&last_name=Smith&email=test%40test.com&address=123+High+Street&zip=35222&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

Astoria Company Payday Short Form Integration Instructions