Astoria Company Installment Loans Integration Instructions




Astoria Company Installment Loans Integration Instructions


Contents

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 (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 '23' for Installment Loans		 23 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
origination_datetime Date/time when lead was submitted by consumer, in format 'YYYY-MM-DD hh:mm:ss',
e.g. '2019-05-19 14:32:48'		 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. '18.234.88.196' 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. '34655753'		 Preferred
url URL of form where lead was generated, e.g. 'http://ratechecker.com/auto-insurance/' Required
first_name Applicants first name. Required
last_name Applicants last name. Required
mothers_maiden_name Applicants mothers maiden name. Optional
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
residence_type Applicants residence status.
0 = Own
1 = Rent		 1 Required
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 Required
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 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
work_phone Work phone number, exactly 10 digits (3 For PhoneAreaCode, 3 For PhoneExchange and 4 For PhoneSuffix ) no (), -, or spaces Preferred
dob Applicants date of birth, in the format YYYY-MM-DD, e.g. '1994-03-13' Required
ssn Applicants Social Security Number - exactly 9 digits, all numeric. Required
license_number Applicants drivers license number Required
license_state Applicants drivers license issuing state.
2-letter state abbreviation, e.g. AL for Alabama, etc		 Required
credit_rating Credit Rating
1 = Excellent
2 = Good
3 = Fair
4 = Poor		 3 Required
employer Name of the Company Required
job_title Job Title (free text) Required
occupation Occupation
See Occupation Values		 123 Required
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 Required
employment_in_year Number of years employed, e.g. '1' or '2', etc. Required
employment_in_month Number of months employed, e.g. '0' or '1', etc; maximum value = '11'. Required
loan_amount Loan Amount, No $, commas, or decimals 5000 Required
income_type Main source of income.
1 = Employed
2 = Benefits / Fixed Income
3 = Self Employed
4 = Unemployed		 Required
income_payment_type How is pay received?
1 = Direct deposit
2 = Check		 Required
income_cycle How often is pay received?
1 = Weekly
2 = Bi-Weekly (every 2 weeks)
3 = Twice Monthly
4 = Monthly		 Required
next_pay_date1 Next paycheck Date 1 - (YYYY-MM-DD) Required
next_pay_date2 Next paycheck Date 2 - (YYYY-MM-DD) Required
monthly_income Monthly Income, No $, commas, or decimals Required
in_military Currently serving in the military?
0 = No
1 = Yes		 0 Required
account_type Has a Saving or Checking account?
1 = Savings 2 = Checking		 Required
bank_name Bank name Required
bank_routing_number Bank routing number, exactly 9 digits, no dashes or spaces Required
bank_account_number Bank account number Required
bank_account_length_months Bank account length in month, maximum 2 digits Preferred
bank_phone Bank Phone Number Optional

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=2019-05-19+14%3A32%3A48&origination_timezone=1&ipaddress=18.234.88.196&user_agent=CCBot%2F2.0+%28https%3A%2F%2Fcommoncrawl.org%2Ffaq%2F%29&vendor_lead_id=34655753&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=1994-03-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=2019-05-19&next_pay_date2=2019-05-26&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

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><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>

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/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=2019-05-19+14%3A32%3A48&origination_timezone=1&ipaddress=18.234.88.196&user_agent=CCBot%2F2.0+%28https%3A%2F%2Fcommoncrawl.org%2Ffaq%2F%29&vendor_lead_id=34655753&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=1994-03-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=2019-05-19&next_pay_date2=2019-05-26&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);

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 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):

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

Back to contents



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
Required
© 2011-2019 Astoria Company. All rights reserved.