Astoria Company Education Integration Instructions

Astoria Company Education 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

Education 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 '12' for Education	12
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 Sub ID sent to you by the call center. Please ensure you are using the correct Sub ID, otherwise the leads may be credited to another call center!
session_id	This is your Session ID.
rep_id	This is your Rep ID.
record_id	This is your Record ID.
visitor_id	This is your Visitor ID.
category_ids	This is your Category IDs, comma separated.
list_id	This is your List ID.
school_id	This is your School ID.
campus_id	This is your Campus ID.
program_id	This is your Program ID.
call_id	This is your Call ID.
submission_id	This is your internal Submission ID.
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.
client_lead_price	Client Lead Price (NOTE: Only send this value if the client is dynamic pricing)
partner	Partner name.
origination_datetime	Date/time when lead was submitted by consumer, in format 'YYYY-MM-DD hh:mm:ss', e.g. '2019-06-24 17:19:10'
ipaddress	Applicants IP address, e.g. '34.228.194.177'
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. '68000627'
first_name	Applicants first name.
last_name	Applicants last name.
gender	Male or Female? 0 = Male 1 = Female
email	Email address
address1	Street Address
address2	Additional Street Address Information
city	City
state	State
zip	Valid 5-digit US Zip Code. Can be used when lead_mode=0 to influence test results. Click here for full testing instructions.
phone	Primary 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
best_contact_time	Best time to contact you?. 1 = Anytime 2 = Morning 3 = Afternoon 4 = Evening	1
dob	Applicants date of birth, in the format YYYY-MM-DD, e.g. '1994-04-18'
level_of_education	Level type of education. 1 = GED 2 = High School 3 = 0-23 College Credits 4 = 24-47 College Credits 5 = Associate Degree 6 = Bachelors Degree 7 = Masters Degree 8 = Doctorate Degree	1
year_obtained_hsged	Year obtained HSGED.
degree_of_interest	Degree of interest. 1 = Associates 2 = Bachelors 3 = Masters 4 = Doctorate 5 = Certificate	1
program_of_interest	Program of interest. 1 = Accounting 2 = Allied Health 3 = Business Administration 4 = Computer Science 5 = Counseling 6 = Criminal Justice 7 = Database Administration 8 = Finance 9 = Forensic Accounting 10 = Forensic Psychology 11 = Graphic Design 12 = Health Science 13 = Health Technology 14 = Healthcare Management 15 = Homeland Security 16 = Hospitality and Restaurant Management 17 = Human Resources 18 = Human Services 19 = Information Systems and Security 20 = Information Technology 21 = International Business 22 = Law Enforcement / Corrections 23 = Legal 24 = Management and Leadership 25 = Marketing 26 = Massage Therapy 27 = Medical Assisting 28 = Medical Billing and Coding 29 = Nursing 30 = Occupational Therapy 31 = Operations Management 32 = Organizational Psychology 33 = Paralegal 34 = Physical Therapy 35 = Property Management 36 = Psychology 37 = Public Health 38 = Substance Abuse Counseling 39 = Web Design 40 = Web Development	1
highest_high_school_grade	Highest High School Grade. 7 = 7th Grade 8 = 8th Grade 9 = 9th Grade 10 = 10th Grade 11 = 11th Grade 12 = 12th Grade	1
in_military	Currently serving in the military? 0 = No 1 = Yes	0
military_affiliation	Military affiliation. 1 = No US Military Affiliation 2 = US Army 3 = US Air Force 4 = Department of Defense - Civilian 5 = US Marine Corps 6 = US Navy 7 = US Coast Guard	1
us_citizen	US Citizen? 0 = No 1 = Yes	1
current_employer	Name of your current employer.	IBM
years_at_employer	How amay years at current employer?	1
annual_income	Annual income amount.	50000
delivery_status	Lead Delivery type, example: "D" for "delivered"	D
rn_license	Do you have an RN License? 0 = No 1 = Yes	0
teaching_license	Do you have a Teaching License? 0 = No 1 = Yes	0
orientation	Type of School Orientation 1 = Online and Campus 2 = Online Only 3 = Campus Only	1
start_range	When do you want to start school?. 1 = Immediately 2 = 1-3 Months 3 = 4-6 Months 4 = 7-9 Months 5 = 10-12 Months	1
tcpa_optin	Aggree to TCPA? 0 = No 1 = Yes	0
tcpa_text	TCPA text.
notes	Notes or comments

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=12&lead_mode=0&vendor_id=76&sub_id=1&session_id=1&list_id=1&school_id=1&campus_id=1&program_id=1&origination_datetime=2019-06-24+17%3A19%3A10&ipaddress=34.228.194.177&vendor_lead_id=68000627&first_name=John&last_name=Smith&gender=1&email=test%40test.com&address1=123+High+Street&city=anywhere&state=FL&zip=35222&phone=6105551212&work_phone=6105551212&dob=1994-04-18&best_contact_time=1&level_of_education=1&in_military=1&military_affiliation=3&birth_year=1966&orientation=1&start_range=1&rn_license=1&teaching_license=1&delivery_status=1&submission_id=1&partner=REPLACE+WITH+PARTNER+NAME


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 recieved the lead. The 'Response' tag will always contain 'Accepted', but the 'Confirmation' will differ for each response.

<PostResponse>
<Response>Accepted</Response>
<Confirmation>12345678901</Confirmation>
<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>
<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>
<Reason>Unable to Monetize</Reason>
<Message>Bids do not meet minimum_price requirement</Message>
</PostResponse>

<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 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>
<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/fulldirect/';
$headers = array('Content-Type: application/x-www-form-urlencoded');

$request = 'lead_type=12&lead_mode=0&vendor_id=76&sub_id=1&session_id=1&list_id=1&school_id=1&campus_id=1&program_id=1&origination_datetime=2019-06-24+17%3A19%3A10&ipaddress=34.228.194.177&vendor_lead_id=68000627&first_name=John&last_name=Smith&gender=1&email=test%40test.com&address1=123+High+Street&city=anywhere&state=FL&zip=35222&phone=6105551212&work_phone=6105551212&dob=1994-04-18&best_contact_time=1&level_of_education=1&in_military=1&military_affiliation=3&birth_year=1966&orientation=1&start_range=1&rn_license=1&teaching_license=1&delivery_status=1&submission_id=1&partner=REPLACE+WITH+PARTNER+NAME';

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

---