LeadQual Web Services

LeadQual Web Services

Version: 1.0.30

Technical specifications for the supported web services are published here.

Additional notes on using the web services:

All Services
All web services take as their first two parameters a user ID and password, which must correspond to an account that is permissioned to make changes to the LeadQual data.

All web services with the exception of GetLeads and GetModifiedLeads return an integer to indicate the success of the function. The return values of these web services are as follows:

Code	Summary	Description
0	OK	The service performed the specified action without any problems occurring
1	Bad user ID or password	The supplied credentials are incorrect, or the account does not have sufficient permission to use the web services
2	System Error	An internal problem occurred within the LeadQual system. Please contact LeadQual if this happens
3	Non-unique value	One of the specified value needs to be unique but is not. For example, you cannot create a Team with a name that is already used for an existing Team
5	Invalid data	One of the specified value needs to be unique but is not. For example, you cannot create a Team with a name that is already used for an existing Team
6	Data too long	The specified data (e.g. the name of a Team) is too long
7	Lead not found	The specified Lead ID is invalid
8	No Client Company	The specified creadentials are not associated with a Client that has an active account within the LeadQual system
9	One of multiple data values invalid	When specifying multiple items in a comma-separated list (e.g. the names of the Teams with which a Sales Associate os to be associated), one or more of the individual items is invalid. In these situations no data is changed
10	Unknown Lead Form Metric Name	The specified Lead Form Metric Name was invalid
11	Invalid Lead Form Metric Value	The specified value for the Lead Form Metric Name failed validation
12	Cannot update locked Lead	The specified Lead is currently in a state where it cannot be modifed
15	Object not found	An item referenced by one of the supplied parameters is invalid. For example, if the ID of the specified Sales Associate when setting his/her ZIP code coverage does not correspond to an existing Sales Associate
16	The system is busy	The LeadQual web services system is too busy to service requests - please re-try.
17	Login Not Authorized	The login is not authorized.

Unless otherwise stated, all parameters for all web services are mandatory.

Offices

CreateOffice

Parameters

pName - Name of the new office to create (must be unique, case insensitive)
pDescription – Description for the new office (can be null)

Error Codes

Code	Description
0	Office created successfully
1	Invalid username or password
2	A system error has occurred, this is typically due to failure accessing SQL Server
3	The office name specified already exists (case insensitive)
5	A required field is invalid (Name)
6	Office name has too many characters (120 chars allowed)
8	The user supplied does not have an associated client (Is not a client admin)

UpdateOffice

Parameters

pCurrentName - Name of the existing office to be updated
pNewName – New name for the existing office (must be unique, case insensitive)
pNewDescription - New description for the existing office (can be null)

Error Codes

Code	Description
0	Office updated successfully
1	Invalid username or password
2	A system error has occurred, this is typically due to failure accessing SQL Server
3	The new office name specified already exists (case insensitive)
5	A required field is invalid (CurrentName, NewName)
6	New office name has too many characters (120 chars allowed)
15	The current office specified does not exist
8	The user supplied does not have an associated client (Is not a client admin)

Teams

CreateTeam

Parameters

pName - Name of the new team to create (must be unique, case insensitive)
pDescription – Description of the new team to create (can be null)
pAssociatedOffice - Name of the office in which this team is associated with

Error Codes

Code	Description
0	Team created successfully
1	Invalid username or password
2	A system error has occurred, this is typically due to failure accessing SQL Server
3	The team name specified already exists (case insensitive)
5	A required field is invalid (Name)
6	Team name has too many characters (120 chars allowed)
15	The specified associated office does not exist
8	The user supplied does not have an associated client (Is not a client admin)

UpdateTeam
Parameters

pCurrentName - Name of the existing team to be updated
pNewName – New name for the existing team (must be unique, case insensitive)
pNewDescription - New description for the existing team (can be null)

Error Codes

Code	Description
0	Team updated successfully
1	Invalid username or password
2	A system error has occurred, this is typically due to failure accessing SQL Server
3	The new team name specified already exists (case insensitive)
5	A required field is invalid (CurrentName, NewName)
6	New team name has too many characters (120 chars allowed)
15	The current team specified does not exist
8	The user supplied does not have an associated client (Is not a client admin)

SetTeamLeader

Parameters

pTeamName - The existing team to set the new team leader
pSalesAssociateID – The sales associate to become the new team leader

Error Codes

Code	Description
0	Team leader has been set successfully
1	Invalid username or password
2	A system error has occurred, this is typically due to failure accessing SQL Server
5	A required field is invalid (TeamName)
15	Team name does not exist or Sales Associate does not exist
8	The user supplied does not have an associated client (Is not a client admin)

Sales Associates

CreateSalesAssociate

Parameters

pFirstName - First name of the new Sales Associate
pLastName – Last name of the new Sales Associate
pRank - Rank of the new Sales Associate (non negative)
pPrimaryPhone – Primary phone of the new Sales Associate
pSecondaryPhone - Secondary phone of the new Sales Associate
pEmailAddress – Email address of the new Sales Associate
pLoginID - LoginID for the new Sales Associate (must be unique, case insensitive)
pPassword – Password for the new Sales Associate
pAssociatedTeamName - Team in which the new Sales Associate will be assigned to
pNewSalesAssociateID – Out parameter giving the Sales Associate ID of the Sales Associate just created (0 if creation was unsuccessful)

Error Codes

Code	Description
0	Sales Associate created successfully
1	Invalid username or password
2	A system error has occurred, this is typically due to failure accessing SQL Server
3	A user with the specified LoginID already exists or a Sales Associate with that Primary Phone already exists
5	A field is invalid PrimaryPhone, SecondaryPhone (if specified), Password too short (6 char minimum), Rank is less than 0, EmailAddress (if specified)
15	Team name specified does not exist
8	The user supplied does not have an associated client (Is not a client admin)

UpdateSalesAssociate

Parameters

pSalesAssociateID - The ID of the Sales Associate to update
pFirstName – The first name of the Sales Associate to change to
pLastName - The last name of the Sales Associate to change to
pRank – The rank of the Sales Associate to change to
pPrimaryPhone - The primary phone of the Sales Associate to change to
pSecondaryPhone – The secondary phone of the Sales Associate to change to
pEmailAddress - The email address of the Sales Associate to change to
pLoginID – The new login id for the Sales Associate (must be unique)
pPassword - The new password for the Sales Associate

Error Codes

Code	Description
0	Sales Associate updated successfully
1	Invalid username or password
2	A system error has occurred, this is typically due to failure accessing SQL Server
3	A user with the specified LoginID already exists or a Sales Associate with that Primary Phone already exists
5	A field is invalid PrimaryPhone, SecondaryPhone (if specified), Password too short (6 char minimum), Rank is less than 0, EmailAddress (if specified)
15	Sales Associate with the specified ID does not exist
8	The user supplied does not have an associated client (Is not a client admin)

SetSalesAssociateZIPCodes

Parameters

pSalesAssociateID - Sales Associate to set zip codes for
pZIPCodes – Comma separated list of zip codes to assign to the Sales Associate

Error Codes

Code	Description
0	Zip Codes for Sales Associate set successfully
1	Invalid username or password
2	A system error has occurred, this is typically due to failure accessing SQL Server
5	A required field is invalid (ZIPCodes)
15	The Sales Associate specified does not exist
8	The user supplied does not have an associated client (Is not a client admin)

Organization

SetOfficesForTeam

Parameters

pTeamName - Team name to set offices for
pOfficeNames – Comma separated list of office names to assign to the team

Error Codes

Code	Description
0	Offices assigned to team successfully
1	Invalid username or password
2	A system error has occurred, this is typically due to failure accessing SQL Server
5	A required field is invalid (TeamName, OfficeNames)
15	The team specified does not exist
8	The user supplied does not have an associated client (Is not a client admin)

SetTeamsForSalesAssociate

Parameters

pSalesAssociateID - Sales Associate to set teams for
pTeamNames – Comma separated list of teams to assign the Sales Associate to

Error Codes

Code	Description
0	Team assigned to Sales Associate successfully
1	Invalid username or password
2	A system error has occurred, this is typically due to failure accessing SQL Server
5	A required field is invalid (TeamNames)
15	Sales Associate specified does not exist
8	The user supplied does not have an associated client (Is not a client admin)

Leads

Lead States

Value	Description
0	All lead states
2	Pending
3	In progress
4	Assigned to Sales Associate
6	Assigned to Client
7	Abandoned due to an incorrect phone number
8	Consumer has been contacted
9	Lead has been qualified
10	Lead has been unqualified
12	Abandoned for any reason other than incorrect phone or due to specific client business rules
13	Lead has been unqualified, do not attempt to call back
15	Lead has been unqualified, a follow up is needed to the consumer
17	Lead has been abandoned due to client business rules

GetSpecificLead

Parameters

pLeadID - Specifies the LeadID to get details

String	Description
Leads Xml	Leads retrieved successfully
"Bad User ID/Password"	Invalid username or password
"A system error has occured"	A system error has occurred, this is typically due to failure accessing SQL Server
"There is no associated client for this user"	The user supplied does not have an associated client (Is not a client admin)
"The value for a field was not found"	The lead was not found

GetLeads

Parameters

pCreationDateFrom - Specifies the start date range in which leads were created
pCreationDateTo – Specifies the end date range in which leads were created
pLeadState – Specifies the state of the leads retrieved

Both pCreationDateFrom and pCreationDateTo can be of the form "1/31/2007" (implying 12:00AM that day), or "1/31/2007 10:30AM".

Error Codes

String	Description
Leads Xml	Leads retrieved successfully
"Bad User ID/Password"	Invalid username or password
"A system error has occured"	A system error has occurred, this is typically due to failure accessing SQL Server
"A field is invalid"	A field is invalid (CreationDateFrom, CreationDateTo)
"There is no associated client for this user"	The user supplied does not have an associated client (Is not a client admin)

GetModifiedLeads

Parameters

pModificationDate - Specifies to retrieve leads modified after this date
pLeadState – Specifies the state of the leads retrieved

pModificationDate can be of the form "1/31/2007" (implying 12:00AM that day), or "1/31/2007 10:30AM".

Error Codes

String	Description
Leads Xml	Leads retrieved successfully
"Bad User ID/Password"	Invalid username or password
"A system error has occured"	A system error has occurred, this is typically due to failure accessing SQL Server
"A field is invalid"	A field is invalid (ModificationDate)
"There is no associated client for this user"	The user supplied does not have an associated client (Is not a client admin)

GetVersion

Returns the current version number as a string