Lead Create/Update API Documentation : FLG Support Portal

Lead Create & Update API Guide • Version 3.00 • Prepared by Mike Emery • 24 February 2020

Leads can be posted into the system or updated through an HTTP post of XML data to a specific URL. Up to 100 requests can be submitted at once.

1. Introduction

1.1 XML Format

The expectation is for data to be wrapped in two hierarchical elements, Data and Lead. To submit multiple leads, repeat the last element (in this case Lead). XML data is therefore expected in the format:

<DATA>
  <LEAD>
    ...
  </LEAD>
</DATA>

Note

A common mistake when working with XML data is not encoding certain characters such as &, < and > into their XML character entities. For example, within data being sent, the & sign should be converted to the &amp; character entity.

Search the internet for ‘XML Character Entities’ for more details.

1.2 Posting URL

The posting URL can be generated through the ‘Tools > Capture Leads’ page. If the service is accessed at the address domain.example.com, the posting URL would be:

https://domain.example.com/api/APILeadCreateUpdate.php

1.3 Testing

As with all lead submission methods, submitting a lead with first name flg and last name test will validate the request without entering a lead into the database, returning a lead ID of 000000 if successful.

1.4 Creating Leads

To create leads, an access key may be required. This depends on the lead group settings.

If the lead group allows leads to be captured through an iFrame and web form, no access key is required. This is set for each lead group in ‘Settings > Lead groups > Edit Group’, under ‘General Settings > General Preferences’. The setting is called ‘Allow capture leads through iFrame and web form’.
If the lead group does not allow leads to be captured through an iFrame and web form, an access key is required. Provide the key in a key element. Access keys can be created in ‘Settings > Access Keys’.

To create a new lead, make a request without an id element. The absence of this element tells the service that the request is to create a new lead.

Example create request (with access key)

<?xml version="1.0" encoding="ISO-8859-1"?>
<data>
  <lead>
    <key>Yrg32FoiRdSriLYEbLrzSvFmurBGsPiz</key>
    <leadgroup>10</leadgroup>
    <site>20</site>
    <introducer>30</introducer>
    <reference>Lead123</reference>
    <source>Google</source>
    <medium>PPC</medium>
    <term>Loans</term>
    <cost>10.00</cost>
    <value>100.00</value>
    <title>Mr</title>
    <firstname>John</firstname>
    <lastname>Smith</lastname>
    <company>ABC Ltd.</company>
    <jobtitle>Manager</jobtitle>
    <phone1>0161 123 1234</phone1>
    <phone2>07912 123 456</phone2>
    <fax>0161 123 1235</fax>
    <email>john@abc.com</email>
    <address>1 High Street</address>
    <address2>This Village</address2>
    <towncity>This Town</towncity>
    <postcode>BB12 6EG</postcode>
    <dobday>01</dobday>
    <dobmonth>01</dobmonth>
    <dobyear>1990</dobyear>
    <contacttime>Anytime</contacttime>
    <data1>Ford</data1>
    <data2>Mondeo</data2>
    <data3>2005</data3>
    <data4>4000</data4>
  </lead>
</data>

If no access key is required, make a request without a key element.

1.5 Updating Leads

To update leads, an access key is required. Provide the key in a key element. Access keys can be created in ‘Settings > Access Keys’.

Most of the same values that can be sent in a create lead request can be used to update leads. Those fields marked with note ³ in section 2.1 cannot.

Example update request

<?xml version="1.0" encoding="ISO-8859-1"?>
<data>
  <lead>
    <key>Yrg32FoiRdSriLYEbLrzSvFmurBGsPiz</key>
    <id>1001150</id>
    <data1>Ford</data1>
    <data2>Mondeo</data2>
    <data3>2005</data3>
    <data4>4000</data4>
  </lead>
</data>

2. Post Format

2.1 Post Data Elements

Field	Type	Required¹ Create	Required¹ Update	Sample	Notes
Key	String	Yes	Yes	Yrg32FoiRdS…	Obtained from ‘Access Keys’
Id	Integer	–	Yes	1001150	The lead ID to be updated
Leadgroup³	Integer	Yes	–	10	Provided by ‘Capture Leads’
Site³	Integer	–	–	20	Provided by ‘Capture Leads’
Introducer³	Integer	–	–	30	Provided by ‘Capture Leads’
Buyer⁶	Integer	–	–	40	Preferred referral partner (see note 6)
Type²	String	–	–	Secured Loan	Sets the lead type
User²	String	–	–	Jane Smith	Sets the assigned user
Status²	String	–	–	New	Sets the status
Ipaddress³	String	–	–	192.168.0.1	Overrides detected IP address
Reference	String	–	–	Lead123	Introducer’s lead reference
Source	String	–	–	Google	Marketing source
Medium	String	–	–	PPC	Marketing medium
Term	String	–	–	Loans	Marketing term
Cost	Decimal	–	–	10.00	Cost of lead
Value	Decimal	–	–	100.00	Value of lead
Title	String	User	–	Mr	See Title Values
Firstname	String	Yes	–	John
Lastname	String	Yes	–	Smith
Company	String	User	–	ABC Ltd.
Jobtitle	String	User	–	Manager
Phone1⁴	Number	User	–	0161 123 1234
Phone2⁴	Number	User	–	07912 123 456
Fax⁴	Number	User	–	0161 123 1235
Email	String	User	–	john@abc.com	Must be a valid email address
Address	String	User	–	1 High Street
Address2	String	–	–	This Area
Address3	String	–	–	This Village
Towncity	String	User	–	This Town
Postcode⁵	String	User	–	BB12 6EG
Dob	String	–	–	01/01/1990	Overrides individual DOB fields
Dobday	Number	User	–	01
Dobmonth	Number	User	–	01
Dobyear	Number	User	–	1990
Contacttime	String	User	–	Anytime	See Contact Time Values
Contactphone	String	–	–	Yes	See Contact Permission Values
Contactsms	String	–	–	Yes	See Contact Permission Values
Contactemail	String	–	–	Yes	See Contact Permission Values
Contactmail	String	–	–	Yes	See Contact Permission Values
Contactfax	String	–	–	Yes	See Contact Permission Values
Data1 – Data50	Varies	User	–	Anything	Lead group data field value

Notes

Fields marked User can be set as required within the lead group’s settings, so may be required. Fields marked Yes are always required.
These are optional. If lead type is not specified, the lead type will be determined by lead type filters. If status is not specified, the first status with a ‘New’ conversion point will be set. If user is not specified, the lead will be unassigned.
These fields cannot be submitted in an update request.
Phone number validation level can be set within the lead group’s settings. Either only valid UK formatted phone numbers will be accepted, or any value. If the field is set to accept any input, all non-numeric and whitespace characters will be stripped out.
Postcode validation level can be set within the lead group’s settings. Either only valid UK postcodes will be accepted, or any value.
Specify a single preferred referral partner ID in buyer, or multiple preferred partner IDs in separate numbered fields such as buyer, buyer2, buyer3, … buyer10.
If the lead is to be referred and the specified partner is eligible for the referral, the preferred referral partner will always be chosen. Likewise, if multiple preferred partners are specified, all of the partners will be preferred over others.
The effect is similar to setting the partner’s lead type ‘selection priority’ higher than for other partners. Note that the partner must be eligible for the referral in the first place, otherwise the setting will have no effect.

2.2 Contact Time Values

Value
Anytime
Morning
Afternoon
Evening

2.3 Contact Permission Values

This value indicates whether permission has been obtained to make contact by phone, fax, email or mail.

Value	Description
Unknown	Not known
Yes	Permission obtained
No	Do not contact using this medium

3. Response Format

The server will respond with XML data containing a parent element Result, and within it a single Status element and one or more Item elements.

If the post is successful, a single Item element will enclose the new (or updated) lead ID. If unsuccessful, one or more item elements will contain the error(s) found.

3.1 Response Data Elements

Field	Type	Sample	Notes
Status	Bit	0	Returns 0 on success and 1 if there are errors
Record	Integer	1	The sequential record number (if submitting multiple requests in one post)
Code	Integer	0	Error code (see table below)
Message	String	OK	Response message
Id	Integer	1001150	New/updated lead ID

3.2 Error Codes

Code	Description
0	No errors
1	Validation error
2	Declined as duplicate
3	Declined as no lead type available (usually out of acceptance criteria)
4	XML format error or no XML provided

4. Create Lead Example

4.1 Post Data

<?xml version="1.0" encoding="ISO-8859-1"?>
<data>
  <lead>
    <key>Yrg32FoiRdSriLYEbLrzSvFmurBGsPiz</key>
    <leadgroup>10</leadgroup>
    <site>20</site>
    <introducer>30</introducer>
    <reference>Lead123</reference>
    <source>Google</source>
    <medium>PPC</medium>
    <term>Loans</term>
    <cost>10.00</cost>
    <value>100.00</value>
    <title>Mr</title>
    <firstname>John</firstname>
    <lastname>Smith</lastname>
    <company>ABC Ltd.</company>
    <jobtitle>Manager</jobtitle>
    <phone1>0161 123 1234</phone1>
    <phone2>07912 123 456</phone2>
    <fax>0161 123 1235</fax>
    <email>john@abc.com</email>
    <address>1 High Street</address>
    <address2>This Village</address2>
    <towncity>This Town</towncity>
    <postcode>BB12 6EG</postcode>
    <dobday>01</dobday>
    <dobmonth>01</dobmonth>
    <dobyear>1990</dobyear>
    <contacttime>Anytime</contacttime>
    <data1>Ford</data1>
    <data2>Mondeo</data2>
    <data3>2005</data3>
    <data4>4000</data4>
  </lead>
</data>

4.2 Response Data

<?xml version="1.0" encoding="ISO-8859-1"?>
<result>
  <status>0</status>
  <item>
    <record>1</record>
    <code>0</code>
    <message>OK</message>
    <id>1001150</id>
  </item>
</result>