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:

  1. Posting directly from the input form on your web page.

  2. 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

  1. 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

  1. API URL - https://webleads.abinitiosoftware.co.uk/api/LeadDetails

  2. Use Content-Type: application/json as the Header Request - strip everything else out. 

  3. Set Json input type and POST method

  4. Complete the map of your Fields sections in the plugin and save.

  5. 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

https://webleads.abinitiosoftware.co.uk/api/LeadDetails

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

https://webleads.abinitiosoftware.co.uk/api/LeadDetails

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

EMAIL

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