PUBLITRAC API Reference documentation


Summary


This document provides information to manage leads using PUBLITRAC API

Note that the API is limited at 35 calls/second.

URL

Authentification


Authentication arguments must be provided to every call. 

Parameters

NameDescription
methodThe API method you want to call
apikeyYour API Key
username

Your username (Same as your PUBLITRAC login)


*Note that we can provide you a specific user to use the API

mot de passeYour password (Same as your PUBLITRAC login)
parametersThe number of parameters required depend on the method called.


Syntaxe

https://app.publitrac.com/api?method=[Method Name]&apikey=[Your API Key]&username=[Your user]&password=[Your password]&[Your parameters (email, query, viewName, listName)]

Examples


https://app.publitrac.com/api?method=getLeads&apikey=1234e567-890c-123e-4567-8901b234c56&username=MyUser&password=MyPassw0rd&query=<XML representation of your search>
https://app.publitrac.com/api?method=getLead&apikey=1234e567-890c-123e-4567-8901b234c56&username=MyUser&password=MyPassw0rd&email=Email representing your search

API Key

Your API Key can be found in the configuration section in the "Account information" tab

Lead fields

The complete list can be found as List and description of all lead fields.

Format

All dates sent with PUBLITRAC API must be in the following format : "yyyy-mm-dd".

If the firls must also indicate time, the format must be "yyyy-mm-dd hh:ii:ss". Example : 2014-01-28 02:04:01


XML Structure


To ensure the XML parameters are properly coded, it is recommended to validate them with a tool such as : http://www.w3schools.com/xml/xml_validator.asp


Methods Index


Get leads

Search lead by query


Url

https://app.publitrac.com/api

Supported

GET

Methode

getLeads

Mandatory Parameters

method : getLeads

apiKey : Your API Key

username : Your username

password : Your password

query : An URL encoded XML representation of your search.

Optional Parameters

page : Page id (default is 1)

Remarks

Custom fields are returned as normal lead fields. Query xml representation is described at the end of this document.


Examples



Request
<?xml version="1.0" encoding="UTF-8"?>
<request>
    <queries>
        <query>
            <field>firstName</field>
            <operator>like</operator>
            <value>john</value>
        </query>
        <query>
            <field>lastName</field>
            <operator>like</operator>
            <value>smith</value>
        </query>
        <query>
            <field>email</field>
            <operator>like</operator>
            <value>johnsmith@%</value>
        </query>
    </queries>
</request>
Response
<response>
    <leads>
        <lead>
            <id>470</id>
            <firstName>John</firstName>
            <lastName>Smith</lastName>
            <middleName></middleName>
            <company>PUBLIPAGE</company>
            <phone>555-555-2149</phone>
            <email>johnsmith@publipage.com</email>
            <mailingAddress></mailingAddress>
            <originalSource>Google</originalSource>
            <originalSourceType>Organic Search</originalSourceType>
            <keyword>marketing automation</keyword>
            <jobTitle></jobTitle>
            <dateOfBirth></dateOfBirth>
            <status>Active</status>
            <score>0</score>
            <postalCode></postalCode>
            <country></country>
            <city></city>
            <state></state>
            <doNotCall>0</doNotCall>
            <doNotCallReason></doNotCallReason>
            <token>_nl-publipage.com-1282527313351-84730</token>
            <unsubscribed>0</unsubscribed>
            <unsubscribeCause></unsubscribeCause>
            <fax></fax>
            <mobile></mobile>
            <isCustomer>0</isCustomer>
            <isAnonymous>0</isAnonymous>
            <emailInvalid>0</emailInvalid>
            <emailInvalidCause></emailInvalidCause>
            <notes></notes>
            <suspended>0</suspended>
            <suspendedReason></suspendedReason>
            <blacklisted>0</blacklisted>
            <blacklistedCause></blacklistedCause>
            <customerId></customerId>
            <website></website>
            <language></language>
            <nbrEmployees></nbrEmployees>
            <revenue></revenue>
            <crmLeadId>5564344</crmLeadId>
            <createdDate>2015-08-23 01:35:13</createdDate>
            <lastUpdated>2015-10-25 02:20:06</lastUpdated>
            <someCustomField>my custom field</someCustomField>
        </lead>
    </leads>
    <paging>
        <page>1</page>
        <items>1</items>
        <offset>100</offset>
        <total>1</total>
    </paging>
    <status>2001</status>
    <message>Get leads success.</message>
</response>
getLeads - Error code
getLeads

success: <status>2001</status> <message>Get leads success.</message>
error: none

Your can search all leads with an empty request:

<?xml version="1.0" encoding="UTF-8"?>
<request>
    <queries></queries>
</request>


Get lead

Retrieve a single lead based on email address.


Url

https://app.publitrac.com/api

Supported

GET

Methode

getLead

Mandatory Parameters

method : getLead

apiKey : Your API Key

username : Your username

password : Your password

email : Lead email

Optional Parameters


Remarks

If you do not have the email address, use the getLeads method to search the requested lead.

The email must contain 50 characters or less. 


Examples


Request
https://app.publitrac.com/api?method=getLead&apiKey=myApiKey&username=john&password=pass&email=johnsmith@publitrac.com
Response
<?xml version="1.0" encoding="UTF-8"?>
<response>
    <leads>
        <lead>
            <id>26005</id>
            <firstName>John</firstName>
            <lastName>Smith</lastName>
            <middleName></middleName>
            <company>PUBLITRAC</company>
            <phone>514-555-2149</phone>
            <email>johnsmith@publitrac.com</email>
            <mailingAddress>123 Street</mailingAddress>
            <originalSource>New Lead</originalSource>
            <originalSourceType>Manual</originalSourceType>
            <keyword>Marketing Automation Solution</keyword>
            <jobTitle></jobTitle>
            <dateOfBirth></dateOfBirth>
            <status>Active</status>
            <score>0</score>
            <postalCode>J4W 1Z1</postalCode>
            <country>Canada</country>
            <city>Montreal</city>
            <state>Quebec</state>
            <doNotCall>0</doNotCall>
            <doNotCallReason></doNotCallReason>
            <token></token>
            <unsubscribed>0</unsubscribed>
            <unsubscribeCause></unsubscribeCause>
            <fax></fax>
            <mobile></mobile>
            <isCustomer>0</isCustomer>
            <isAnonymous>0</isAnonymous>
            <emailInvalid>0</emailInvalid>
            <emailInvalidCause></emailInvalidCause>
            <notes></notes>
            <suspended>0</suspended>
            <suspendedReason></suspendedReason>
            <blacklisted>0</blacklisted>
            <blacklistedCause></blacklistedCause>
            <customerId></customerId>
            <website></website>
            <language></language>
            <nbrEmployees></nbrEmployees>
            <revenue></revenue>
            <crmLeadId></crmLeadId>
            <createdDate>2010-06-04 15:58:37</createdDate>
            <lastUpdated>2010-06-04 15:58:37</lastUpdated>
            <someCustomField>custom value</someCustomField>
        </lead>
    </leads>
    <status>2002</status>
    <message>Get lead success.</message>
</response>
getLead - Error code
getLead

success: <status>2002</status> <message>Get lead success.</message>
error: <status>9005</status> <message>Get lead failed.</message>

Les balises d'erreurs qu'on peut retrouver:
<errors> 
<error> One lead email is required</error> 
</errors>


Sync Lead

Synchronize one or many leads, if the lead exists, it will be updated with the new information or create a new one if there is none corresponding.



Url

https://app.publitrac.com/api

Supported

POST

Methode

syncLead

Mandatory Parameters

method : syncLead

apiKey : Your API Key

username : Your username

password : Your password

query : Xml representation of the lead to update

Remarks

This method will add a new lead if the token, the crmLeadId or the email address are not in the database. Unique identifiers are in this order: the ‘token’, the ‘crmLeadId’ and then the ‘email address’.  The email address is always mandatory and must be valid.

It is possible to synchronize your leads with different unicity keys; 

  • Email address is the default unicity key. For any lead in your account, each time the SyncLead method is invoked, the process validates if there is a lead corresponding to their criteria or creates a new one if there is none.
  • Email address and CRM Lead Id : In the instance where a CRM lead Id is added in the Synchronisation, the process will validate if a lead which has both information already exists and updates the leads corresponding to their criteria or creates a new one if there is none. 
  • Token : The token is a cookie that is set on the visitor browser which is used to track the interactions of a lead before and after it's acquisition. The Publitrac token is a string that is similar to "_nl-publitrac.com-1111111111111-11111". If useToken is set to true, PUBLITRAC will find the lead or the anonymous lead with this token and update the information accordingly. If no leads are found, a new lead will be created with this token. This option will over-write all other unicity key rules except the customUnicityKeys.
  • Custom unicity key : In the instance when you need to have a différent unicity key, for example only the crmLeadID, your can define your own by the customUnicityKeys. It will validate if there already is a lead that has the unicity key information and update the leads corresponding to their criteria or create a new one if there is none. This option will over-write all other unicity key rules including the useToken rule.

    ** if there is more than one lead found meeting the criteria and that mergeAnonymous or useToken or crmLeadId was used in the query, the API call will respond with an error.

It is also possible to merge or ignore the Anonymous leads. That means, if you synchronized your leads from a web form, you may want to use a custom unicity key, for example, the CRM Lead ID and make sure to merge the interactions which ocurred before the acquisition based on his Token.  In this case you'll configure  mergeAnonymous to 1 (true) useToken to 0 (false) and specify the corresponding token and crmLeadId in the lead information.

If the values mergeAnonymous or useToken are not set, the default value is set to 0 (false).

Be careful with the following most common errors :

  • The <email></email> node can not be empty or be in an invalid email format
  • Duplicate leads based on the selected unicity key
  • Using the mergeAnonymous without providing a Token value.
  • Have empty values for any fields specified un a unicity key (example the customUnicityKeys with crmLeadId and firstName with these 2 values empty)
  • <language> should be a language code (ISO 639-1). Currently publitrac supports en/fr as Languages. You can save anything you want in this field, but you won't be able to send emails to leads with wrong language.



Examples

Request
<?xml version="1.0" encoding="UTF-8"?>
<request>
    <mergeAnonymous>0</mergeAnonymous>
	<useToken>1</useToken>
	<customUnicityKeys>
		<key>crmLeadId</key>
		<key>customKey2</key>
	</customUnicityKeys>
    <lead>
        <token>_nl-yourdomain.com-1323891914130-53205</token>
        <crmLeadId>CRM_ID134</crmLeadId>
        <firstName>John</firstName>
        <lastName>Smith</lastName>
        <middleName></middleName>
        <company>ACME</company>
        <phone>555-423-2453</phone>
        <email>johnsmith@mydomain.com</email>
        <mailingAddress>134 Ocean Street</mailingAddress>
        <leadSource>New Production ABC</leadSource>
        <originalSource> New Production ABC</originalSource>
        <originalSourceType>Organic</originalSourceType>
        <jobTitle>Software Engineer</jobTitle>
        <score>90</score>
        <postalCode>90211</postalCode>
        <country>USA</country>
        <city>Compton</city>
        <state>CA</state>
        <doNotCall>0</doNotCall>
        <doNotCallReason></doNotCallReason>
        <unsubscribed>0</unsubscribed>
        <unsubscribeCause></unsubscribeCause>
        <unsubscribeReason></unsubscribeReason>
        <fax>555-324-2134</fax>
        <mobile>555-432-1242</mobile>
        <isCustomer>0</isCustomer>
        <isAnonymous>0</isAnonymous>
        <emailInvalid>0</emailInvalid>
        <emailInvalidCause></emailInvalidCause>
        <notes>This lead is very interest in product ABC</notes>
        <suspended>0</suspended>
        <suspendedReason></suspendedReason>
        <blacklisted>0</blacklisted>
        <blacklistedCause></blacklistedCause>
        <customerId></customerId>
        <website>http://www.acme.com</website>
        <language>fr</language>
        <nbrEmployees>4</nbrEmployees>
        <revenue>400000</revenue>
        <customFields>
            <carColor>Red</carColor>
            <carMaker>Infiniti</carMaker>
        </customFields>
    </lead>
</request>
Response
<?xml version="1.0" encoding="UTF-8"?>
<response>
    <status>2006</status>
    <message>Update lead success.</message>
</response>
syncLead - Error code
syncLead

success: <status>2006</status> <message>Leads synchronization successfull.</message>
error: <status>9018</status> <message>Leads synchronization contain error.</message>
  
Les balises d'erreurs qu'on peut retrouver:

<errors>
<error>at least one lead is required</error>      
<error>9001 - Unable to process lead #$leadnumber, email is empty.</error>
<error>9004 - Lead with email address $emailAddress already exists, please use the updateLead() call.</error>                      
<error>9002 - Email address is invalid for xml lead->email ($emailAddress) </error>             
<error>9006 - Score ($score) must be a valid integer for xml lead->email ($emailAddress) </error>
<error>9007 - DoNotCall ($doNotCall) must be 0 or 1 for xml lead->email ($emailAddress) </error>
<error>9007 - Unsubscribed ($unsubscribed) must be 0 or 1 for xml lead->email ($emailAddress) </error>
<error>9007 - IsCustomer ($isCustomer) must be 0 or 1 for xml lead->email ($emailAddress) </error>          
<error>9007 - isAnonymous ($isAnonymous) must be 0 or 1 for xml lead->email ($emailAddress) </error> 
<error>9007 - emailInvalid ($emailInvalid) must be 0 or 1 for xml lead->email ($emailAddress) </error>
<error>9007 - Suspended ($suspended) must be 0 or 1 for xml lead->email ($emailAddress) </error>
<error>9007 - Blacklisted ($blacklisted) must be 0 or 1 for xml lead->email ($emailAddress) </error>     
<error>9006 - NbrEmployees ($nbrEmployees) must be a valid integer for xml lead->email ($emailAddress) </error>
<error>9006 - Revenue ($revenue) must be a valid integer for xml lead->email ($emailAddress) </error>
<error>9001 - Email is required for xml lead->crmId ($xml->crmLeadId) </error>
<error>9006 - Score ($score) must be a valid integer for xml lead->crmId ($xml->crmLeadId) </error>
<error>9007 - DoNotCall ($doNotCall) must be 0 or 1 for xml lead->crmId ($xml->crmLeadId) </error>           
<error>9007 - Unsubscribed ($unsubscribed) must be 0 or 1 for xml lead->crmId ($xml->crmLeadId) </error>           
<error>9007 - IsCustomer ($isCustomer) must be 0 or 1 for xml lead->crmId ($xml->crmLeadId) </error>              
<error>9007 - isAnonymous ($isAnonymous) must be 0 or 1 for xml lead->crmId ($xml->crmLeadId) </error>              
<error>9007 - emailInvalid ($emailInvalid) must be 0 or 1 for xml lead->crmId ($xml->crmLeadId) </error>           
<error>9007 - Suspended ($suspended) must be 0 or 1 for xml lead->crmId ($xml->crmLeadId) </error>
<error>9007 - Blacklisted ($blacklisted) must be 0 or 1 for xml lead->crmId ($xml->crmLeadId) </error>
<error>9006 - NbrEmployees ($nbrEmployees) must be a valid integer for xml lead->crmId ($xml->crmLeadId) </error>
<error>9006 - Revenue ($revenue) must be a valid integer for xml lead->crmId ($xml->crmLeadId) </error>    
<error>9001 - Email is required for xml (lead no email no crm id)</error>
<error>9006 - Score ($score) must be a valid integer for (lead no email no crm id)</error>
<error>9007 - DoNotCall ($doNotCall) must be 0 or 1 for (lead no email no crm id)</error>
<error>9007 - Unsubscribed ($unsubscribed) must be 0 or 1 for (lead no email no crm id)</error>
<error>9007 - IsCustomer ($isCustomer) must be 0 or 1 for (lead no email no crm id)</error>
<error>9007 - isAnonymous ($isAnonymous) must be 0 or 1 for (lead no email no crm id)</error>            
<error>9007 - emailInvalid ($emailInvalid) must be 0 or 1 for (lead no email no crm id)</error>
<error>9007 - Suspended ($suspended) must be 0 or 1 for (lead no email no crm id)</error>       
<error>9007 - Blacklisted ($blacklisted) must be 0 or 1 for (lead no email no crm id)</error>       
<error>9006 - NbrEmployees ($nbrEmployees) must be a valid integer for (lead no email no crm id)</error>
<error>9006 - Revenue ($revenue) must be a valid integer for (lead no email no crm id)</error>  
</errors>
 


Get View

Retrieve history about one lead based on its email address.


Url

https://app.publitrac.com/api

Supported

GET

Methode

getView

Mandatory Parameters

method : ‘getView’

apiKey : Your API Key

username : Your username

password : Your password

viewName: Filtered list name.

Optional Parameters

page : Page id (default is 1)


Examples

Request
https://app.publitrac.com/api?method=getView&apiKey=abc&username=john&password=pass&viewName=PromoABC_Email_Open&page=1
Response
<?xml version="1.0" encoding="UTF-8"?>
<response>
    <leads>
        <lead>
            <id>470</id>
            <firstName>John</firstName>
            <lastName>Smith</lastName>
            <middleName></middleName>
            <company>PUBLIPAGE</company>
            <phone>514-555-2149</phone>
            <email>johnsmith@publipage.com</email>
            <mailingAddress></mailingAddress>
            <originalSource>Google</originalSource>
            <originalSourceType>Organic Search</originalSourceType>
            <keyword>marketing automation</keyword>
            <jobTitle></jobTitle>
            <dateOfBirth></dateOfBirth>
            <status>Active</status>
            <score>0</score>
            <postalCode></postalCode>
            <country></country>
            <city></city>
            <state></state>
            <doNotCall>0</doNotCall>
            <doNotCallReason></doNotCallReason>
            <token>_nl-publipage.com-1282527313351-84730</token>
            <unsubscribed>0</unsubscribed>
            <unsubscribeCause></unsubscribeCause>
            <fax></fax>
            <mobile></mobile>
            <isCustomer>0</isCustomer>
            <isAnonymous>0</isAnonymous>
            <emailInvalid>0</emailInvalid>
            <emailInvalidCause></emailInvalidCause>
            <notes></notes>
            <suspended>0</suspended>
            <suspendedReason></suspendedReason>
            <blacklisted>0</blacklisted>
            <blacklistedCause></blacklistedCause>
            <customerId></customerId>
            <website></website>
            <language></language>
            <nbrEmployees></nbrEmployees>
            <revenue></revenue>
            <crmLeadId>5e0ff332-090c-b97d-6325-4c786a68e9a7</crmLeadId>
            <createdDate>2010-08-23 01:35:13</createdDate>
            <lastUpdated>2010-10-25 02:20:06</lastUpdated>
            <someCustomField>my custom field</someCustomField>
        </lead>
    </leads>
    <paging>
        <page>1</page>
        <items>1</items>
        <offset>100</offset>
        <total>1</total>
    </paging>
    <status>2001</status>
    <message>Get leads success.</message>
</response>
getView - Error code
getView

success: <status>2001</status> <message>Get view success.</message>
error: <status>9010</status> <message>View $viewName does not exist.</message>
      
Les balises d'erreurs qu'on peut retrouver: aucune



Get List

Retrieve history about one lead based on its email address.


Url

https://app.publitrac.com/api

Supported

GET

Methode

getList

Mandatory Parameters

method : getList

apiKey : Your API Key

username : Your username

password : Your password

listName: List name

Optional Parameters

page : Page id (default is 1)


Examples

Request
https://app.publitrac.com/api?method=getList&apiKey=abc&username=john&password=pass&viewName=Imported2012&page=1
Response
<?xml version="1.0" encoding="UTF-8"?>
<response>
    <leads>
        <lead>
            <id>470</id>
            <firstName>John</firstName>
            <lastName>Smith</lastName>
            <middleName></middleName>
            <company>PUBLIPAGE</company>
            <phone>514-555-2149</phone>
            <email>johnsmith@publipage.com</email>
            <mailingAddress></mailingAddress>
            <originalSource>Google</originalSource>
            <originalSourceType>Organic Search</originalSourceType>
            <keyword>marketing automation</keyword>
            <jobTitle></jobTitle>
            <dateOfBirth></dateOfBirth>
            <status>Active</status>
            <score>0</score>
            <postalCode></postalCode>
            <country></country>
            <city></city>
            <state></state>
            <doNotCall>0</doNotCall>
            <doNotCallReason></doNotCallReason>
            <token>_nl-publipage.com-1282527313351-84730</token>
            <unsubscribed>0</unsubscribed>
            <unsubscribeCause></unsubscribeCause>
            <fax></fax>
            <mobile></mobile>
            <isCustomer>0</isCustomer>
            <isAnonymous>0</isAnonymous>
            <emailInvalid>0</emailInvalid>
            <emailInvalidCause></emailInvalidCause>
            <notes></notes>
            <suspended>0</suspended>
            <suspendedReason></suspendedReason>
            <blacklisted>0</blacklisted>
            <blacklistedCause></blacklistedCause>
            <customerId></customerId>
            <website></website>
            <language></language>
            <nbrEmployees></nbrEmployees>
            <revenue></revenue>
            <crmLeadId>5e0ff332-090c-b97d-6325-4c786a68e9a7</crmLeadId>
            <createdDate>2010-08-23 01:35:13</createdDate>
            <lastUpdated>2010-10-25 02:20:06</lastUpdated>
            <someCustomField>my custom field</someCustomField>
        </lead>
    </leads>
    <paging>
        <page>1</page>
        <items>1</items>
        <offset>100</offset>
        <total>1</total>
    </paging>
    <status>2001</status>
    <message>Get list success.</message>
getList - Error code
getList

success: <status>2001</status> <message>Get list success.</message>
error: <status>9009</status> <message>List does not exist.</message>

Les balises d'erreurs qu'on peut retrouver: aucune


Add leads to list

Retrieve history about one lead based on its email address.


Url

https://app.publitrac.com/api

Supported

POST

Methode

addLeadsToList

Mandatory Parameters

method : addLeadsToList

apiKey : Your API Key

username : Your username

password : Your password

query: The xml representation of the list to add leads to and the list of emails to add to the list.

Optional Parameters


Remarks



Examples

The query object might contain many lead’s email addresses with only one list name. If many leads with the same email addresse exist in the system, only the first

created lead will be associated with the list.


Request
<?xml version="1.0" encoding="UTF-8"?>
<request>
    <list>
		<name>The name of the list to add to</name>
	</list>
    <leads>
        <lead>
            <email>someone1@publitrac.com</email>
        </lead>
        <lead>
            <email>someone2@publitrac.com</email>
        </lead>
    </leads>
</request>
Success Response
<?xml version="1.0" encoding="UTF-8"?>
<response>
    <status>2009</status>
    <message>Success.</message>
</response>
Failure Response
<?xml version="1.0" encoding="UTF-8"?>
<response>
    <error>
        <leadNotFound>someone1@gmail.com</leadNotFound>
        <leadNotFound>someone2@gmail.com</leadNotFound>
    </error>
    <statuts>9501
        
    </status>
    <message> Leads not found</message>
</response>
addLeadsToList - Error code
addLeadsToList

success: <status>2009</status> <message>Add leads to list success.</message>
error: <status>9013</status> <message>Add Leads To List failed.</message>

Les balises d'erreurs qu'on peut retrouver:

<errors>
<error>9005 - ($emailAddress) Leads not found.</error>
<error>AT least one lead is required</error>
<error>9012 - ($filterListsName) is not a static list</error>
<error>One list is required</error>
</errors>



Add web visit history

Add a web visit to lead history.


Url

https://app.publitrac.com/api

Supported

POST

Methode

addWebVisitHistory

Mandatory Parameters

method : addWebVisitHistory

apiKey : Your API Key

username : Your username

password : Your password

email: Lead email

query: Visit Info

Optional Parameters


Remarks

The email must contain 50 characters or less.


Examples


Request
<?xml version="1.0" encoding="UTF-8"?>
<request>
    <webvisitleadhistory>
        <information>/blog</information>
        <context>Blog viewed</context>
        <url>http://www.acme.com/blog</url>
        <query>blog_post=product_abc_launch</query>
        <referral>http://www.linkedin.com/home.php?udi=1</referral>
        <ip>71.23.75.32</ip>
        <userAgent>Mozilla/5.0 (Windows; U; Windows NT 6.1; es-ES; rv:1.9.1.16) Gecko/20101130 Firefox/3.5.16</userAgent>
        <sessionId>2192c0f3802f8e0744e9940788121624</sessionId>
    </webvisitleadhistory>
</request>
Response
<?xml version="1.0" encoding="UTF-8"?>
<response>
    <status>3002</status>
    <message>Add web page history success.</message>
</response>


Add click link history

Add a click link to lead history.


Url

https://app.publitrac.com/api

Supported

POST

Method

addClickLinkHistory

Mandatory Parameters

method : addClickLinkHistory

apiKey : Your API Key

username : Your username

password : Your password

email: Lead email

query: Click info

Optional Parameters


Remarks

The email must contain 50 characters or less


Examples

Request
<?xml version="1.0" encoding="UTF-8"?>
<request>
    <webvisitleadhistory>
        <information>/blog</information>
        <context>Blog viewed</context>
        <url>http://www.acme.com/blog</url>
        <query>blog_post=product_abc_launch</query>
        <referral>http://www.linkedin.com/home.php?udi=1</referral>
        <ip>71.23.75.32</ip>
        <userAgent>Mozilla/5.0 (Windows; U; Windows NT 6.1; es-ES; rv:1.9.1.16) Gecko/20101130 Firefox/3.5.16</userAgent>
        <sessionId>2192c0f3802f8e0744e9940788121624</sessionId>
    </webvisitleadhistory>
</request>
Response
<?xml version="1.0" encoding="UTF-8"?>
<response>
    <status>3003</status>
    <message>Add click link history success.</message>
</response>


Add fill out form history

Add a fill out form to lead history.


Url

https://app.publitrac.com/api

Supported

POST

Methode

addFillFormHistory

Mandatory Parameters

method : addFillFormHistory

apiKey : Your API Key

username : Your username

password : Your password

email: Lead email

query: form info

Optional Parameters


Remarks

Le nom du formulaire (formName) doit être un formulaire valide dans PUBLITRAC.

The email must contain 50 characters or less



Examples

Request
<?xml version="1.0" encoding=" UTF-8"?>
<request>
    <fillformleadhistory>
        <information>Registration Form</information>
        <context></context>
        <formName>Infolettre</formName>
        <url>/infolettre.php</url>
        <values>
            <![CDATA[

Firstname: Claude

Lastname: Sage

Email: claude@sage.com

Phone: 555-666-7777

]]>
        </values>
        <sessionId>2192c0f3802f8e0744e9940788121624</sessionId>
    </fillformleadhistory>
</request>
Response
<?xml version="1.0" encoding="UTF-8"?>
<response>
    <status>3004</status>
    <message>Add fill form history success.</message>
</response>

Get campaigns

Retrieve all tracking campaigns.


Url

https://app.publitrac.com/api

Supported

GET

Methode

getCampaigns

Mandatory Parameters

method : getCampaigns

apiKey : Your API Key

username : Your username

password : Your password

Optional Parameters

page: page : Page id (default is 1)

Remarks




Examples

Request
https://app.publitrac.com/api?method=getCampaigns&apiKey=abc&username=john&password=pass&page=1
Response
<?xml version="1.0" encoding="UTF-8"?>
<response>
    <campaign>
        <id>2071</id>
        <Name>AdCenter - Drip Marketing</Name>
        <Type>Paid Search</Type>
        <Token>CMP-4d7147b0dd389</Token>
        <CampaignType>CAMPAIGNTRACKING</CampaignType>
        <Created_Date>2011-03-04 20:12:32</Created_Date>
        <Last_Updated>2011-12-08 01:10:14</Last_Updated>
    </campaign>
    <campaign>
        <id>2211</id>
        <Name>AdCenter - Internet Marketing Software</Name>
        <Type>Paid Search</Type>
        <Token>CMP-4dc2ebfe7a3f2</Token>
        <CampaignType>CAMPAIGNTRACKING</CampaignType>
        <Created_Date>2011-05-05 18:27:10</Created_Date>
        <Last_Updated>2011-12-08 01:10:14</Last_Updated>
    </campaign>
</response>


Get opportunities

Retrieve all opportunities.


Url

https://app.publitrac.com/api

Supported

GET

Methode

getOpportunities

Mandatory Parameters

method : getOpportunities

apiKey : Your API Key

username : Your username

password : Your password

Optional Parameters

page: page : Page id (default is 1)

Remarks



Examples

Request
https://app.publitrac.com/api?method=getOpportunities&apiKey=abc&username=john&password=pass&page=1
Response
<?xml version="1.0" encoding="UTF-8"?>
<response>
    <opportunities>
        <opportunity>
            <id>1</id>
            <Name>PUBLITRAC</Name>
            <Description>Marketing Automation Solution</Description>
            <Opportunity_Type>Web</Opportunity_Type>
            <Account_Name>PUBLITRAC</Account_Name>
            <Campaign_Name>Marketing Automation</Campaign_Name>
            <Lead_Source></Lead_Source>
            <Amount>9000</Amount>
            <Date_Closed>2010-10-10</Date_Closed>
            <Sales_Stage>Closed Won</Sales_Stage>
            <Probability>100</Probability>
            <External_id>My ID</External_id>
            <Account>1</Account>
            <Created_Date>0000-00-00 00:00:00</Created_Date>
            <Last_Updated>0000-00-00 00:00:00</Last_Updated>
        </opportunity>
    </opportunities>
    <paging>
        <page>1
            </page>
        <items>1</items>
        <offset>200</offset>
        <total>1</total>
    </paging>
    <status>5001</status>
    <message>Get opportunities success.</message>
</response>

Sync opportunity

Insert a new opportunity.


Url

https://app.publitrac.com/api

Supported

POST

Methode

syncOpportunity

Mandatory Parameters

method : syncOpportunity

apiKey : Your API Key

username : Your username

password : Your password

query: The xml representation of an opportunity (more explanation at the end of this document)

Optional Parameters


Remarks

If the opportunity does not exist by id, it will be created.


The leadId must be the External ID of the lead.



Examples

Request
<?xml version="1.0" encoding=" UTF-8"?>
<request>
    <opportunity>
        <id>Product ABC</id>
        <name>Promotion Product ABC</name>
        <description>Product ABC is a revolutionary…</description>
        <type>New Business</type>
        <accountName>XYZ Solutions</accountName>
        <salesStage>Closed Won</salesStage>
        <campaignName>LinkedIn</campaignName>
        <leadSource>Web</leadSource>
        <amount>100000</amount>
        <dateClosed>20/08/2012</dateClosed>
        <probability>100</probability>
        <leads>
            <leadId>ae555ecc-e998-85b9-4c9f-4c8d13581a9b</leadId>
        </leads>
    </opportunity>
</request>
Response
<?xml version="1.0" encoding="UTF-8"?>
<response>
    <status>5002</status>
    <message>Opportunity synchronized.</message>
</response>

Execute campaigns on leads

Insert leads into automated campaigns.


Url

https://app.publitrac.com/api

Supported

POST

Methode

executeCampaign

Mandatory Parameters

method : executeCampaign

apiKey : Your API Key

username : Your username

password : Your password

query: The xml representation of the lead emails and campaign name.

Optional Parameters


Remarks

The query object might contain many lead email addresses and many campaign names.

If many leads with the same email addresses exist in the system, only the first lead created will be sent to the campaigns.

Please note that all leads will be inserted into all campaigns defined and if one lead or one campaign does not exist, nothing will be processed.


Examples

Request
<?xml version="1.0" encoding="UTF-8"?>
<request>
    <leads>
        <lead></lead>
        <lead></lead>
    </leads>
    <campaigns>
        <email>johnsmith@acme.com</email>
        <email>csage@ acme.com</email>
        <campaign>
            <name>Trade Show May</name>
        </campaign>
    </campaigns>
</request>
Response
<?xml version="1.0" encoding="UTF-8"?>
<response>
    <status>1100</status>
    <message>Execute campaigns on leads success.</message>
</response>

Add emails campaign

Create a complete email marketing campaign.

This method will automatically create an email, a list and a campaign.  The leads will be added to the automation campaign and they will receive the email.  If the campaign already exists, it will add the new leads to the campaign. 


Url

https://app.publitrac.com/api

Supported

POST

Methode

addEmailCampaign

Mandatory Parameters

method : addEmailCampaign

apiKey : Your API Key

username : Your username

password : Your password

query: The xml representation of the email information, and a list of leads.

Optional Parameters


Remarks

A maximum of 50 leads per call can be provided.


Examples

Request
?xml version="1.0" encoding="UTF-8"?>
<request>
    <information>
        <name>Promotion January 2014</name>
    </information>
    <email>
        <fromName>PUBLITRAC</fromName>
        <fromEmail>no-reply@publipage.com</fromEmail>
        <subject>January Promotion</subject>
        <message>
            <html>
                <![CDATA[


<html><body>

Hello <strong>{{FirstName;Default=}}</strong>.<br /><br />

There is a new promotion this year…<br /><br /><br /></body></html>


]]>
            </html>
            <text>
                <![CDATA[


Hello {{FirstName;Default=}}.


There is a new promotion this year…


            ]]>
            </text>
        </message>
        <options>
            <sendAsSalesRep>false</sendAsSalesRep>
        </options>
    </email>
    <leads>
        <lead>
            <firstName>John</firstName>
            <lastName>Smith</lastName>
            <company>ACME</company>
            <phone>555-423-2453</phone>
            <email>jsmith@acme.com</email>
            <leadSource>New Production ABC</leadSource>
            <originalSource> New Production ABC</originalSource>
            <originalSourceType>Web</originalSourceType>
            <customFields>
                <GamePreferences>Action
                </Buyin>
                <GamePlayed>121
                </Buyin>
            </customFields>
        </lead>
        <lead>
            <firstName>John</firstName>
            <lastName>Carmack</lastName>
            <company>ID Software</company>
            <phone>555-423-2453</phone>
            <email>jcarmack@idsoftware.ca</email>
            <leadSource>New Production ABC</leadSource>
            <originalSource> New Production ABC</originalSource>
            <originalSourceType>Web</originalSourceType>
            <customFields>
                <GamePreferences>Strategy
                </Buyin>
                <GamePlayed>23
                </Buyin>
            </customFields>
        </lead>
    </leads>
</request>
Response
<?xml version="1.0" encoding="UTF-8"?>
<response>
          <status>2001</status>
          <message>Lead emails synchronization successfull.</message>
</response>

E-Commerce Transactions

Create an e-commerce transaction. 

Synchronise the sales history of your leads automatically from your web site. Each transaction data and each product will be kept in time and can be updated as they evolve.

The sales history will be usable as:

  • Create segmented list
  • Activity on transactions information within automated campaigns 
  • Automated campaigns on transaction status and information


Url

https://app.publitrac.com/tracking/ecommerce

Supported

POST

Body Parameters (required)

transaction : json representation of the transaction

token : Your account token

email: yourLeadEmail@service.com

Optional Parameters


Remarks

the transaction object has several required fields, refer to example transaction content to build your JSON object

Examples

transaction content
{
  "id": "1000",
  "token": "accountToken",
  "email": "yourleademail@service.com",
  "type": "buying",
  "total": "40",
  "tax": "12",
  "shipping": "air",
  "info": "my first transaction",
  "currency": "EUR",
  "items": [
    {
      "id": "9991",
      "name": "Bunnies",
      "sku": "DD23444",
      "category": "Animals",
      "price": "10",
      "quantity": "1"
    },
    {
      "id": "9992",
      "name": "Ball",
      "sku": "CC23444",
      "category": "Party Toys",
      "price": "10",
      "quantity": "1"
    },
    {
      "id": "9993",
      "name": "Hammer",
      "sku": "BB23444",
      "category": "Tools",
      "price": "10",
      "quantity": "1"
    },
    {
      "id": "9994",
      "name": "Pencils",
      "sku": "AA23444",
      "category": "Arts",
      "price": "10",
      "quantity": "1"
    }
  ]
}
Response
200 OK

Annex

Country List


The country list is ISO_3166-1 in alpha-2 code


Language

The language is ISO_639-1 (currently supported only en/fr)


Opportunity Objet


Mandatory fields:

  • Id: Your system ID to identify the opportunity.
  • Name: The name of the opportunity.
  • Sales Stages:
    • Prospecting
    • Qualification
    • Needs Analysis
    • Value Proposition
    • Id. Decision Makers
    • Perception Analysis
    • Proposal/Price Quote
    • Negotiation/Review
    • Closed Won
    • Closed Lost
  • Amount: Integer
  • Date Closed: Mandatory if opportunity is closed. Use your own data format.
  • Probability: Integer from 1 to 100
  • Leads: List of lead ids attached to the opportunity. ID is your internal crmLeadId and must have been previously added using addLead method.


Examples

<?xml version="1.0" encoding="UTF-8"?>
<request>
    <opportunity>
        <id>1234abc</id>
        <name>PUBLITRAC</name>
        <description>Marketing Automation Solution</description>
        <type>Web</type>
        <accountName>PUBLITRAC</accountName>
        <salesStage>Closed Won</salesStage>
        <campaignName>Webinar</campaignName>
        <leadSource>Web</leadSource>
        <amount>9000</amount>
        <dateClosed>2010-10-10</dateClosed>
        <probability>100</probability>
        <leads>
            <leadId>456zxy</leadId>
        </leads>
    </opportunity>
</request>

Errors codes


Constantes
ERROR_EMAIL_IS_REQUIRED = 9001
ERROR_EMAIL_IS_INVALID = 9002
ERROR_EXTERNAL_ID_NOT_DEFINED = 9003
ERROR_LEAD_ALREADY_EXISTS = 9004
ERROR_LEAD_DOES_NOT_EXISTS = 9005
ERROR_LEAD_DOES_NOT_HAVE_ORIGINAL_SOURCE = 9006
ERROR_LEAD_DOES_NOT_HAVE_ORIGINAL_SOURCE_TYPE = 9007
ERROR_LEAD_UNSUPPORTED_CUSTOM_TAG = 9008
ERROR_LIST_DOES_NOT_EXISTS = 9009
ERROR_VIEW_DOES_NOT_EXISTS = 9010
ERROR_INVALID_XML = 9011
ERROR_LIST_INSIDE_FILTER_LIST = 9012
ERROR_ADD_LEAD_TO_LIST = 9013
ERROR_REMOVE_LEAD_FROM_LIST = 9014
ERROR_GET_LEAD = 9015
ERROR_ADD_LEAD = 9016
ERROR_UPDATE_LEAD = 9017
ERROR_SYNC_LEAD = 9018
STATUS_GET_LEADS = 2001
STATUS_GET_LEAD = 2002
STATUS_ADD_LEAD  = 2003
STATUS_UPDATE_LEAD = 2004
STATUS_DELETE_LEAD = 2005
STATUS_SYNC_LEAD = 2006
STATUS_ADD_LEAD_TO_LIST = 2009
STATUS_REMOVE_LEAD_FROM_LIST = 2008
STATUS_ADD_LEADS_TO_LIST = 2009
removeLeadFromList - Error code
removeLeadFromList

success: <status>2008</status> <message>Remove lead from list success.</message>
error: <status>9014</status> <message>Remove lead from list failed.</message>

Les balises d'erreurs qu'on peut retrouver:

<errors>
<error>9009 - List name is required</error>
<error>9009 - List does not exist.</error>
<error>9005 - Lead email address is required</error>
<error>9005 - Lead does not exist.</error>
</errors>
addLeadToList - Error code
addLeadToList
success:  <status>2009</status> <message>Add lead to list success.</message>
error: <status>9013</status> <message>Add lead to list failed.</message>
        
Les balises d'erreurs qu'on peut retrouver:
<errors>
	<error>9009 - List ($listName) does not exist.</error>                
	<error>9012 - You are trying to insert a lead inside a filtered list, this operation is only permitted on static lists.</error>
	<error>9005 - Lead ($emailAddress) does not exist.</error>
</errors>
getLeadByTokenId - Error code
getLeadByTokenId
success: 
<status>2002</status> <message>getLeadByTokenId success.</message>
error: <status>9015</status><message>getLeadByTokenId failed.</message>

Les balises d'erreurs qu'on peut retrouver:

<errors>
<error>Tok Id is required</error>
<error>Tok Id is invalid</error>
<error>9005 - lead not found</error>
</errors> 
updateLead - Error code
updateLead

success: <status>2004</status> <message>Leads updated successfully.</message>
error: <status>9017</status> <message>Update Lead contain error</message>

Les balises d'erreurs qu'on peut retrouver:  


<errors>
<error>9006 - Score ($score) must be a valid integer for xml lead->email ($emailAddress) </error>
<error>9007 - DoNotCall ($doNotCall) must be 0 or 1 for xml lead->email ($emailAddress) </error>              
<error>9007 - Unsubscribed ($unsubscribed) must be 0 or 1 for xml lead->email ($emailAddress) </error>
<error>9007 - IsCustomer ($isCustomer) must be 0 or 1 for xml lead->email ($emailAddress) </error>    

<error>9007 - isAnonymous ($isAnonymous) must be 0 or 1 for xml lead->email ($emailAddress) </error>            
<error>9007 - emailInvalid ($emailInvalid) must be 0 or 1 for xml lead->email ($emailAddress) </error>              
<error>9007 - Suspended ($suspended) must be 0 or 1 for xml lead->email ($emailAddress) </error>       
<error>9007 - Blacklisted ($blacklisted) must be 0 or 1 for xml lead->email ($emailAddress) </error>   
<error>9006 - NbrEmployees ($nbrEmployees) must be a valid integer for xml lead->email ($emailAddress) </error>    
<error>9006 - Revenue ($revenue) must be a valid integer for xml lead->email ($emailAddress) </error> 
</errors>
addLead - Error code
addLead

success: <status>2003</status> <message>Create new lead success.</message>
error: <status>9016</status> <message>Create new lead have errors.</message>
        
Les balises d'erreurs qu'on peut retrouver:

<errors>
<error>lead is required</error>
<error>$result['validate'] lead $emailAddress was not created</error>
<error>9004 - Lead with email address $emailAddress already exists, please use the updateLead() call.</error>         
<error>9002 - Email address is invalid for xml lead->email ($emailAddress) </error>
<error>9006 - Score ($score) must be a valid integer for xml lead->email ($emailAddress) </error>
<error>9007 - DoNotCall ($doNotCall) must be 0 or 1 for xml lead->email ($emailAddress) </error>
<error>9007 - Unsubscribed ($unsubscribed) must be 0 or 1 for xml lead->email ($emailAddress) </error>
<error>9007 - IsCustomer ($isCustomer) must be 0 or 1 for xml lead->email ($emailAddress) </error>
<error>9007 - isAnonymous ($isAnonymous) must be 0 or 1 for xml lead->email ($emailAddress) </error>
<error>9007 - emailInvalid ($emailInvalid) must be 0 or 1 for xml lead->email ($emailAddress) </error>
<error>9007 - Suspended ($suspended) must be 0 or 1 for xml lead->email ($emailAddress) </error>
<error>9007 - Blacklisted ($blacklisted) must be 0 or 1 for xml lead->email ($emailAddress) </error>
<error>9006 - NbrEmployees ($nbrEmployees) must be a valid integer for xml lead->email ($emailAddress) </error>
<error>9006 - Revenue ($revenue) must be a valid integer for xml lead->email ($emailAddress) </error>
<error>9001 - Email is required for xml lead->crmId ($xml->crmLeadId) </error>
<error>9006 - Score ($score) must be a valid integer for xml lead->crmId ($xml->crmLeadId) </error>
<error>9007 - DoNotCall ($doNotCall) must be 0 or 1 for xml lead->crmId ($xml->crmLeadId) </error> 
<error>9007 - Unsubscribed ($unsubscribed) must be 0 or 1 for xml lead->crmId ($xml->crmLeadId) </error>
<error>9007 - IsCustomer ($isCustomer) must be 0 or 1 for xml lead->crmId ($xml->crmLeadId) </error>
<error>9007 - isAnonymous ($isAnonymous) must be 0 or 1 for xml lead->crmId ($xml->crmLeadId) </error>
<error>9007 - emailInvalid ($emailInvalid) must be 0 or 1 for xml lead->crmId ($xml->crmLeadId) </error>
<error>9007 - Suspended ($suspended) must be 0 or 1 for xml lead->crmId ($xml->crmLeadId) </error>
<error>9007 - Blacklisted ($blacklisted) must be 0 or 1 for xml lead->crmId ($xml->crmLeadId) </error>
<error>9006 - NbrEmployees ($nbrEmployees) must be a valid integer for xml lead->crmId ($xml->crmLeadId) </error>
<error>9006 - Revenue ($revenue) must be a valid integer for xml lead->crmId ($xml->crmLeadId) </error>
<error>9001 - Email is required for xml (lead no email no crm id)</error>
<error>9006 - Score ($score) must be a valid integer for (lead no email no crm id)</error>
<error>9007 - DoNotCall ($doNotCall) must be 0 or 1 for (lead no email no crm id)</error>
<error>9007 - Unsubscribed ($unsubscribed) must be 0 or 1 for (lead no email no crm id)</error>
<error>9007 - IsCustomer ($isCustomer) must be 0 or 1 for (lead no email no crm id)</error>
<error>9007 - isAnonymous ($isAnonymous) must be 0 or 1 for (lead no email no crm id)</error>
<error>9007 - emailInvalid ($emailInvalid) must be 0 or 1 for (lead no email no crm id)</error>
<error>9007 - Suspended ($suspended) must be 0 or 1 for (lead no email no crm id)</error>
<error>9007 - Blacklisted ($blacklisted) must be 0 or 1 for (lead no email no crm id)</error>
<error>9006 -NbrEmployees ($nbrEmployees) must be a valid integer for (lead no email no crm id)</error>
<error>9006 -Revenue ($revenue) must be a valid integer for (lead no email no crm id)</error>      
</errors>