Search, Read & Delete API Documentation

Modified on Fri, 21 Aug at 12:36 PM

Lead API Guide • Version 1.50 • Prepared by John Jackson • 25 January 2018

Introduction

This API allows the reading or deletion of leads. The request is made by making an HTTP POST of an XML message containing an access key, request type and other elements.

To create or update leads, please see the ‘Lead Create & Update API Guide’ instead.

The Request

To use this API, an access key is required. Provide the key in a key element within the request. Access keys can be created in ‘Settings > Access Keys’.

For each request, a request element must also be given containing either search, read or delete. Details of how to make each request type are given below.

If the main service is accessed at the address domain.example.com, then a POST request should be made to the corresponding API URL:

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

An XML message should be sent as the POST data:

<?xml version="1.0" encoding="ISO-8859-1"?>
<data>
  <key>Yrg32FoiRdSriLYEbLrzSvFmurBGsPiz</key>
  <request>create</request>
  ...
</data>

The Response

The server will respond with XML data. The response will always contain Code (error code) and Message (response message) elements. If there are several messages, there may be multiple Message elements. If successful, other response elements will also be returned.

A successful response may look like this:

<?xml version="1.0" encoding="ISO-8859-1"?>
<result>
  <code>0</code>
  <message>OK</message>
  ...
</result>

Search

<request>search</request>

Parameters

Parameter Required Description

startdate Required The start date for the search period. e.g. 01/01/2014.

enddate Required The end date for the search period. e.g. 31/01/2014.

page Optional Page number (starts at 1).

perpage Optional Number of results per page — 10 25 50 100 1000.

search Optional Keyword search term to filter on.

leadtypeid

Optional

The lead group or lead type to filter on.

To filter by lead group, use only the lead group ID. For example, to filter on lead group ID 15263, use 15263.

To filter by lead type, use the group and type IDs concatenated with a hyphen. For example, to filter on lead type ID 9263 in group 15263, use 15263-9263.

userid

Optional

The user or user group to filter on.

To filter by user ID, prefix the user’s ID with u-. For example, to search for user ID 2536, use u-2536.

To filter by user group ID, prefix the user group’s ID with g-. For example, to search for user group ID 81526, use g-81526.

To filter for all unassigned leads, simply use Unassigned.

status

Optional

The status or progress point to filter on.

To filter on a status, prefix the exact string representation of the status with s-. For example, to search for the status ‘Validated’, use s-Validated.

To filter for leads with no status set, use the value n.

To filter on the progress point, use the progress point from the table below prefixed with p-. For example, to search for progress point 1 (All New), use p-1.

Progress Point ID	Meaning
1	All New
2	All Validated
6	All Contacted
8	All Qualified
9	All Converted
o	All Open
oc	All Open/Closed
10	All Closed
c	All Closed/Invalidated
3	All Invalidated

Response

A collection of leads that match the search criteria. Each lead returned includes the following data:

Field	Description
id	ID of the lead.
subid	Sub ID of the lead.
received	Date/time that the lead was received. e.g. `2011-01-01 12:00:00`.
leadgroupid	ID of the lead group that the lead belongs to.
leadgroupname	Name of the lead group that the lead belongs to.
leadtype	Lead’s type.
status	Lead’s status.
user	Name of the lead’s assigned user.
buyer	Name of the partner who has been referred the lead.
introducer	Name of the partner who introduced the lead.
fullname	The full name on the lead.
company	Company name.
phone1	Phone number.
phone2	Alternative phone number.
email	Email address.
address	Address line 1.
towncity	Town or city.
postcode	Postcode.

Error Codes

Code	Description
0	No errors
1	Validation or authentication error
2	XML format error or no XML provided

Read

<request>read</request>

Parameters

Parameter	Required	Description
id	Required	The ID of the lead to read.
subid	Optional	The sub ID of the lead to read.

Response

Field	Description
id	ID of the lead.
subid	Sub ID of the lead.
ipaddress	Originating IP address.
received	Date/time that the lead was received. e.g. `2011-01-01 12:00:00`.
leadgroupid	ID of the lead group that the lead belongs to.
leadgroupname	Name of the lead group that the lead belongs to.
leadtype	Lead’s type.
status	Lead’s status.
progress	Billing point. e.g. `Converted`.
siteid	ID of the site that the lead belongs to.
sitename	Name of the site that the lead belongs to.
userid	ID of the lead’s assigned user.
username	Name of the lead’s assigned user.
buyerid	ID of the partner who has been referred the lead.
buyer	Name of the partner who has been referred the lead.
buyerreference	Reference supplied by the partner who has been referred the lead.
introducerid	ID of the partner who introduced the lead.
introducername	Name of the partner who introduced the lead.
reference	Source/introducer reference.
source	Marketing source.
medium	Marketing medium.
term	Marketing term.
cost	Lead cost.
value	Lead value.
transferdatetime	Date/time that the lead was referred. e.g. `2011-01-01 12:00:00`.
transfersuccessful	Successful telephone transfer — `Yes` `No`.
xmldatetime	Date/time of internet delivery. e.g. `2011-01-01 12:00:00`.
xmlfails	Number of failed internet delivery attempts.
xmlresult	Internet delivery result.
xmlreference	Internet delivery return reference.
appointmentdatetime	Date/time of appointment. e.g. `2011-01-01 12:00:00`.
appointmentnotes	Appointment notes.
lastnotedatetime	Date/time of last note/call. e.g. `2011-01-01 12:00:00`.
lastnote	Details of last note/call.
taskexists	Does the lead have an outstanding task? — `Yes` `No`.
workflowexists	Does the lead have a workflow? — `Yes` `No`.
dropbox	The lead’s email dropbox address.
fullname	The full name on the lead.
title	Person’s title — `Mr.` `Mrs.` `Ms.` `Miss` `Dr.` `Rev.`.
firstname	First name.
lastname	Last name.
company	Company name.
jobtitle	Job title.
phone1	Phone number.
phone2	Alternative phone number.
fax	Fax number.
email	Email address.
address	Address line 1.
address2	Address line 2.
address3	Address line 3.
towncity	Town or city.
postcode	Postcode.
dob	Full date of birth. e.g. `1990-01-01`.
dobday	Day of birth. e.g. `01`.
dobmonth	Month of birth. e.g. `01`.
dobyear	Year of birth. e.g. `1990`.
contacttime	Preferred contact time — `Anytime` `Morning` `Afternoon` `Evening`.
contactphone	Phone contact permission — `Yes` `No` `Unknown`.
contactsms	Text message contact permission — `Yes` `No` `Unknown`.
contactemail	Email contact permission — `Yes` `No` `Unknown`.
contactmail	Mail contact permission — `Yes` `No` `Unknown`.
contactfax	Fax contact permission — `Yes` `No` `Unknown`.
data1 – data50	Additional information fields.
type1 – type50	Descriptions of additional information fields.

Error Codes

Code	Description
0	No errors
1	Validation or authentication error
2	XML format error or no XML provided

Delete

<request>delete</request>

Parameters

Parameter	Required	Description
id	Required	The ID of the lead to delete.

Response

If the delete succeeds, the code will be 0 with the message OK.

Error Codes

Code	Description
0	No errors
1	Validation or authentication error
2	XML format error or no XML provided