Difference between revisions of "Send Lead API"

From Netsville Support
Jump to navigation Jump to search
 
(18 intermediate revisions by the same user not shown)
Line 1: Line 1:
 +
=Overview=
 +
This is a work in progress.  This document describes how to submit leads directly to Netsville via an HTTP POST Request.  Requests are submitted to a CGI script with Key-Value Pairs in the BODY of the request.
 +
 +
=Request Requirements=
 +
 +
* POST (only)
 +
 +
Only standard POST requests are allowed.  Either Content-type of '''multipart/form-data''' or '''application/x-www-form-urlencoded'''.
 +
 +
Each key-value pair is separated by an '&' character, and each key is separated from its value by an '=' character. Keys and values are both escaped by replacing spaces with the '+' character and then using URL encoding on all other non-alphanumeric characters.
 +
 +
=URI=
 +
Here is the main URI:
 +
 +
https://www.us-social-security-disability.com/admin/sendlead.php
 +
 +
=Sample Request Body (detail with headers)=
 +
 +
Again, note that all requests to the <strong>https://www.us-social-security-disability.com/admin/sendlead.php</strong> URL must be a valid POST request.  See '''[[ #Sample_PHP_FORM_SUBMIT_script|below]]''' for a coding example in PHP.
 +
 +
POST /admin/sendlead.php HTTP/1.1
 +
User-Agent: Mozilla/5.0 (compatible; MSIE 9.0; Windows NT 6.1; Trident/5.0)
 +
Host: www.us-social-security-disability.com
 +
Accept: */*
 +
Content-Length: 394
 +
Content-Type: application/x-www-form-urlencoded
 +
 +
affiliate_id=123123&name_last=Smith&name_first=John&dob=1985-01-10&email=jsmith@example.com&phone_home=5852325670
 +
&addr_street=69 Cascade Dr&addr_city=Rochester&addr_state=NY&addr_zip=14614&applied_yn=Y&applied_result=denied
 +
&applied_denial_date=2010-12-31&out_of_work_yn=Y&stop_work_date=2009-11-30&work_half_yn=Y&disability=dizziness
 +
&talk_to_lawyer_yn=Y&doc_yn=Y&have_lawyer_yn=N
 +
 +
=Description of Form Fields=
 +
 +
Required fields are in bold.
 +
 
{| class="wikitable" border="1"
 
{| class="wikitable" border="1"
 
!Field||Description||Type||Required||Example
 
!Field||Description||Type||Required||Example
 
|-
 
|-
−
|affiliate_id||Unique identifier given to you by Netsville||Alphanumeric||Yes||ABC123
+
|<strong>affiliate_id</strong>||Unique identifier given to you by Netsville.  A 6-digit number.||Numeric||Yes||123123
 
|-
 
|-
−
|name_last||Last Name of Person||Alpha||Yes||Smith
+
|<strong>name_last</strong>||Last Name of Person||Alpha||Yes||Smith
 
|-
 
|-
−
|name_first||First Name of Person||Alpha||Yes||John
+
|<strong>name_first</strong>||First Name of Person||Alpha||Yes||John
 
|-
 
|-
−
|dob||Date of Birth in YYYY-MM-DD format||Date||Yes||1985-01-15
+
|<strong>dob</strong>||Date of Birth in YYYY-MM-DD format||Date||Yes||1985-01-15
 
|-
 
|-
−
|email||Email address||Email||Yes||jsmith@example.com
+
|<strong>email</strong>||Email address||Email||Yes||jsmith@example.com
 
|-
 
|-
−
|phone_home||10 digit home phone number in NNNXXXYYYY format (numbers only)||Numeric||Yes||5855551212
+
|<strong>phone_home</strong>||10 digit home phone number in NNNXXXYYYY format (numbers only)||Numeric||Yes||5855551212
 
|-
 
|-
−
|addr_street||Street address||Alphanumeric||Yes||123 Main Street
+
|<strong>addr_street</strong>||Street address||Alphanumeric||Yes||123 Main Street
 
|-
 
|-
−
|addr_city||City||Alpha||Yes||Rochester
+
|<strong>addr_city</strong>||City||Alpha||Yes||Rochester
 
|-
 
|-
−
|addr_state||State (two letter abbreviation)||Alpha||Yes||NY
+
|<strong>addr_state</strong>||State (two letter abbreviation)||Alpha||Yes||NY
 
|-
 
|-
−
|addr_zip||Zip code (5 number)||Numeric||Yes||14614
+
|<strong>addr_zip</strong>||Zip code (5 numbers)||Numeric||Yes||14614
 
|-
 
|-
−
|applied_yn||Have you applied for Social Security Disability?<br>Either Yes(Y) or No(N)||Alpha||Yes||Y
+
|<strong>disability</strong>||What is the condition that prevents you from working?||Alpha||Yes||A-Fib, heart condition, dizziness
 
|-
 
|-
−
|applied_result||What was the result of your application? The possible choices are: Claim Pending, Receiving Benefits, Claim Denied.<br>The answer must contain one of these words: 'pending', 'benefits', or 'denied'||Alpha||Yes||denied
+
|<strong>out_of_work_yn</strong>||Do you expect to be out of work for the next 12 months?<br>Either Yes(Y) or No(N)||Alpha||Yes||Y
 +
|-
 +
|<strong>stop_work_date</strong>||The date that you stopped working in YYYY-MM-DD format||Date||Yes||2009-11-30
 +
|-
 +
|<strong>applied_yn</strong>||Have you applied for Social Security Disability?<br>Either Yes(Y) or No(N)||Alpha||Yes||Y
 +
|-
 +
|<strong>applied_result</strong>||What was the result of your application? The possible choices are: Claim Pending, Receiving Benefits, Claim Denied.<br>The answer must contain one of these words: 'pending', 'benefits', or 'denied'||Alpha||Yes||denied
 
|-
 
|-
 
|applied_denial_date||If the above answer contains 'denied', then this field must contain the date of that denial in the format: YYYY-MM-DD.  Otherwise, this field can be empty.||Date||No||2010-12-31
 
|applied_denial_date||If the above answer contains 'denied', then this field must contain the date of that denial in the format: YYYY-MM-DD.  Otherwise, this field can be empty.||Date||No||2010-12-31
 
|-
 
|-
−
|out_of_work_yn||Do you expect to be out of work for the next 12 months?<br>Either Yes(Y) or No(N)||Alpha||Yes||Y
+
|work_half_yn||Have you worked 5 out of the last 10 years? This field can be empty.||Alpha||No||N
 +
|-
 +
|talk_to_lawyer_yn||Would you like a free consultation (speak to a laywer)? If this is blank, YES(Y) is assumed.||Alpha||No||Y
 +
|-
 +
|doc_yn||In the past 6 months, have you seen a doctor?<br>Either Yes(Y) or No(N).  This field can be empty.||Alpha||No||N
 
|-
 
|-
 +
|have_lawyer_yn||Do you currently have an attorney helping you?<br>Either Yes(Y) or No(N).  This field can be empty.||Alpha||No||N
 
|-
 
|-
 
|is_test_lead||A trigger to mark lead as only a test in the database.  Use '1' for Yes and '0' for No.  This field can be empty.||Numeric||No||0
 
|is_test_lead||A trigger to mark lead as only a test in the database.  Use '1' for Yes and '0' for No.  This field can be empty.||Numeric||No||0
 
|}
 
|}
 +
 +
=Return Values=
 +
The result will be of '''Content-type: text/html''' and a single line.  For example:
 +
 +
==A Successful Result==
 +
; RESULT=SUCCESS&RESULT_DETAIL=906 : The RESULT_DETAIL is the id of the lead added to the database if successful.
 +
 +
==An Unsuccessful Result==
 +
; RESULT=ERROR&RESULT_DETAIL=<a list of Missing Fields> : This will be the most common.  If we need to tweak the required fields, we will.
 +
 +
=Other Errors=
 +
; RESULT=ERROR&RESULT_DETAIL=Could not find your affiliate id.  Please contact Netsville. : Unable to find your affiliate id in our database.  Email support@netsville.com to verify your affiliate number.
 +
; RESULT=ERROR&RESULT_DETAIL=Invalid home phone number.  Must be numeric and 10 digits. : Non-numerics will be stripped out, but if the number is the wrong length, this error will be displayed.
 +
; RESULT=ERROR&RESULT_DETAIL=Invalid zip code. : Non-numerics will be stripped out.  Currently only US zip codes are supported.
 +
; RESULT=ERROR&RESULT_DETAIL=Unable to read date. : If the Date of Birth (dob) or Date of Denial (applied_denial_date) is invalid, this error will show up.  See above in Description of Form Fields for the valid format.
 +
 +
=Sample PHP FORM SUBMIT script=
 +
 +
<pre>
 +
<?php
 +
 +
//
 +
// sendlead tester script - a barebones FORM ACTION script in PHP
 +
//
 +
 +
$data = array(
 +
        'affiliate_id' => "123123",
 +
        'name_last' => "Smith",
 +
        'name_first' => "John",
 +
        'dob' => "1985-01-10",
 +
        'email' => "jsmith@example.com",
 +
        'phone_home' => "5852325670",
 +
        'addr_street' => "69 Cascade Dr",
 +
        'addr_city' => "Rochester",
 +
        'addr_state' => "NY",
 +
        'addr_zip' => "14614",
 +
        'applied_yn' => "Y",
 +
        'applied_result' => "denied",
 +
        'applied_denial_date' => "2010-12-31",
 +
        'out_of_work_yn' => "Y",
 +
        'stop_work_date' => "2009-11-30",
 +
        'work_half_yn' => "Y",
 +
        'disability' => "dizziness",
 +
        'talk_to_lawyer_yn' => "Y",
 +
        'doc_yn' => "Y",
 +
        'have_lawyer_yn' => "N",
 +
        'is_test_lead' => "1",
 +
);
 +
 +
$baseurl = "https://www.us-social-security-disability.com/admin/sendlead.php";
 +
$userAgent = 'Mozilla/5.0 (compatible; MSIE 9.0; Windows NT 6.1; Trident/5.0)';
 +
$timeout = 10;
 +
 +
$ch = curl_init();
 +
 +
curl_setopt($ch, CURLOPT_POST, true);
 +
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
 +
curl_setopt($ch, CURLOPT_VERBOSE, false);
 +
curl_setopt($ch, CURLOPT_HEADER, true);
 +
curl_setopt($ch, CURLINFO_HEADER_OUT, true);
 +
curl_setopt($ch, CURLOPT_USERAGENT, $userAgent);
 +
curl_setopt($ch, CURLOPT_CONNECTTIMEOUT, $timeout);
 +
curl_setopt($ch, CURLOPT_URL, $baseurl);
 +
curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
 +
 +
 +
$content = curl_exec($ch);
 +
curl_close($ch);
 +
 +
if (!$content) {
 +
  echo "ERROR: No data received.\n";
 +
  exit();
 +
}
 +
 +
echo "$content\n";
 +
 +
?>
 +
 +
</pre>
 +
 +
A successful result should look like this:
 +
 +
<pre>
 +
HTTP/1.1 200 OK
 +
Date: Mon, 26 Aug 2013 19:38:59 GMT
 +
Server: Apache
 +
Vary: Accept-Encoding
 +
Content-Length: 32
 +
Content-Type: text/html
 +
 +
RESULT=SUCCESS&RESULT_DETAIL=919
 +
</pre>

Latest revision as of 11:37, 28 February 2014

Overview

This is a work in progress. This document describes how to submit leads directly to Netsville via an HTTP POST Request. Requests are submitted to a CGI script with Key-Value Pairs in the BODY of the request.

Request Requirements

  • POST (only)

Only standard POST requests are allowed. Either Content-type of multipart/form-data or application/x-www-form-urlencoded.

Each key-value pair is separated by an '&' character, and each key is separated from its value by an '=' character. Keys and values are both escaped by replacing spaces with the '+' character and then using URL encoding on all other non-alphanumeric characters.

URI

Here is the main URI: 

https://www.us-social-security-disability.com/admin/sendlead.php

Sample Request Body (detail with headers)

Again, note that all requests to the https://www.us-social-security-disability.com/admin/sendlead.php URL must be a valid POST request. See below for a coding example in PHP. 

POST /admin/sendlead.php HTTP/1.1
User-Agent: Mozilla/5.0 (compatible; MSIE 9.0; Windows NT 6.1; Trident/5.0)
Host: www.us-social-security-disability.com
Accept: */*
Content-Length: 394
Content-Type: application/x-www-form-urlencoded

affiliate_id=123123&name_last=Smith&name_first=John&dob=1985-01-10&email=jsmith@example.com&phone_home=5852325670
&addr_street=69 Cascade Dr&addr_city=Rochester&addr_state=NY&addr_zip=14614&applied_yn=Y&applied_result=denied
&applied_denial_date=2010-12-31&out_of_work_yn=Y&stop_work_date=2009-11-30&work_half_yn=Y&disability=dizziness
&talk_to_lawyer_yn=Y&doc_yn=Y&have_lawyer_yn=N

Description of Form Fields

Required fields are in bold.

Field Description Type Required Example
affiliate_id Unique identifier given to you by Netsville. A 6-digit number. Numeric Yes 123123
name_last Last Name of Person Alpha Yes Smith
name_first First Name of Person Alpha Yes John
dob Date of Birth in YYYY-MM-DD format Date Yes 1985-01-15
email Email address Email Yes jsmith@example.com
phone_home 10 digit home phone number in NNNXXXYYYY format (numbers only) Numeric Yes 5855551212
addr_street Street address Alphanumeric Yes 123 Main Street
addr_city City Alpha Yes Rochester
addr_state State (two letter abbreviation) Alpha Yes NY
addr_zip Zip code (5 numbers) Numeric Yes 14614
disability What is the condition that prevents you from working? Alpha Yes A-Fib, heart condition, dizziness
out_of_work_yn Do you expect to be out of work for the next 12 months?
Either Yes(Y) or No(N)		 Alpha Yes Y
stop_work_date The date that you stopped working in YYYY-MM-DD format Date Yes 2009-11-30
applied_yn Have you applied for Social Security Disability?
Either Yes(Y) or No(N)		 Alpha Yes Y
applied_result What was the result of your application? The possible choices are: Claim Pending, Receiving Benefits, Claim Denied.
The answer must contain one of these words: 'pending', 'benefits', or 'denied'		 Alpha Yes denied
applied_denial_date If the above answer contains 'denied', then this field must contain the date of that denial in the format: YYYY-MM-DD. Otherwise, this field can be empty. Date No 2010-12-31
work_half_yn Have you worked 5 out of the last 10 years? This field can be empty. Alpha No N
talk_to_lawyer_yn Would you like a free consultation (speak to a laywer)? If this is blank, YES(Y) is assumed. Alpha No Y
doc_yn In the past 6 months, have you seen a doctor?
Either Yes(Y) or No(N). This field can be empty.		 Alpha No N
have_lawyer_yn Do you currently have an attorney helping you?
Either Yes(Y) or No(N). This field can be empty.		 Alpha No N
is_test_lead A trigger to mark lead as only a test in the database. Use '1' for Yes and '0' for No. This field can be empty. Numeric No 0

Return Values

The result will be of Content-type: text/html and a single line. For example:

A Successful Result

RESULT=SUCCESS&RESULT_DETAIL=906 
The RESULT_DETAIL is the id of the lead added to the database if successful.

An Unsuccessful Result

RESULT=ERROR&RESULT_DETAIL=<a list of Missing Fields> 
This will be the most common. If we need to tweak the required fields, we will.

Other Errors

RESULT=ERROR&RESULT_DETAIL=Could not find your affiliate id. Please contact Netsville. 
Unable to find your affiliate id in our database. Email support@netsville.com to verify your affiliate number.
RESULT=ERROR&RESULT_DETAIL=Invalid home phone number. Must be numeric and 10 digits. 
Non-numerics will be stripped out, but if the number is the wrong length, this error will be displayed.
RESULT=ERROR&RESULT_DETAIL=Invalid zip code. 
Non-numerics will be stripped out. Currently only US zip codes are supported.
RESULT=ERROR&RESULT_DETAIL=Unable to read date. 
If the Date of Birth (dob) or Date of Denial (applied_denial_date) is invalid, this error will show up. See above in Description of Form Fields for the valid format.

Sample PHP FORM SUBMIT script

<?php

//
// sendlead tester script - a barebones FORM ACTION script in PHP
//

$data = array(
        'affiliate_id' => "123123",
        'name_last' => "Smith",
        'name_first' => "John",
        'dob' => "1985-01-10",
        'email' => "jsmith@example.com",
        'phone_home' => "5852325670",
        'addr_street' => "69 Cascade Dr",
        'addr_city' => "Rochester",
        'addr_state' => "NY",
        'addr_zip' => "14614",
        'applied_yn' => "Y",
        'applied_result' => "denied",
        'applied_denial_date' => "2010-12-31",
        'out_of_work_yn' => "Y",
        'stop_work_date' => "2009-11-30",
        'work_half_yn' => "Y",
        'disability' => "dizziness",
        'talk_to_lawyer_yn' => "Y",
        'doc_yn' => "Y",
        'have_lawyer_yn' => "N",
        'is_test_lead' => "1",
);

$baseurl = "https://www.us-social-security-disability.com/admin/sendlead.php";
$userAgent = 'Mozilla/5.0 (compatible; MSIE 9.0; Windows NT 6.1; Trident/5.0)';
$timeout = 10;

$ch = curl_init();

curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_VERBOSE, false);
curl_setopt($ch, CURLOPT_HEADER, true);
curl_setopt($ch, CURLINFO_HEADER_OUT, true);
curl_setopt($ch, CURLOPT_USERAGENT, $userAgent);
curl_setopt($ch, CURLOPT_CONNECTTIMEOUT, $timeout);
curl_setopt($ch, CURLOPT_URL, $baseurl);
curl_setopt($ch, CURLOPT_POSTFIELDS, $data);


$content = curl_exec($ch);
curl_close($ch);

if (!$content) {
  echo "ERROR: No data received.\n";
  exit();
}

echo "$content\n";

?>

A successful result should look like this: 

HTTP/1.1 200 OK
Date: Mon, 26 Aug 2013 19:38:59 GMT
Server: Apache
Vary: Accept-Encoding
Content-Length: 32
Content-Type: text/html

RESULT=SUCCESS&RESULT_DETAIL=919
Retrieved from "https://support.netsville.com/index.php?title=Send_Lead_API&oldid=391"