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. '2021-01-18 05:26:43' |
![]() |
|
ipaddress | Applicants IP address, e.g. '3.232.96.22' | ![]() |
|
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. '32319268' |
![]() |
|
first_name | Applicants first name. | ![]() |
|
last_name | Applicants last name. | ![]() |
|
gender | Male or Female? 0 = Male 1 = Female |
![]() |
|
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. '1995-11-13' | ![]() |
|
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 = 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 | ![]() |
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 many 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 | ![]() |
internet_connection | Do you have a Internet Connection? 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=2021-01-18+05%3A26%3A43&ipaddress=3.232.96.22&vendor_lead_id=32319268&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=1995-11-13&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&internet_connection=1&delivery_status=1&submission_id=1&partner=REPLACE+WITH+PARTNER+NAME
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>
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=2021-01-18+05%3A26%3A43&ipaddress=3.232.96.22&vendor_lead_id=32319268&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=1995-11-13&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&internet_connection=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);
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 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