Lead API
Important Note : Coding the submission of enquiries from your web site to be sent to AdminBase should be undertaken by your web site developers. It is NOT the responsibility of AdminBase to do this for you. We do not recommend you attempt to make these changes yourself unless you are familiar with web development and calling API’s. We will answer questions and offer guidance to assist your web site developers where we can.
To make Lead data collected on your website available for import into AdminBase you will need to POST your Lead data to the following API endpoint:-
https://webleads.abinitiosoftware.co.uk/api/LeadDetails
This can be accomplished by:
Posting directly from the input form on your web page.
Posting from a database on your website where the input form data has been stored.
Checkatrade
It is also possible to setup a webhook at Checkatrade to forward leads captured there straight into AdminBase.
The API endpoint for this is:-
https://webleads.abinitiosoftware.co.uk/api/CTLeadDetails/AB_CUSTID/AB_PWORD
Where AB_CUSTID and AB_PWORD are your unique values given to you by us.
Posting directly from the input form on your web page
The simplest way is to name your in fields so that they match the parameters required by us to get lead data into AdminBase. See the appendix for the naming of these parameters. Note that not all of these are required, only the mandatory ones. Other than this you can use as many or as few of the fields that you desire.
<form id="form1" method="post" action="https://webleads.abinitiosoftware.co.uk/api/LeadDetails" enctype="application/x-www-form-urlencoded"> <input type="hidden" value="value1" name="AB_CUSTID" /> //mandatory <input type="hidden" value="value2" name="AB_PWORD" /> //mandatory <input type="hidden" value="https://www.abinitiosoftware.co.uk" name="URLRedirect" /> //optional <input type="hidden" value="1" name="TEST" /> //optional <input type="text" name="FIRSTSURNAME" /> <input type="text" name="EMAIL" /> <input type="submit" /> </form>
The mandatory parameters (AB_CUSTID and AB_PWORD) will not be visible to the user if implemented via hidden fields in your form.
Note that values 1-5 should be provided by you as follows:
value1 : Type the Ab Initio Customer ID you use to log in to the support website. See Options for this if you do not have it.
value2 : Type your Ab Initio Web Leads Password (as supplied by Ab Initio)
value3 : Optional) Type the full URL of the web page you wish the user to be directed to after posting. (This would not be required if posting from a database rather than a form)
value4 : (Optional) This is the test mode. 0 for live, 1 for testing. Form data will not be processed and made ready for import.
Posting from a database on your website where the input form data has been stored
If your Lead data is stored in a database on the web, you can iterate through the records you wish to send to AdminBase, replacing the values in red below with the corresponding field from your database.
NB. You do not have to post all of the parameters displayed here, just the ones marked as ‘Required’ (See appendix).
Posting using ASP
The following example is written in asp…
<% test = 0 //1 = test mode, 0 = live ab_custid = yourCustomerID pword = "yourpassword" firstsurname = "value read from your data" firsttitle = "value read from your data" houseno = "value read from your data" street = "value read from your data" town = "value read from your data" pcode = "value read from your data" leaddate = "" //blank will use current date, else if leaddate entered, must be in "DD/MM/YYYY" format DestURL = "http://webleads.abinitiosoftware.co.uk/api/LeadDetails" Set xmlhttp = Server.CreateObject("msxml2.ServerXMLHTTP") xmlhttp.Open "POST", DestURL xmlhttp.setRequestHeader "Content-Type", "application/x-www-form-urlencoded" postdata = "TEST=" & test & "&AB_CUSTID=" & ab_custid & "&AB_PWORD=" & pword & "&FIRSTSURNAME=" & firstsurname & "&FIRSTTITLE=" & firsttitle & "&HOUSENO=" & houseno & "&STREET=" & street & "&TOWN=" & town & "&PCODE=" & pcode & "&LEADDATE=" & leaddate xmlhttp.Send postdata Response.Write xmlhttp.ResponseText %>
Posting using PHP
The following example is written in php…
$url = 'https://webleads.abinitiosoftware.co.uk/api/LeadDetails'; $houseno = value from your data; $firstsurname = value from your data; $pcode = value from your data; $custID = your Customer ID; $pw = your password; $data = array('AB_CUSTID' => $custID, 'AB_PWORD' => $pw, 'FIRSTSURNAME' => $firstsurname, 'HOUSENO' => $houseno, 'PCODE' => $pcode); // use key 'http' even if you send the request to https://... $options = array( 'http' => array( 'header' => "Content-type: application/x-www-form-urlencoded\r\n", 'method' => 'POST', 'content' => http_build_query($data) ) ); $context = stream_context_create($options); $result = file_get_contents($url, false, $context); if ($result === FALSE) { /* Handle error */ } //var_dump($result);
Posting using Contact Form 7 - Plugin
Contact Form 7 is a popular Wordpress plugin for form creation and management. To configure Contact Form 7 to POST data to the Web Leads API first install the Contact Form 7 To Any API plugin.
Within your Contact Form
Use EXACT NAME for fields in the contact form as per the Appendix - i.e. FIRSTNAME, EMAIL, HOMETEL as this is what is outputted in the JSON.
CF7 to Any API
API URL - https://webleads.abinitiosoftware.co.uk/api/LeadDetails
Use Content-Type: application/json as the Header Request - strip everything else out.
Set Json input type and POST method
Complete the map of your Fields sections in the plugin and save.
NOT PREFERED - Use [hidden AB_CUSTID "userid"] and [hidden AB_PWORD "password"] using your provided credentials in each contact form if you unable to add these fields into the plugin configuration.
API Integration Setting | Value |
---|---|
Base URL | |
Input Type | JSON |
Method | POST |
Posting using Contact Form 7 - [Historical]
Please hook into the before email send event of Contact Form 7 to fire this code which will forward the data to us. You can modify your functions.php or use a plugin such as Code Snippets. PLEASE NOTE you will have to amend the Title and Field names along with the AB_CUSTID and AB_PWORD in the code to match your form and the credentials you have been supplied.
/** * POST Call to AdminBase API from CF7 Submit */ add_action( 'wpcf7_before_send_mail', 'wpcf7_api_function' ); function wpcf7_api_function( $contact_form ) { $title = $contact_form->title; $submission = WPCF7_Submission::get_instance(); if ( $submission ) { $posted_data = $submission->get_posted_data(); } if ( 'Contact Form' == $title ) {//The title will be form specific!! $name = strtolower($posted_data['your-name']);//YOUR-NAME will be form specific!! $email = strtolower($posted_data['your-email']);//YOUR-EMAIL will be form specific!! $phone = strtolower($posted_data['your-telephone']);//YOUR-TELEPHONE will be form specific!! $notes = strtolower($posted_data['your-message']);//YOUR-MESSAGE will be form specific!! $leadsource = "WEB"; $ab_custid = "CUSTOMER SPECIFIC";//AB_CUSTID will be customer specific!! $ab_pword = "CUSTOMER SPECIFIC";//AB_PWORD will be customer specific!! $url = 'https://webleads.abinitiosoftware.co.uk/api/LeadDetails'; $data = array( 'AB_CUSTID' => $ab_custid, 'AB_PWORD' => $ab_pword, 'FIRSTSURNAME' => $name, 'EMAIL' => $email, 'HOMETEL' => $phone, 'NOTES' => $notes, 'LEADSOURCE' => $leadsource, ); // use key 'http' even if you send the request to https://... $options = array( 'http' => array( 'header' => "Content-type: application/x-www-form-urlencoded\r\n", 'method' => 'POST', 'content' => http_build_query($data) ) ); $context = stream_context_create($options); $result = file_get_contents($url, false, $context); if ($result === FALSE) { /* Handle error */ } } }
Posting using Contact Form 7 - [Historical]
Contact Form 7 is a popular Wordpress plugin for form creation and management. To configure Contact Form 7 to POST data to the Web Leads API first install the Contact Form 7 To API plugin.
This will add in an API Integration tab to your form configuration. Within this tab specify the following details:
API Integration Setting | Value |
---|---|
Send to api? | Tick |
Base URL | |
Input Type | JSON |
Method | POST |
JSON Template | This will be dependant on your form. You will see the available items to send above the text box. In the below example you will see how to setup a small form. Use the parameter name from the Appendix and the corresponding item name in your form to build the string that will be sent. Values need to be encapsulated in quotation marks (“). If you have checkboxes you can put them all inside one parameter, i.e. PRODINTEREST1 below |
Posting using Wix
Wix is a simple use use website generation tool. It allows you to build contact forms within its interface. To get them to POST to the Web Leads API go to the form you wish to send in edit mode and after clicking Form Settings then choose Automations.
For the Trigger specify which form you want to apply the automation to.
For the Action specify Connect to Webhook and provide the Target URL as https://webleads.abinitiosoftware.co.uk/api/LeadDetails
Then choose to Customize the structure of the payload. Add as many Key-Value pairs as you need, be sure to add in the AB_CUSTID and AB_PWORD here. Then choose Insert variable and select the variable from your form you wish to post, then using the Appendix find the parameter name to use in the Key column.
Finally you may want to limit the number of times someone can submit their details, if so under Timing change Limit Frequency to Once per contact every 24hrs
Files
Files can be attached to a submitted lead. To do so the Lead is submitted in the usual fashion but with the added parameter TOKENREQ set to 1. This returns json like the following:
{ "token": "8548d5e0-9d47-4d08-b9ec-2e0d8689c712" }
This token value uniquely identifies the just submitted lead and can be used in a subsequent call to add a file to the lead.
You will need to send the following multipart form data to https://webleads.abinitiosoftware.co.uk/api/Upload
API Parameter | Value |
---|---|
Filename | The files name. i.e.. File.pdf |
Description | The files description, this will show in AdminBase |
Token | The token returned from the main submission call |
File | The file data |
It is possible to add multiple files by sending multiple requests to this endpoint.
Here is a simplified example of how to do this in JavaScript:
var handleSubmit = (event) => { //event.preventDefault(); const form = document.getElementById("form"); const inputFile = document.getElementById("file"); const inputNote = document.getElementById("note"); var formData = new FormData(); //set values of formdata - these are the fields of the form i.e. formData.append("NOTES", inputNote.value); // ... formData.append("TOKENREQ", 1); formData.append("AB_CUSTID", "Your credentials"); formData.append("AB_PWORD", "Your credentials"); //send form data fetch("https://webleads.abinitiosoftware.co.uk/api/LeadDetails", { method: "post", body: formData, }).then((data) => { //if successful send file(s) for (const file of inputFile.files) { formData = new FormData(); formData.append("file", file); formData.append("token", data.token); formData.append("description", file.name); formData.append("filename", file.name); fetch("https://webleads.abinitiosoftware.co.uk/api/Upload", { method: "post", body: formData, }).catch((error) => ("Something went wrong!", error)); } }).catch((error) => ("Something went wrong!", error)); };
Where the html may look like:
<form id="form"> <input type="text" id="note" /> ... <input type="file" id="file" multiple /> <button onclick="handleSubmit()">Submit</button> </form>
This is just an example, you are free to use any language you like to send the data across.
Return Status Codes
The status codes returned from the API are the standard HTTP status codes. For example:-
Status code | Meaning |
---|---|
200 | Success |
400 | Bad Request |
500 | Error |
Appendix
The following name-value pairs can be posted to the above API End Point…
Parameter Name | Parameter Value | Info | Required? |
---|---|---|---|
AB_CUSTID | integer | Customer ID as supplied by Ab Initio | Yes |
AB_PWORD | Text(20) | Ab Initio Support Web-Site (Web Leads) Password | Yes |
FIRSTSURNAME | Text(25) | First Surname | |
FIRSTTITLE | Text(15) | First Title | |
SECONDSURNAME | Text(25) | Second Surname | |
SECONDTITLE | Text(15) | Second Title | |
HOUSENO | Text(30) | House Number | |
HOUSENAME | Text(30) | House Name | |
STREET | Text(50) | Street | |
AREA | Text(30) | Area | |
TOWN | Text(30) | Town | |
COUNTY | Text(30) | County | |
PCODE | Text(9) | Postcode | |
HOMETEL | Text(25) | Home Telephone No. | |
WORKTEL | Text(50) | Work Telephone No. | |
LEADDATE | Text(10) | Lead Date (NB. must be in the format DD/MM/YYYY) If left blank then current date and time will be used | |
LEADSOURCE | Text(50) | Lead Source | |
SALESAREA | Text(50) | Sales Area | |
SALESPERSON | Text(50) | Salesperson | |
PRODINTEREST1 | Text(50) | Product Interest 1 | |
PRODINTEREST2 | Text(50) | Product Interest 2 | |
PRODTYPE | Text(50) | Product Type | |
MOBTEL | Text(15) | Mobile Telephone No. | |
FAX | Text(15) | Fax No. | |
FIRSTINITIAL | Text(25) | First Initial | |
SECONDINITIAL | Text(25) | Second Initial | |
OFFICEREF | Text(50) | Office Ref | |
COMPANYNAME | Text(50) | Company Name | |
CONTACTNAME | Text(50) | Contact Name | |
BUSADDRESS | Text(5) | Business Address? (NB. must be in the format 'True' or 'False') | |
TAKENBY | Text(50) | Taken By | |
QUOTETYPE | Text(50) | Quote Type | |
Text(50) | E-mail Address | ||
NOTES | Text(2000) | Notes 'Catch all' for information that has no direct matching field in AdminBase. Anything in here will get posted to the AdminBase – Leads – Notes section. | |
URLRedirect | Text | Full URL of web page that user should be directed to after submitting their details. (Recommended if posting from a form rather than a database) | |
TEST | 1 or 0 (or blank) | This is the test mode. If TEST=1 then the API will return a list of the data values correctly submitted to us along with any error messages (missing mandatory fields, invalid password etc.) Form data will not be processed and made ready for import. | |
GDPROPTINDATE | Text(10) | Marketing Opt in Date. (NB. If entered then must be in the format DD/MM/YYYY) A date in this field indicates a ‘hard opt in’. | |
GDPROPTINMETHOD | Text(30) | Marketing Opt in Method. For web leads you would specify Website here. If needed you can specify different websites. There must be a corresponding entry in your AdminBase Lists -> Drop Down Lists -> Marketing Opt In Methods | |
GDPROPTINDOC | Text(255) | Marketing Opt in Document. In AdminBase this is a link to a file which proves the Opt in. If you use a file you would need to handle the copying of the file to the appropriate location yourself. Optionally your website could create a unique identifier that is stored in this field. | |
GDPROPTINPHONE | Text(5) | (NB. must be in the format 'True' or 'False') Alternatively, 1 or 0 can be passed | |
GDPROPTINLETTER | Text(5) | (NB. must be in the format 'True' or 'False') Alternatively, 1 or 0 can be passed | |
GDPROPTINEMAIL | Text(5) | (NB. must be in the format 'True' or 'False') Alternatively, 1 or 0 can be passed | |
GDPROPTINSMS | Text(5) | (NB. must be in the format 'True' or 'False') Alternatively, 1 or 0 can be passed | |
SUBSOURCE | Text(50) | Sub Source | |
SUBSUBSOURCE | Text(50) | Sub Sub Source | |
APPOINTMENTDATE | Text(16) | Appointment Date & Time (NB. must be in the format DD/MM/YYYY HH:mm) | |
APPOINTMENTDURATION | Decimal | Used to specify the length of appointment in Hrs | |
OPPORTUNITYID | Text(100) | Used to track the opportunity | |
CONTACTID | Text(100) | Used to track the contact | |
DIGITALSOURCE | Text(100) | Used to track the digital source | |
DIGITALSUBSOURCE | Text(100) | Used to track the digital sub source | |
DIGITALSUBSUBSOURCE | Text(100) | Used to track the digital sub sub source | |
NOOFFRAMES | Integer | The number of frames for this lead | |
TOKENREQ | 1 or 0 (or blank) | Used to request a token than can be used for files | |
CONFEMAIL | Text(200) | A single email address to which the payload of the submission will be forwarded | |
CUSTCATEG | Text(50) | A custom category field for your own use |