LIPNET OUTBOUND API FORMS DOCUMENTATION

Size: px

Start display at page:

Download "LIPNET OUTBOUND API FORMS DOCUMENTATION"

Violet Regina Watts
5 years ago
Views:

1 LIPNET OUTBOUND API FORMS DOCUMENTATION LEGAL INAKE PROFESSIONALS

2 Contents Description... 2 Requirements:... 2 General Information:... 2 Request/Response Information:... 2 Service Endpoints... 2 Outbound Endpoint... 2 Description... 2 Endpoint URIs... 2 Form Request Format... 2 JSON Response Format... 3 Code Examples... 4 PHP... 4 PHP HTML Form Page Example:... 4 PHP Stream Submission Example:... 4 PHP CURL Submission Example:... 5 ASP.NET... 5 ASP.NET HTML Form Page Example:... 5 ASP.NET C# Code Example:... 6

3 LIPNET Outbound API Forms Documentation Description Requirements: IMPORTANT: As of February 8 th 2018, communication with the LIPNET Outbound API is secured using the Transport Layer Security (TLS) version 1.2. As a result, updates to software frameworks on partners integrations may be necessary. Every development project is different and can have many parts, so a comprehensive how to for enabling TLS 1.2 is challenging. If you are receiving communication errors when integrating with the API, please contact LIP Client Services for assistance. General Information: The LIPNET Forms API is a Representational State Transfer (REST) service which uses URL encoding as the primary means of communication between computer systems Request/Response Information: The Form system receives data using a URL encoded string. Standard HTTP response codes are provided by all endpoints. Requesting application can use the HTTP response code to determine if the request was successful or if an error occurred during processing. Service Endpoints Outbound Endpoint Description Receives client lead information for call backs (outbounds) to be completed by Legal Intake Professionals (LIP). Endpoint URIs To fully integrate a web site with the live API, please use the following endpoint: - Production URI: Form Request Format The following fields are available to requesting application: - APIKey: A numeric value that indicates what client account the request is related to o A value for this field is required o Value must be a valid account id

4 - FirstName: The first name of the lead to contact o A value for this field is required - LastName: The last name of the lead to contact - (string): address of the lead to contact - PhoneNumber (string): The phone number of lead to contact that will be dialed by LIP o A value for this field is required o Value must meet the following conditions All non-numeric characters will be removed by the API All leading zero (0) and one (1) characters will be removed by the API The resulting values must be ten (10) digits in length - Comments (string): Any additional information the requestor would like to provide - SubmitterId (string): A value that represents the lead contact record of the requesting system - FormHash (string): A hashed value created using form values o A value for this field is required - MediaSourceId (string): A value that represents where the lead came from. An example would be an identifier for a web site form. JSON Response Format Depending on the result of the HTTP request, one of following will be supplied for each request sent to the outbound endpoint Successful Request HTTP Response Code: 200 Response Message: Outbound submitted successfully Unsuccessful Request Issue: Missing API Key - HTTP Response Code: 400 (Bad Request) - Message: Invalid request. Issue: Invalid API Key - HTTP Response Code: 401 (Unauthorized) - Message: Unauthorized User. Issue: Missing First Name - HTTP Response Code: 500 (Internal Server Error) - Message: Validation failed for one or more entities. See 'EntityValidationErrors' property for more details Issue: Invalid Phone Number

5 - HTTP Response Code: 406 (Bad Request) - Message: Request not accepted Issue: Missing Form Hash - HTTP Response Code: 400 (Bad Request) - Message: Invalid request Code Examples PHP Use the following examples as a reference when integrating a web site coded using PHP. PHP HTML Form Page Example: <! - Filename: index.php --> <! - Description: html form presented to user to fill out --> <html> <body> <form method= post action=./process.php > <input type= hidden name= apikey value= 1234 /> First Name: <input type= text name= firstname /><br /> Last Name: <input type= text name= lastname /><br /> Address: <input type= text name= address /><br /> Phone Number: <input type= text name= phonenumber /><br /> Comments: <input type= textarea rows= 3 name= comments /><br /> <input type= submit value= Submit Form /> </form> </body> </html> PHP Stream Submission Example: <! - Filename: process.php --> <! - Description: code that submits form data to API using a data stream --> <?php $apiurl = $submitvalues = array( "ApiKey" => $_POST[ apikey ], "FirstName" => $_POST[ firstname ], "LastName" => $_POST[ lastname ], " " => $_POST[ address ], "PhoneNumber" => $_POST[ phonenumber ], "Comments" => $_POST[ comments ], "Encryption" => "SHA" ); $encryptstr = xxxmyprivateapikey== ; //value provided by LIP foreach($submitvalues as $key => $value) $encryptstr.= $key.$value; $encryptstr = base64_encode(sha1($encryptstr, true)); $submitvalues[ FormHash ] = $encryptstr; $postoptions = array('http' => array( 'method' => 'POST', 'content' => http_build_query($values) )); $context = stream_context_create($postoptions); $fopen 'rb', false, $context); $response print_r($response);

6 if (!$response) print("error occurred"); //do error handling here else print($response);?> PHP CURL Submission Example: <! - Filename: process.php --> <! - Description: code that submits form data to API using CURL --> <?php $apiurl = $submitvalues = array( "ApiKey" => $_POST[ apikey ], "FirstName" => $_POST[ firstname ], "LastName" => $_POST[ lastname ], " " => $_POST[ address ], "PhoneNumber" => $_POST[ phonenumber ], "Comments" => $_POST[ comments ], "Encryption" => "SHA" ); $encryptstr = xxxmyprivateapikey== ; //value provided by LIP foreach($submitvalues as $key => $value) $encryptstr.= $key.$value; $encryptstr = base64_encode(sha1($encryptstr, true)); $submitvalues[ FormHash ] = $encryptstr; $ch = curl_init(); curl_setopt($ch, CURLOPT_URL, $apiurl); curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1); curl_setopt($ch, CURLOPT_POST, true); curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($submitvalues)); $response = curl_exec($ch); $responseinfo = curl_getinfo($ch); curl_close($ch); if ($responseinfo['http_code']!= 200) // Handle API error?> ASP.NET Use the following examples as a reference when integrating a web site coded using ASP.Net. ASP.NET HTML Form Page Example: <! - Filename: index.aspx --> <! - Description: form presented to user to fill out --> <%@ Page Language="C#" CodeFile="Index.aspx.cs" Inherits="Index" %> <!DOCTYPE html> <html lang="en"> <head> <meta charset="utf-8" /> <title></title> </head> <body> <form id="form1" runat="server"> <div> <asp:hiddenfield id="hidapikey" runat="server" Value="525" />

7 First Name: <asp:textbox id="txtfirstname" runat="server" /><br /> Last Name: <asp:textbox id="txtlastname" runat="server" /><br /> Address: <asp:textbox id="txt address" runat="server" /><br /> Phone Number: <asp:textbox id="txtphonenumber" runat="server" /><br /> Comments:<asp:TextBox id="txtcomments" runat="server" TextMode="MultiLine" Rows="3" /><br /> <asp:button id="btnsubmit" runat="server" Text="Submit Form" OnClick="btnSubmit_Click" /><br /> <asp:label ID="lblResult" runat="server" /> </div> </form> </body> </html> ASP.NET C# Code Example: <! - Filename: index.aspx.cs --> <! - Description: index.aspx code behind file --> using System; using System.Collections.Generic; using System.Collections.Specialized; using System.Net; using System.Security.Cryptography; using System.Text; using System.Web; public partial class Index : System.Web.UI.Page protected void btnsubmit_click(object sender, EventArgs e) var apiurl = " var values = new NameValueCollection() "ApiKey", this.hidapikey.value, "FirstName", this.txtfirstname.text, "LastName", this.txtlastname.text, " ", this.txt address.text, "PhoneNumber", this.txtphonenumber.text, "Comments", this.txtcomments.text, "Encryption", "SHA" ; var sb = new StringBuilder(); sb.append("xxxmyprivateapikey=="); //Provided by LIP foreach (var item in values.allkeys) sb.append(item + "" + values[item]); var encryptedstring = Convert.ToBase64String(new SHA1CryptoServiceProvider().ComputeHash(Encoding.ASCII.GetBytes(sb.ToString()))); values.add("formhash", encryptedstring); using (WebClient client = new WebClient()) var sresponse = String.Empty; try byte[] response = client.uploadvalues(apiurl, values); sresponse = ASCIIEncoding.ASCII.GetString(response); catch(exception ex) sresponse = ex.message; this.lblresult.text = sresponse;

API USER GUIDE MARKETING MESSAGES & BROADCASTS

API USER GUIDE MARKETING MESSAGES & BROADCASTS General Overview So, what do you want to do? 3 3 Marketing Messages with replies 4 First, let s send the messages Advanced API developers note Next, let s