TABLE OF CONTENTS


 

Usage


The purpose of this API is so that you can easily update data for a lead, whether its lead data, lead phone data or customer data.



Process



Search for a Lead


First you will need to authenticate, to do this you can either get a valid token prior and supply this token in the request (see page 4) or send login details in the Authorization header.


Once you have authenticated you will then need to search for the lead to do this you need to use the method ‘Search for Leads’ (see page 5).  This request requires you to use the HTTP POST protocol with a valid ‘APISearchTerms’ (see page 11) object in the request body.


In the response content of this request you will be return a collection of ‘APILead’ (see page 10) which contains a collection of ‘MaxApiResponseLink’ which contains links to methods you can call.



Update a Phone Number


 First you will need to authenticate, to do this you can either get a valid token prior and supply this token in the request (see page 4) or send login details in the Authorization header.


There is many different methods to update a phone number for them all refer to Methods, in this example ‘we will use Update Lead Phone by Lead Reference and Phone Type’. This method will attempt to find a single lead phone and update it to the phone number in the URL; if more than one number is found the request will be rejected.


This request requires you to use the HTTP POST protocol with a URL structured as:









api/v2/leads/byreference/{referenceId}/phonetype/{type}/update/{phonenumber}


  • refererenceId – this is the reference you set for the lead when it was imported
  • type – the phone type you want to update (PhoneType – see page 13)
  • phonenumber – the number you want to update the found entity to.



What is a RESTful API


A RESTful API is an API that communicates over Hypertext Transfer Protocol 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’ for more information.



HATEOAS Driven API


This API is HATEOAS (Hypermedia as the Engine of Application State) driven so that any content returned from a request will contain hypermedia links to progress your request.


See ‘https://en.wikipedia.org/wiki/HATEOAS’ for more information.



Authentication


There is multiple ways to authenticate to use the API.



Token Authentication


You can get a token using the lead management API (refer to lead management document) then you can set this as a cookie “TokenKey” or you can pass it in the request Authorization header in the format of “Bearer base64Token”.



Basic Authentication


Another option is Basic Authentication where you supply the request header Authorization which contains both the username and password for you login details.


The header needs in the format of “Basic Base64(username:password)”; the header value should be something like “Basic dXNlcjpwYXNzd29yZA==” this was for username : user and password : password.

Methods – Lead API


Search for Leads


Returns collection of APILead



POST - api/v2/leads/search
Request body - APISearchTerms


Example:


https://(customer).maxcontact.com/LeadServices/api/v2/leads/search


Request Body (raw/json):



{
 “Name”: “MaxTest”,
 “CustomerName2”: “Support”,
 “Home”: “07999999999”
}


Postman API Example:



 


 



Bulk Update Leads


Accepts an array of APILeads to updates



PUT - api/v2/leads/
Request body – APILead[]


Will also update customer data


Example:


https://(customer).maxcontact.com/LeadServices/api/v2/leads


Request Body (raw/json):



[
      {
              ReferenceId: "PPE222236707112529",
              Title: "Mrs",
              FirstName: "Jane",
              LastName: "Doe",
              Address: "20 long street",
              CustomerData:
              [
                     {
                     "FieldId": 372,
                     "Value": "Female",
                     },
                     {
                     "FieldId": 373,
                     "Value": "Doctor",
                     }
              ]     
      },
      {
              ReferenceId: "EPP288240177212540",
              FirstName: "John",
              LastName: "Doe",
              PostalCode: "M12 1DL",
              CustomerData:
              [
                     {
                     "FieldId": 372,
                     "Value": "Male",
                     },
                     {
                     "FieldId": 373,
                     "Value": "Dentist",
                     }            
             ]
       }
]


 


Postman API Example




 



Get Lead by Id


Returns single APILead found



GET - api/v2/leads/{leadId:long}


Example:


https://(customer).maxcontact.com/LeadServices/api/v2/leads/123


Postman API Example:



 



Update Lead by Id


Updates found lead with lead information found in request body



PUT - api/v2/leads/{leadId:long}
Request body - APILead


Will also update any customer data provided.


Example: 


https://(customer).maxcontact.com/LeadServices/api/v2/leads/123


Request Body (raw/json)



{
ReferenceId: "EPP288240177212540",
CustomerData:
[
{
"FieldId": 372,
"Value": "Male",
}
]
}


Postman API Example:



 

 



Get Fields for Lead


Returns all APICustomerData for a lead optional to filter by table




GET - api/v2/leads/{leadId:long}/fields?tableId={tableId:int}


Example:


https://(customer).maxcontact.com/LeadServices/api/v2/leads/123/fields?tableId=1


Postman API Example:


 



Get Data for Field and Lead


Gets APICustomerData for a certain customer field



GET - api/v2/leads/{leadId:long}/fields/{fieldId:int}


Example:


https://(customer).maxcontact.com/LeadServices/api/v2/leads/123/fields/1


Postman API Example:


 


Update Data for Field


Updates the value of the found customer data



PUT - api/v2/leads/{leadId:long}/fields/{fieldId:int}/{newValue:string}


Example:


https://(customer).maxcontact.com/LeadServices/api/v2/leads/123/fields/1/cheese


Postman API Example:




Get Lead Phones for Lead


Gets All APILeadPhones for the found APILead



GET - api/v2/leads/{leadId:long}/phones


Example:


https://(customer).maxcontact.com/LeadServices/api/v2/leads/123/phones


Postman API Example:


 


Create Lead Phone for Lead Id


Creates APILeadPhone matching APILeadPhone in request body for found lead



POST - api/v2/leads/{leadId:long}/phones
Request body - APILeadPhone


Example:


https://(customer).maxcontact.com/LeadServices/api/v2/leads/123/phones


Request body (raw/json):



{
 “PhoneNumber”: “0012456852”,
 “PhoneType”: 2
}


Postman API Example:


 

 


Get Lead Phones for Lead by Phone Number


Gets a collection of APILeadPhones for a lead with matching phone number



GET - api/v2/leads/{leadId:long}/phonenumber/{phonenumber:string}


Example:


https://(customer).maxcontact.com/LeadServices/api/v2/leads/123/phonenumber/07802473946


Postman API Example:




Update Lead Phone for Lead by Phone Number


Updates APILeadPhone for a lead with the matching phone number to phone number provided



POST - api/v2/leads/{leadId:long}/phonenumber/{phonenumber:string}/update/{phonenumber:string}


Example:


https://(customer).maxcontact.com/LeadServices/api/v2/leads/123/phonenumber/07802473946/update/07802473941


Postman API Example:




Update Can Call Date and Priority by Lead Id and Phone Number


Will update found leads phone can call date and priority 



POST - api/v2/leads/{leadId:long}/phonenumber/{phonenumber:string}/
Request body - APILeadPhoneUpdate


Example: 


https://(customer).maxcontact.com/LeadServices/api/v2/leads/123/phonenumber/07802473942


Request body (raw/json):



{
 CanCallDate: '2018-02-20T18:05:39.049Z',
 HighPriority: true
}


Postman API Example:



 

 


Gets Leads by Reference Id


Gets collection of APILead by reference id



GET - api/v2/leads/byreference/{referenceId:string}


Example:


https://(customer).maxcontact.com/LeadServices/api/v2/leads/byreference/X12521AS456141


Postman API Example:




Get Lead Phones by Lead Reference


Gets all APILeadPhone for the reference id provided



GET - api/v2/leads/byreference/{referenceId:string}/phones


Example:


https://(customer).maxcontact.com/LeadServices/api/v2/leads/byreference/X12521AS456141/phones


Postman API Example:




Create Lead Phone by Lead Reference


Creates Lead Phone for lead found by reference using APILeadPhone in request body



POST - api/v2/leads/byreference/{referenceId:string}/phones?listId={int}&updateAll={bool}
Request Body - APILeadPhone


Example:


https://(customer).maxcontact.com/LeadServices/api/v2/leads/byreference/X12521AS456141/phones?listId=1&updateAll=false


Request body (raw/json):



{
 “PhoneNumber: “0012456812”,
 “PhoneType”: 0
}


Postman API Example:



 



Get Lead Phones by Lead Reference and Phone Type


Gets collection of APILeadPhones for leads found with reference and matching phone type



GET - api/v2/leads/byreference/{referenceId:string}/phonetype/{type:PhoneType}


Example:


https://(customer).maxcontact.com/LeadServices/api/v2/leads/byreference/X12521AS456141/phonetype/1


Postman API Example:


 


Update Lead Phone by Lead Reference and Phone Type


Updates APILeadPhone phone number to provided phone number by lead reference and phone type



POST - api/v2/leads/byreference/{referenceId:string}/phonetype/{type:PhoneType}/update/{phonenumber:string}


Example:


https://(customer).maxcontact.com/LeadServices/api/v2/leads/byreference/X12521AS456141/phonetype/1/update/07802473943


Postman API Example:


 


Get Lead Phones by Lead Reference and Phone Number


Gets all APILeadPhones for found leads with matching phone number provided



GET - api/v2/leads/byreference/{referenceId:string}/phonenumber/{phonenumber:string}


Example:


https://(customer).maxcontact.com/LeadServices/api/v2/leads/byreference/X12521AS456141/phonenumber/07802473942


Postman API Example:




Update Lead Phone by Lead Reference and Phone Number


Updates found APILeadPhone phone number by lead reference and phone number



POST - api/v2/leads/byreference/{referenceId:string}/phonenumber/{originalphonenumber:string}/update/{phonenumber:string}


Example:


https://(customer).maxcontact.com/LeadServices/api/v2/leads/byreference/X12521AS456141/phonenumber/07802473942/update/01214578452


Postman API Example:




Update Can Call Date and Priority by Reference and Phone Number


Will update found leads phone can call date and priority 



POST - api/v2/leads/byreference/{referenceId:string}/phonenumber/{phonenumber:string}
Request body - APILeadPhoneUpdate


Example: 


https://(customer).maxcontact.com/LeadServices/api/v2/leads/byreference/X12521AS456141/phonenumber/07802473942


Request body (raw/json):



{


 CanCallDate: '2018-02-20T18:05:39.049Z',


 HighPriority: true


}


Postman API Example:



 


Methods – Lead Phone API



Get Lead Phone by Id


Gets single APILeadPhone by id



GET - api/v2/phone/{leadphoneid:long}


Example:


https://(customer).maxcontact.com/LeadServices/api/v2/phone/12354123


Postman API Example:




Update Lead Phone by Id


Updates APILeadPhone phone number found by id to provided phone number



POST - api/v2/phone/{leadphoneid:long}/update/{phonenumber:string}


Example:


https://(customer).maxcontact.com/LeadServices/api/v2/phone/12354123/update/07802473942


Postman API Example:




Update Can Call Date and Priority by Id


Will update found leads phone can call date and priority 



POST - api/v2/phone/{leadphoneid:long}
Request body - APILeadPhoneUpdate


Example: 


https://(customer).maxcontact.com/LeadServices/api/v2/phone/12354123


Request body (raw/json):



{
 CanCallDate: '2018-02-20T18:05:39.049Z',
 HighPriority: true
}


Postman API Example:



 

 


Get Lead Phones by Phone Number


Gets all APILeadPhones with matching phone number



GET - api/v2/phone/phonenumber/{phonenumber:string}


Example:


https://(customer).maxcontact.com/LeadServices/api/v2/phone/phonenumber/07804421245


Postman API Example:


 


Update Lead Phone by Phone Number


Updates APILeadPhone phone number found by phone number



POST - api/v2/phone/phonenumber/{phonenumber:string}/update/{newphonenumber:string}


Example:


https://(customer).maxcontact.com/LeadServices/api/v2/phone/phonenumber/07804421245/update/07802435412


Postman API Example:




Update Can Call Date and Priority by Phone Number


Will update found leads phone can call date and priority 



POST - api/v2/phone/phonenumber/{phonenumber:string}
Request body - APILeadPhoneUpdate


Example: 


https://(customer).maxcontact.com/LeadServices/api/v2/phone/phonenumber/07804421245


Request body (raw/json):



{
 CanCallDate: '2018-02-20T18:05:39.049Z',
 HighPriority: true
}


Postman API Example:



 


Entities



APILead - Object


Return object for any lead that has been found



{
Id: long,
Title: string,
FirstName: string,
LastName: string,
OtherInfo: string,
Address: string,
Address2: string,
City: string,
PostalCode: string,
State: string,
ReferenceID: string,
ReferenceField: string,
Supplier: string,
ListID: int,
CustomerData: APICustomerData[],
LeadPhone: APILeadPhone[],
Links: MaxApiResponseLink[]
}




APILeadPhone - Object


Return object for any phone data that is returned.



{
Id: long,
LeadId: long,
PhoneNumber: string,
PhoneType: Enum.PhoneType,
Links: MaxApiResponseLink[]
}



APILeadPhoneUpdate – Object


Object used in request to update lead phones



{
       CanCallDate: DateTime?,
       HighPriority: Boolean
}



APICustomerData - Object


Secondary data object that is returned with the APILead.



{
Id: long,
CustomerTableId: int,
DateType: enum.AllowedDataType,
Name: string,
Links: MaxApiResponseLink[]
}



APISearchTerms - Object


Object which is used to search for leads



{
ReferenceId: string,
PhoneNumber: string,
Name: string
}



APICustomerField - Object


Customer Field object that is returned from the tables API



{
Id: long,
CustomerTableId: int,
DateType: enum.AllowedDataType,
Name: string,
Links: MaxApiResponseLink[]
}



APICustomerTable - Object


Customer Table object



{
Id: long,
Name: string,
Description: string,
Active: bool,
Links: MaxApiResponseLink[]
}



HATEOAS object that is returned with all API objects



{
Href: string,
Method: string,
Rel: string,
}



MaxApiResponse - Object


Response returned when requested object cannot be returned



{
ErrorCode: Enum.ErrorCode,
ErrorServerity: Enum.ErrorServerity,
ErrorMessage: string,
SuccessResult: boolean
}


Enums



AllowDataType - Enum



@string,
@integer,
@double,
@date,
@time,
@datetime,
@boolean,
@phonenumber


Possible customer data types



PhoneType - Enum



Home,
Work,
Mobile


Possible Phone Type for lead phones



ErrorCode - Enum



NotAuth,
GeneralInfo,
GeneralWarning,
GeneralError,
DBError,
Rejected,
InvalidLead,
InvalidLeadId,
InvalidLeadPhone,
InvalidLeadPhoneId,
NotFound,
InvalidData,
InvalidPhoneType,
Success


Possible Error Codes in response



ErrorSeverities - Enum



None,
Info,
Warning,
Severe


Possible Error Serverities returned in response