Astoria Company Installment Loans 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
- Testing
IMPORTANT NOTE: PLEASE ENSURE YOU CAREFULLY FOLLOW THE TESTING INSTRUCTIONS ONCE YOU'VE COMPLETED THE INTEGRATION!
Introduction to Direct Post
Installment Loans 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 these steps to test your 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 '23' for Installment Loans |
23 | ![]() |
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. |
![]() |
|
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! |
![]() |
|
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. |
![]() |
|
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:37:32' |
![]() |
|
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' | ![]() |
|
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/)' |
![]() |
|
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. '86006940' |
![]() |
|
url | URL of form where lead was generated, e.g. 'http://ratechecker.com/auto-insurance/' | ![]() |
|
first_name | Applicants first name. | ![]() |
|
last_name | Applicants last name. | ![]() |
|
mothers_maiden_name | Applicants mothers maiden name. | ![]() |
|
Email address | ![]() |
||
address | Street Address | ![]() |
|
zip | Valid 5-digit US Zip Code. Can be used when lead_mode=0 to influence test results. Click here for full testing instructions. |
![]() |
|
residence_type | Applicants residence status. 0 = Own 1 = Rent |
1 | ![]() |
years_at_residence | Applicants years at residence. 0 = 0 Years 1 = 1 Year 2 = 2 Years 3 = 3 Years 4 = 4 Years 5 = 5 Years 6 = 6 Years 7 = 7 Years 8 = 8 Years 9 = 9 Years 10 = 10 Years Etc. |
3 | ![]() |
months_at_residence | Applicants months at residence. 0 = 0 Months 1 = 1 Month 2 = 2 Months 3 = 3 Months 4 = 4 Months 5 = 5 Months 6 = 6 Months 7 = 7 Months 8 = 8 Months 9 = 9 Months 10 = 10 Months 11 = 11 Months |
0 | ![]() |
primary_phone | Primary phone number, exactly 10 digits (3 For PhoneAreaCode, 3 For PhoneExchange and 4 For PhoneSuffix ) no (), -, or spaces | ![]() |
|
secondary_phone | Secondary phone number, exactly 10 digits (3 For PhoneAreaCode, 3 For PhoneExchange and 4 For PhoneSuffix ) no (), -, or spaces | ![]() |
|
work_phone | Work phone number, exactly 10 digits (3 For PhoneAreaCode, 3 For PhoneExchange and 4 For PhoneSuffix ) no (), -, or spaces | ![]() |
|
dob | Applicants date of birth, in the format YYYY-MM-DD, e.g. '1995-11-13' | ![]() |
|
ssn | Applicants Social Security Number - exactly 9 digits, all numeric. | ![]() |
|
license_number | Applicants drivers license number | ![]() |
|
license_state | Applicants drivers license issuing state. 2-letter state abbreviation, e.g. AL for Alabama, etc |
![]() |
|
credit_rating | Credit Rating 1 = Excellent 2 = Good 3 = Fair 4 = Poor |
3 | ![]() |
employer | Name of the Company | ![]() |
|
job_title | Job Title (free text) | ![]() |
|
occupation | Occupation See Occupation Values |
123 | ![]() |
best_time_contact | Best time to contact applicant about their loan application. 1 = Any Time 2 = Morning 3 = Afternoon 4 = Evening 5 = Business Hours 6 = Weekends |
1 | ![]() |
employment_in_year | Number of years employed, e.g. '1' or '2', etc. | ![]() |
|
employment_in_month | Number of months employed, e.g. '0' or '1', etc; maximum value = '11'. | ![]() |
|
loan_amount | Loan Amount, No $, commas, or decimals | 5000 | ![]() |
income_type | Main source of income. 1 = Employed 2 = Benefits / Fixed Income 3 = Self Employed 4 = Unemployed |
![]() |
|
income_payment_type | How is pay received? 1 = Direct deposit 2 = Check |
![]() |
|
income_cycle | How often is pay received? 1 = Weekly 2 = Bi-Weekly (every 2 weeks) 3 = Twice Monthly 4 = Monthly |
![]() |
|
next_pay_date1 | Next paycheck Date 1 - (YYYY-MM-DD) | ![]() |
|
next_pay_date2 | Next paycheck Date 2 - (YYYY-MM-DD) | ![]() |
|
monthly_income | Monthly Income, No $, commas, or decimals | ![]() |
|
in_military | Currently serving in the military? 0 = No 1 = Yes |
0 | ![]() |
account_type | Has a Saving or Checking account? 1 = Savings 2 = Checking |
![]() |
|
bank_name | Bank name | ![]() |
|
bank_routing_number | Bank routing number, exactly 9 digits, no dashes or spaces | ![]() |
|
bank_account_number | Bank account number | ![]() |
|
bank_account_length_months | Bank account length in month, maximum 2 digits | ![]() |
|
bank_phone | Bank Phone Number | ![]() |
Additional Requirements
To be considered for a loan, a customer must:
- Reside in the United States
- Be employed
Sending a Direct Post Request
Direct Post Request Using HTTP/1.1 POST
Our POST URL is https://api.astoriacompany.com/v2/fulldirect/. 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/fulldirect/
Content-Type: application/x-www-form-urlencoded
lead_type=23&lead_mode=0&vendor_id=76&sub_id=6&tcpa_optin=1&tcpa_text=By+submitting+this+form...&origination_datetime=2021-01-18+05%3A37%3A32&origination_timezone=1&ipaddress=3.232.96.22&user_agent=CCBot%2F2.0+%28https%3A%2F%2Fcommoncrawl.org%2Ffaq%2F%29&vendor_lead_id=86006940&url=http%3A%2F%2Fratechecker.com%2Fpayday%2F&tier=ALL&first_name=John&last_name=Smith&email=test%40test.com&address=123+High+Street&zip=35222&primary_phone=6105551212&dob=1995-11-13&residence_type=1&years_at_residence=3&months_at_residence=0&ssn=123456789&license_number=123456&license_state=PA&credit_rating=3&employer=Big+Company%2C+LLC&job_title=unknown&occupation=123&best_time_contact=1&employment_in_year=3&employment_in_month=0&loan_amount=5000&income_type=1&income_payment_type=1&income_cycle=1&next_pay_date1=2021-01-18&next_pay_date2=2021-01-25&monthly_income=5000&in_military=0&account_type=2&bank_name=TD+Bank&bank_routing_number=123456789&bank_account_number=09876543&bank_account_length_months=36
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><RedirectURL>http://api.astoriacompany.com/redirect/index/12345678901/98765432109/1/1</RedirectURL><Reason></Reason> <Message></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', 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 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>
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/fulldirect/';
$headers = array('Content-Type: application/x-www-form-urlencoded');
$request = 'lead_type=23&lead_mode=0&vendor_id=76&sub_id=6&tcpa_optin=1&tcpa_text=By+submitting+this+form...&origination_datetime=2021-01-18+05%3A37%3A32&origination_timezone=1&ipaddress=3.232.96.22&user_agent=CCBot%2F2.0+%28https%3A%2F%2Fcommoncrawl.org%2Ffaq%2F%29&vendor_lead_id=86006940&url=http%3A%2F%2Fratechecker.com%2Fpayday%2F&tier=ALL&first_name=John&last_name=Smith&email=test%40test.com&address=123+High+Street&zip=35222&primary_phone=6105551212&dob=1995-11-13&residence_type=1&years_at_residence=3&months_at_residence=0&ssn=123456789&license_number=123456&license_state=PA&credit_rating=3&employer=Big+Company%2C+LLC&job_title=unknown&occupation=123&best_time_contact=1&employment_in_year=3&employment_in_month=0&loan_amount=5000&income_type=1&income_payment_type=1&income_cycle=1&next_pay_date1=2021-01-18&next_pay_date2=2021-01-25&monthly_income=5000&in_military=0&account_type=2&bank_name=TD+Bank&bank_routing_number=123456789&bank_account_number=09876543&bank_account_length_months=36';
$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!
Testing
For testing, i.e. when lead_mode=0, please omit the 'tier' parameter (or use 'tier=ALL'), and 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 POST a test lead with a zip code that ends with a ZERO (e.g. 19460) or an ODD number (e.g. 19461), you will receive the 'No Coverage' response, i.e. it will be REJECTED.
- If you POST a test lead with a zip code that ends with an EVEN number (e.g. 19462), it will be ACCEPTED.
Please email all of the 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):
- Go to: hurl.it
- Select 'POST' in the first dropdown
- For the URL, enter: https://api.astoriacompany.com/v2/fulldirect/
- Add a Header: 'Content-Type' with a value of 'application/x-www-form-urlencoded'
- Paste your post request into the 'Parameters' text area
- Click: Launch Request
Field | Contents | Values Allowed | Required? |
---|---|---|---|
occupation | Occupation | 1 => Accounts Pay/Rec. 2 => Actor 3 => Administration/Management 4 => Appraiser 5 => Architect 6 => Artist 7 => Assembler 8 => Auditor 9 => Baker 10 => Bank Teller 11 => Banker 12 => Bartender 13 => Broker 14 => Cashier 15 => Casino Worker 16 => CEO 17 => Certified Public Accountant 18 => Chemist 19 => Child Care 20 => City Worker 21 => Claims Adjuster 22 => Clergy 23 => Clerical/Technical 24 => College Professor 25 => Computer Tech 26 => Construction 27 => Contractor 28 => Counselor 29 => Craftsman/Skilled Worker 30 => Customer Support Rep 31 => Custodian 32 => Dancer 33 => Decorator 34 => Delivery Driver 35 => Dentist 36 => Director 37 => Disabled 38 => Drivers 39 => Electrician 40 => Engineer-Aeronautical 41 => Engineer-Aerospace 42 => Engineer-Chemical 43 => Engineer-Civil 44 => Engineer-Electrical 45 => Engineer-Gas 46 => Engineer-Geophysical 47 => Engineer-Mechanical 48 => Engineer-Nuclear 49 => Engineer-Other 50 => Engineer-Petroleum 51 => Engineer-Structural 52 => Entertainer 53 => Farmer 54 => Fire Fighter 55 => Flight Attend. 56 => Food Service 57 => Health Care 58 => Installer 59 => Instructor 60 => Journalist 61 => Journeyman 62 => LabTech 63 => Laborer/Unskilled Worker 64 => Lawyer 65 => Machine Operator 66 => Machinist 67 => Maintenance 68 => Manufacturer 69 => Marketing 70 => Mechanic 71 => Model 72 => Nanny 73 => Nurse/CNA 74 => Other 75 => Painter 76 => Para-Legal 77 => Paramedic 78 => Personal Trainer 79 => Photographer 80 => Physician 81 => Pilot 82 => Plumber 83 => Police Officer 84 => Postal Worker 85 => Preacher 86 => Pro Athlete 87 => Production 88 => Prof-College Degree 89 => Prof-Specialty Degree 90 => Programmer 91 => Real Estate 92 => Receptionist 93 => Reservation Agent 94 => Restaurant Manager 95 => Retail 96 => Roofer 97 => Sales 98 => Scientist 99 => Secretary 100 => Security 101 => Social Worker 102 => Stocker 103 => Store Owner 104 => Stylist 105 => Supervisor 106 => Teacher 107 => Teacher - with Credentials 108 => Technical/Supervisory 109 => Travel Agent 110 => Truck Driver 111 => Vet 112 => Waitress 113 => Welder 114 => Government 115 => Housewife/Househusband 116 => Retired 117 => Student Not Living w/Parents 118 => Unemployed 119 => Military E1 - E4 120 => Military E5 - E7 121 => Military Officer 122 => Military Other 123 => Unknown 124 => Self Employed 125 => Student Living w/Parents |
![]() |