Astoria Company Education Integration Instructions




Astoria Company Education Integration Instructions


Contents

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 (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 '12' for Education		 12 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 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!		 Required
session_id This is your Session ID. Optional
rep_id This is your Rep ID. Optional
record_id This is your Record ID. Optional
visitor_id This is your Visitor ID. Optional
category_ids This is your Category IDs, comma separated. Optional
list_id This is your List ID. Optional
school_id This is your School ID. Optional
campus_id This is your Campus ID. Optional
program_id This is your Program ID. Optional
call_id This is your Call ID. Optional
submission_id This is your internal Submission ID. Optional
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
client_lead_price Client Lead Price (NOTE: Only send this value if the client is dynamic pricing) Optional
partner Partner name. Optional
origination_datetime Date/time when lead was submitted by consumer, in format 'YYYY-MM-DD hh:mm:ss',
e.g. '2019-09-21 05:54:22'		 Required
ipaddress Applicants IP address, e.g. '35.175.191.150' Required
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. '29165892'		 Required
first_name Applicants first name. Required
last_name Applicants last name. Required
gender Male or Female?
0 = Male
1 = Female		 Optional
email Email address Required
address1 Street Address Required
address2 Additional Street Address Information Optional
city City Required
state State 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
phone Primary phone number, exactly 10 digits (3 For PhoneAreaCode, 3 For PhoneExchange and 4 For PhoneSuffix ) no (), -, or spaces Required
work_phone Work phone number, exactly 10 digits (3 For PhoneAreaCode, 3 For PhoneExchange and 4 For PhoneSuffix ) no (), -, or spaces Optional
best_contact_time Best time to contact you?.
1 = Anytime
2 = Morning
3 = Afternoon
4 = Evening		 1 Required
dob Applicants date of birth, in the format YYYY-MM-DD, e.g. '1994-07-16' Required
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 Required
year_obtained_hsged Year obtained HSGED. Optional
degree_of_interest Degree of interest.
1 = Associates
2 = Bachelors
3 = Masters
4 = Doctorate
5 = Certificate		 1 Required
program_of_interest Program of interest.
1 = General Business
2 = International Business
3 = Business Administration
4 = Marketing Communications
5 = Management
6 = Accounting/Bookkeeping
7 = Financial Services
8 = Forensic Accounting
9 = Operations Management
10 = Administrative Office Assistant/Secretary
11 = Administrative Support Specialist
12 = Business Office Support
13 = Executive Office Administration
14 = Executive Office Specialist
15 = Office Support Specialist
16 = Office Technology
17 = Professional Administrative Specialist
18 = Information Technology Management
19 = Database Administration
20 = Information Systems and Security
21 = Computer Information Technology
22 = Computer & Business Applications
23 = Computer & Networking Technology
24 = Computer Networking and Security
25 = Computer Networking Management
26 = Computer Operations/Web Design Specialist
27 = Computer Accounting Specialist
28 = Computerized Accounting Technology
29 = Computer Based Administrative Assistant
30 = Computerized Medical Office Assistant
31 = Digital Computer Technology
32 = Graphic Design and Animation
33 = PC Servicing & Repair
34 = Software & Network Administration
35 = Microsoft Office Application Professional
36 = Network Administrator
37 = Web Design
38 = Web Development
39 = Associate in Science in Accounting
40 = Associate in Science in Medical Assisting
41 = Associate in Science in Office Administration
42 = Associate in Science in Office Administration: Executive
43 = Associate in Science in Office Administration: Legal
44 = Associate in Science in Office Administration: Medical
45 = Diagnostic Cardiovascular Sonography
46 = Cardiovascular Technology
47 = Diagnostic Medical Sonography
48 = Electrocardiograph Technician
49 = Surgical Technology
50 = DMS-General
51 = Electronics Technology
52 = Emergency Medical Technician
53 = Esthetics
54 = Health Sciences
55 = Healthcare Management
56 = Public Health
57 = Allied Health
58 = Health Information Technology
59 = Health Services Administration
60 = Health Services Management
61 = Health Claims Examiner/Medical Biller
62 = Health Claims Specialist
63 = Historical Allied Health
64 = Historical Business
65 = Historical Trades
66 = Home Health Aide
67 = Multi-Skill Health Technician
68 = Respiratory Therapy
69 = Phlebotomy
70 = Phlebotomy Technician
71 = Dental Administrative Assistant
72 = Dental Assistant
73 = Forensic Psychology
74 = Psychology
75 = Organizational Psychology
76 = Medical Office
77 = Medical Office Administration
78 = Medical Office Specialist
79 = Medical Administrative Assistant
80 = Professional Medical Assistant
81 = Medical Billing and Coding
82 = Legal Office Administration
83 = Legal Office Assistant
84 = Legal Office Specialist
85 = Legal Office Technology
86 = Paralegal
87 = Legal Studies
88 = Justice Studies - Criminal Justice
89 = Law Enforcement / Corrections
90 = Homeland Security
91 = Certified Nurses Aide
92 = Certified Nursing Assistant
93 = Nursing Assistant
94 = Practical Nursing
95 = Pre LPN
96 = Patient Care Assistant
97 = Patient Care Technician
98 = Patient Care Technician I
99 = Patient Care Technician II
100 = Pharmacy Tech
101 = Pharmacy Technician
102 = Counseling
103 = Substance Abuse Counseling
104 = Massage Therapy
105 = Occupational Therapy
106 = Physical Therapy
107 = Property Management
108 = Hospitality and Restaurant Management
109 = Human Resources
110 = Human Services
111 = Culinary Arts
112 = Cosmetology
113 = Skin Care Specialty
114 = Skin Esthetics
115 = Barbering
116 = Nail Esthetics
117 = Manicuring
118 = Heating, Ventilation, Air Conditioning & Refrigeration
119 = Professional Fitness Trainer
120 = Professional Photography
121 = Fashion Merchandising & Management
122 = Interior Design
123 = Contract Training
124 = Star Tech Teach Out
125 = Teacher Training
126 = Teachers Course
127 = Default Conversion Program
128 = Non Degree Seeking		 1 Required
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 Required
in_military Currently serving in the military?
0 = No
1 = Yes		 0 Required
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 Required
us_citizen US Citizen?
0 = No
1 = Yes		 1 Required
current_employer Name of your current employer. IBM Optional
years_at_employer How many years at current employer? 1 Optional
annual_income Annual income amount. 50000 Optional
delivery_status Lead Delivery type, example: "D" for "delivered" D Required
rn_license Do you have an RN License?
0 = No
1 = Yes		 0 Required
teaching_license Do you have a Teaching License?
0 = No
1 = Yes		 0 Required
orientation Type of School Orientation
1 = Online and Campus
2 = Online Only
3 = Campus Only		 1 Required
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 Required
tcpa_optin Aggree to TCPA?
0 = No
1 = Yes		 0 Required
tcpa_text TCPA text. Required
notes Notes or comments Optional

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-09-21+05%3A54%3A22&ipaddress=35.175.191.150&vendor_lead_id=29165892&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-07-16&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-09-21+05%3A54%3A22&ipaddress=35.175.191.150&vendor_lead_id=29165892&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-07-16&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



© 2011-2019 Astoria Company. All rights reserved.