TABLE OF CONTENTS [Document Version - 2.0]

• Contents
• Cheat Sheet
  • Web Methods
  • Bulk Loading of Leads
  • Individual Lead Management Methods
  • Full Process
  • Notes
  • What is a RESTful API?
• Usage
• Common API Parameters
• Lead Activation and Deactivation Parameters
• Important Notes
• Authentication
• Tokens API 
  • Token URL
  • Password
  • Steps
• Responses
  • ImportDataResult
  • Entities
    • API Lead Status
    • API Lead Phone Status
• Methods
  • Deactivate Lead by Id
  • Deactivate Leads by Id
  • Deactivate Leads by Phone Number
  • Deactivate Leads by Reference Id
  • Deactivate Leads by Reference Ids
  • Get Lead Info by Reference Id
  • Move Lead by Phone Number
  • Move Lead by Reference Id
  • Reactivate Lead by Id
  • Reactivate Leads by Phone Number
  • Reactivate Leads by Reference Id
  • Reactivate Leads by Reference Ids
  • Update Lead Phone by Phone Number
  • Update Lead Phone by Reference Id
• Bulk Lead Loading Methods
  • Creating an Import Mapping
  • Attaching the File to Import
  • Example CSV format
  • Options
  • Headers
  • Mandatory Params
  • Example Multipart Content
  • Optional Parameters
  • Response When Bulk Imports Complete
  • Add Lead
• Errors and Error Handling 
  • Token Errors
  • Import API Errors
  • Object Definitions
• Example Code 
  • Get Token Example Code
  • Setting Token Example Code
  • Bulk Load Leads Example Code
• Appendix
  • Appendix 1: Phone Types
  • Appendix 2: Lead Deactivation Scope
  • Appendix 3: API Error Codes
  • Appendix 4: API Error Severities
  • Appendix 5: Final Codes
  • Appendix 6: Time Zones

Cheat Sheet

Web Methods

It is important to note that these methods require the use of an API token set in a cookie. Please refer to the Authentication section

Bulk Loading of Leads

Individual Lead Management Methods

These are RESTful requests formatted in the style of

Entity/Id/action

OR

Entity/Id?param1=x&param2=y

Full Process

1. Authenticate and generate an API token.
2. Call relevant API requests.
3. Process return result.

Notes

• If you require secondary table information (scripting information), please utilise the Bulk Upload method and not "AddLead".
• The bulk loader does not require you to write a CSV file to disk, only that you stream your leads to the server.
• You need to have a phone number when adding a lead.
• If you use hot leads or otherwise have leads you would like to push as high priority, you can enable this via the IsHighPriority property on the LeadPhone object. This will prioritise the lead to be called above all others.
• The maximum allowed request size is 51200000 bytes, or 51.2MB. Please consider this when sending large CSV files with the Bulk Import method. A request with too large a payload will return a HTTP 413 status code. 

What is a RESTful API?

A RESTful API is an API that communicates over Hypertext Transfer Protocol (HTTP) to retrieve data and to send data to remote servers using the same HTTP Verbs as the Web.

See 'https://en.wikipedia.org/wiki/Representational_state_transfer'

Back to Contents

Usage

This API allows the remote management of lead data within the MaxContact platform. The API makes it possible to insert and update leads either singly or in bulk by loading CSV, XML or JSON-based lead data files.

Common API Parameters

The following is a list of some common parameters that are used by a number of the API methods, along with details of what each parameter represents.

• Lead ID – This is the unique ID for a lead once loaded into the system.
• List ID – When leads are imported into the system, they are grouped together into lists. This is the unique ID of a particular list as recorded in the database.
• Reference ID – An optional external reference number (e.g. a customer ID from an external CRM system, etc.) that can be supplied when leads are imported into the system and can be used as an alternate way of identifying particular leads.

Lead Activation and Deactivation Parameters

The following is a list of parameters that can be supplied to a number of the API methods that are used to activate and deactivate leads.

• List ID – When activating or deactivating leads, an optional list ID parameter value can be supplied to restrict the set of leads that are activated/deactivated to just ones in the specified list.
• Reactivate DNC -When reactivating leads, this optional Boolean parameter can be used to control whether leads that have been previously given a final code of ‘DNC’ (‘Do Not Call’) are reactivated or not. The default value is false, so if no value is supplied for this parameter, then leads with a final code of ‘DNC’ will not be reactivated.
• Result Code – When deactivating leads, this optional string parameter, of up to 10 characters in length, can be used to provide additional details about the reason for deactivation. If no value is supplied, then a default result code (such as ‘API-Remove’) is applied to the lead and lead phones.
• Scope – When deactivating leads, the scope parameter can be used to restrict the set of leads that are affected by the deactivation. Four different values can be supplied for the scope parameter (see appendix for full list); however, if no scope is specified, then the default value of ‘0 – All’ is used, which instructs the API to deactivate all of the leads that match the other search criteria.
• Update History – When deactivating leads, this parameter instructs the API to update the result code of the last entry in the history table for each of the deactivated leads. The default value for this parameter is false.

Important Notes

• The API methods require the use of an API token in the header of the request. Please check the section on authentication.
• The bulk loader does not require you to write a CSV file to disk, only that you stream your leads to the server
• A phone number is required to import a lead.
• API imports, which are high priority, need to be set at the Import API Mapping configuration page or within the request to import the lead
• The maximum allowed request size is 51200000 bytes, or 51.2MB. Please consider this when sending large CSV files with the bulk import method. A request with too large a payload will return an HTTP 413 status code.

Back to Contents

Authentication

An authentication token is required to access this API. A token can be requested from the token service using the Token API.

Tokens API

All API methods require a security token to use the system. This token is stored in the HTTP cookie to allow multiple API calls from one authentication request.

A token is requested by authenticating with a user and password combination. The Token service API will return a token on success.

Token URL

https://[CUSTOMER].maxcontact.com/webservices/services/apitoken/login/{login}

Password

The password needs to be sent in the authorisation header of the request; the password needs to be converted to Base64 with ASCII encoding to get the bytes[] from the password string.

Steps

1. Make a request to the token URI.
2. Store the token key for any subsequent requests.
3. Make a request to the Lead Management Service.

Recommendations

• It is recommended that you keep track of the Token Key and its expiry, as making a request every time can slow down the import process.
• Login should be plain text.

When a successful API call is made to the API Token service, it will return a JSON/XML object. A token key must be passed to each API endpoint along with the request.

The TokenKey property is the API key you should use for the remainder of the session. You can use the ExpiryDate property to see when this will expire.

Back to Contents

Responses

By default, the API will return an XML response, but Accept and Content-Type headers with values of application/json can be supplied with requests, and this will result in the API returning JSON-formatted responses.

ImportDataResult

Most methods return an ImportDataResult object. The value of the “Errors” property will be a different type dependent on the method used.

{
Success: bool,
Errors: object containing additional information about any errors that were
encountered,
ImmediateRejectCount: integer,
ImportIDs: array of integer
}

{
LeadID: int64, // Unique id of the lead
ListID: int, // Unique id of the list the lead belongs to
ReferenceID: string, // Optional external reference for the lead
Name: string, // Forename
Name2: string, // Surname
OtherInfo: string, // Extra info to be displayed to the agent
QueuedForCall: boolean, // Is the system about to dial the lead
FinalCodeID: int, // See appendix for list of final codes
TotalAttempts: int, // Number of times the lead has been dialled
LastCallDate: datetime, // Date and time of the last call
LastAgentID: int, // User Id of the agent that made the last call
ImportDate: datetime, // Date and time this lead was imported
Supplier: int, // Unique id of the supplier of this lead
LeadPhones: array of APILeadPhoneStatus entities
}

{
LeadPhoneID: int64, // Unique Id of the lead phone
PhoneNumber: string, // Phone number or contact details
PhoneTypeID: int, // Type of phone number (e.g. work, home)
CanCall: boolean, // Indicates whether this number can be called
NextCallDate: datetime, // Date and time of the next call
Attempts: int, // Number of times the number has been dialled
FinalCodeID: int, // See appendix for list of final codes
TotalAttempts: int, // Total dial attempts this value does not reset
LastCallDate: datetime, // Date and time of the last call
LastResultCode: string, // Indicates the outcome of the last call
LastAgentID: int, // User Id of the agent that made the last call
ImportDate: datetime // Date and time this number was imported
}

DELETE
/webservices/services/leadmanagement/DeactivateLeadId/{leadId}
Params:
leadId: string
Returns:
ImportDataResult indicating success or failure

DELETE
/webservices/services/leadmanagement/DeactivateLeadId/{leadIds}
Params:
leadIds: string
Returns:
ImportDataResult indicating success or failure

DELETE
/webservices/services/leadmanagement/DeactivateLeadByPhone/{phoneNumber}
Params:
phoneNumber: string,
resultCode: string,
scope: integer,
listId: int,
updateHistory: boolean
Returns:
ImportDataResult indicating success or failure

DELETE
/webservices/services/leadmanagement/DeactivateLeadByRefId/{referenceId}
Params:
referenceId: string,
resultCode: string,
scope: integer,
listId: int,
updateHistory: boolean
Returns:
ImportDataResult indicating success or failure

[“abc-123”,

“def-456”,

“ghi-789”]

POST
/webservices/services/leadmanagement/DeactivateLeadByRefId
Body:
referenceIds: URL encoded string
Params:
resultCode: string,
scope: integer,
listId: int,
updateHistory: boolean
Returns:
ImportDataResult indicating success or failure

GET
/webservices/services/leadmanagement/GetLeadInfoByReferenceId/{referenceId}
Params:
referenceId: string,
Returns:
An array of APILeadStatus entities (see Entities section)

POST
/webservices/services/leadmanagement/MoveLeadByPhone/{phoneNumber}
Params:
phoneNumber: string
newListId: integer
oldListId: integer
resetAttempts: Boolean
updateFinal: Boolean
finalCode: int
dncException: Boolean
Returns:
ImportDataResult indicating success or failure

POST
/webservices/services/leadmanagement/MoveLeadRefId/{referenceId}
Params:
referenceId: string
newListId: integer
oldListId: integer
resetAttempts: Boolean
updateFinal: Boolean
finalCode: int
dncException: Boolean
Returns:
ImportDataResult indicating success or failure

POST
/webservices/services/leadmanagement/ReactivateLeadId/{leadId}
Params:
leadId: string
reactivateDnc: boolean
Returns:
ImportDataResult indicating success or failure

POST
/webservices/services/leadmanagement/ReactivateLeadByPhone/{phoneNumber}
Params:
phoneNumber: string,
listId: int,
reactivateDnc: boolean
Returns:
ImportDataResult indicating success or failure

POST
/webservices/services/leadmanagement/ReactivateLeadByRefId/{referenceId}
Params:
referenceId: string,
listId: int,
reactivateDnc: boolean
Returns:
ImportDataResult indicating success or failure

POST
/webservices/services/leadmanagement/ReactivateLeadByRefIds
Body:
referenceIds: URL encoded string
Params:
listId: int,
reactivateDnc: boolean
Returns:
ImportDataResult indicating success or failure

POST
/webservices/services/leadmanagement/UpdateLeadPhoneByPhoneNum/{phoneNum}
Params:
phoneNum: string
newPhone: string
listId: integer
reset: Boolean
Returns:
ImportDataResult indicating success or failure

POST
/webservices/services/leadmanagement/UpdateLeadPhoneByPhoneNum/{referenceId}
Params:
referenceId
oldPhone: string
newPhone: string
listId: integer
reset: Boolean
Returns:
ImportDataResult indicating success or failure

POST
/webservices/services/leadmanagement/ImportCsvFiles
/webservices/services/leadmanagement/ImportJsonFiles
/webservices/services/leadmanagement/ImportXmlFiles
BodyParams:
FileName: string
MapName: string
File: filecontent
Returns:
ImportDataResult indicating success or failure

phone,id,first_name,last_name
“01234567890”,1,“joe”,”blogs”

Content-Type: multipart/form-data; boundary=[YOUR DELIMITER] 

Cookie: TokenKey=[YOUR TOKEN]

--DELIMITER
Content-Disposition: form-data; name="CSV Upload"; filename="filename.csv Content-Type: application/octet-stream
first_name,last_name,reference,mobile,home,work
“Joe","Bloggs","abc","9876543210","9876543210","9876543210
“Jane","Bloggs","def","9876543210","9876543210","9876543210

--DELIMITER
Content-Type: text/plain; charset=utf-8
Content-Disposition: form-data; name="mapname"

My Mapping

--DELIMITER
Content-Type: text/plain; charset=utf-8
Content-Disposition: form-data; name="options"

[JSON Optional Parameters]}

--DELIMITER--

<LeadAPIResult.ImportDataResponse
xmlns="http://schemas.datacontract.org/2004/07/Max.LeadManagement.LeadAPIPublic"
xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<Errors xmlns:a="http://schemas.datacontract.org/2004/07/Max.LeadManagement.APIError">
<a:APIError>
<a:ErrorCode>GeneralInfo</a:ErrorCode>
<a:ErrorSeverity>Info</a:ErrorSeverity>
<a:ErrorText>Line: 1 Reason: Duplicate</a:ErrorText>
</a:APIError>
<a:APIError>
<a:ErrorCode>GeneralInfo</a:ErrorCode>
<a:ErrorSeverity>Info</a:ErrorSeverity>
<a:ErrorText>Line: 2 Reason: DoNotCall</a:ErrorText>
</a:APIError>
<a:APIError>
<a:ErrorCode>GeneralInfo</a:ErrorCode>
<a:ErrorSeverity>Info</a:ErrorSeverity>
<a:ErrorText>Line: 3 Reason: DuplicateInFile</a:ErrorText>
</a:APIError>
<a:APIError>
<a:ErrorCode>GeneralInfo</a:ErrorCode>
<a:ErrorSeverity>Info</a:ErrorSeverity>
<a:ErrorText>Line: 4 Reason: InvalidSourceFormat</a:ErrorText>
</a:APIError>
<a:APIError>
<a:ErrorCode>GeneralInfo</a:ErrorCode>
<a:ErrorSeverity>Info</a:ErrorSeverity>
<a:ErrorText>Line: 5 Reason: InvalidPhoneNumber</a:ErrorText>
</a:APIError>
</Errors>
<ImmediateRejectCount>0</ImmediateRejectCount>
<ImportIDs i:nil="true" xmlns:a="http://schemas.microsoft.com/2003/10/Serialization/Arrays"/>
<LeadsImported>100</LeadsImported >
<RejectedDedupe>1</RejectedDedupe>
<RejectedDedupeFile>1</RejectedDedupeFile>
<RejectedDnc>1</RejectedDnc>
<RejectedParsing>1</RejectedParsing>
<RejectedValidation>1</RejectedValidation >
<Success>false</Success>
</LeadAPIResult.ImportDataResponse >

POST
/webservices/services/leadmanagement/addlead
Body:
{
Title: string, // Personal title (Mr, Ms, Dr etc.)
Name: string, // Forename
Name2: string, // Surname
Address: string, // First line of address
Address2: string, // Second line of address
City: string, // City
State: string, // State
PostalCode: string, // Postal code
ReferenceID: string, // Optional external reference for the lead
Supplier: string, // Supplier of the lead data
Cost: decimal, // Cost of the lead data
ListID: integer, // Id of the list the lead should be added to
ReferenceField: string, //
OtherInfo: string, // Extra info to be displayed to the agent
LeadPhones: [
{
PhoneNum: string, // Phone number or contact details
PhoneTypeID: integer, // Type of phone number (e.g. work, home)
CanCallDate: datetime, // Earliest date the lead can be called
TimeZoneID: integer, // Time zone where the lead is located
IsHighPriority: Boolean // High priority lead phones are called first
}
]
}
Returns:
ImportDataResult indicating success or containing any validation failures

{ 

    ErrorId = ErrorID.NoMapMatch, 

    ErrorText = "You do not have a valid map to import with", 

    ErrorSeverity = ErrorSeverities.Severe 

}

{ 

    ErrorId = ErrorID.GeneralWarning, 

    ErrorText = "There were a high number of rejected leads", 

    ErrorSeverity = ErrorSeverities.Warning 

}

var targetUri = new Uri("https://[CUSTOMER].maxcontact.com/webservices/services/apitoken/login/{login}"); 

using (var httpClient = new HttpClient())

{

// Set buffer to a 10 megs for receiving large data sets        

httpClient.MaxResponseContentBufferSize = 10000000;

var base64 = Convert.ToBase64String(Encoding.ASCII.GetBytes(password));        

httpClient.DefaultRequestHeaders.Authorization = new System.Net.Http.Headers.AuthenticationHeaderValue("Basic", base64);

using (HttpResponseMessage response = await httpClient.GetAsync(targetUri))

using (HttpContent content = response.Content)

{

string httpResult = await content.ReadAsStringAsync();            

                if (httpResult.Length > 0)

                {

                        var token = (APIToken)Helper.XmlToObject(httpResult, typeof(APIToken));

                        return token;

                } 

        }      

}

var cookies = new CookieContainer(); cookies.Add(host, new Cookie("TokenKey", returnedToken.TokenKey));

var handler = new HttpClientHandler() { CookieContainer = cookies }) 

Uri uri = new Uri("https://[CUSTOMER].maxcontact.com........")
FileInfo fi = new FileInfo(“[PATH TO YOUR FILE]”);        
string fileName = fi.Name;        
byte[] fileContents = File.ReadAllBytes(fi.FullName);


// open an HttpRequest object
HttpRequestMessage message = new HttpRequestMessage(HttpMethod.Post, uri);        
message.Headers.ExpectContinue = false;

// Fill out the cookie with the token obtained during auth        
CookieContainer cookies = new CookieContainer();        
cookies.Add(uri, new Cookie("TokenKey", "[YOUR TOKEN KEY]"));

// Create a new multipart content section
MultipartFormDataContent multiPartContent = new MultipartFormDataContent("--Max Test-");
ByteArrayContent byteArrayContent = new ByteArrayContent(fileContents);

// Its a stream!
byteArrayContent.Headers.Add("Content-Type", "application/octet-stream");        
multiPartContent.Add(byteArrayContent, "Test CSV Upload", fileName);

// These are all of the options for the server to process        
var formData = new[] {

                    // REQUIRED
                    new KeyValuePair<string, string>("mapname", "default"),
                    // any optional options here in Json
                    //new KeyValuePair<string, string>("options", "{ ListID: 1 }"), 
};

// Add the form fields to the request        
foreach (var kpv in formData)             
        multiPartContent.Add(new StringContent(kpv.Value), kpv.Key);

 message.Content = multiPartContent;

// Make the request
using (var handler = new HttpClientHandler() { CookieContainer = cookies })        
using (var client = new HttpClient(handler))
{            

        var httpRequest = client.SendAsync(message, HttpCompletionOption.ResponseContentRead);
        HttpResponseMessage httpResponse = httpRequest.Result;
        HttpStatusCode statusCode = httpResponse.StatusCode;
        HttpContent responseContent = httpResponse.Content;

        if (responseContent != null)
               var stringContentsTask = responseContent.ReadAsString();             
}