Astoria Company Payday Short Form Integration Instructions
Contents
- 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 | Required? |
---|---|---|---|
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. '2021-01-18 05:19:15' |
![]() |
|
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. '3.232.96.22' | ![]() |
|
first_name | Applicants first name. | ![]() |
|
last_name | Applicants last name. | ![]() |
|
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=2021-01-18+05%3A19%3A15&origination_timezone=1&ipaddress=3.232.96.22&first_name=John&last_name=Smith&email=test%40test.com&address=123+High+Street&zip=35222&primary_phone=6105551212
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>
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=2021-01-18+05%3A19%3A15&origination_timezone=1&ipaddress=3.232.96.22&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);
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!