API documentation

Transcription

API documentation

SALESmanago
Technical API Documentation
Version: 1.43
Last modification: 6 December 2014
Modified by: Konrad Pawlus
General information..............................................................................................................................3
Monitoring code integration................................................................................................................. 3
Adding a contact and monitoring......................................................................................................... 4
Adding a new contact or modifying the existing contact................................................................ 4
Adding a new contact...................................................................................................................... 6
Sending additional monitoring data................................................................................................. 7
Modifying an existing contact......................................................................................................... 8
Adding many contacts simultaneously............................................................................................ 9
Deleting a contact.......................................................................................................................... 10
Checking if a contact is already recorded...................................................................................... 10
Managing discount coupons............................................................................................................... 10
Użycie kuponu dla kontaktu.......................................................................................................... 10
Managing mailing list (Opt-in / Opt-out)........................................................................................... 11
Unsubscribing a contact from the list (Opt-out)............................................................................ 11
Adding a contact to the list (Opt-in).............................................................................................. 11
Mass unsubscribing contacts from the list (Opt-out).....................................................................12
Adding mass contacts to the list (Opt-in)...................................................................................... 13
Unsubscribing a contact from the phone list (Opt-out phone).......................................................13
Adding a contact to the phone list (Opt-in phone).........................................................................14
Paged contact list........................................................................................................................... 15
Contact list import.............................................................................................................................. 16
Import based on email address.......................................................................................................16
Import based on contact's ID......................................................................................................... 20
Importing the list of recently modified contacts.................................................................................21
Contacts' activity................................................................................................................................ 22
External events................................................................................................................................... 24
Adding an external event............................................................................................................... 24
Modifying events........................................................................................................................... 25
Removing an event........................................................................................................................ 26
Integration of external events, like basket..................................................................................... 27
Import of tag list................................................................................................................................. 27
Monitoring AJAX/JavaScript events.................................................................................................. 28
Editing contact's tag list......................................................................................................................28
Sending email..................................................................................................................................... 29
Contacts' tasks.................................................................................................................................... 31
Adding automation rules.................................................................................................................... 32
Temporary authorization.....................................................................................................................34
Account registration (partners only)...................................................................................................34
NextGen e-Commerce code implementation..................................................................................... 35
General information
Each API call, except for authentication, has to include authentication data:
"clientId":"your-client-id-123",
"apiKey":"your-api-key-123",
"requestTime":1327056031488,
"sha":"2aa3927a7dee8c2a712adb5375f5fa36dd8fe00c",
Values of clientId can be found under the "Integration" bookmark in the "Settings" menu.
The apiKey value is a random string used for authentication.
The sha value is generated using the SHA-1 algorithm from a string created from the
combination: apiKey + clientId + apiSecret. ApiSecret is located on the above
mentioned "Integration” bookmark.
requestTime is a timestamp when the call is made.
All requests must be sent at: http://www.salesmanago.pl/api
eg. http://xyz.salesmanago.pl/api/contact/upsert
Where xyz is your server's ID (www or app1, app2, app3...)
Important:
The following headers should be included in the request:
Accept: application/json, application/json
Content-Type: application/json;charset=UTF-8
Each request is sent using the HTTP POST method. If the HTTP GET method should be
used, it is clearly stated in the user's manual for each method.
*
The obligatory fields in the documentation are marked with an .
Monitoring code integration
Once our account has been activated, we get access to the code monitoring our website.
We will find the code on the main page, visible after logging in (until SALESmanago
detects the code on our website), or under "Settings">"Integration" menu.
Script [1] should be added to each page of our website, just before the end of the "body"
section. It is best if there is the possibility to download this script into the template of our
website, so that the code is in one place and it is identically printed on all pages.
For example, the script in CMS Wordpress can be downloaded into the "footer.php" file.
Here is an example:
Adding a contact and monitoring
Adding a new contact or modifying the existing contact
The contact is added by calling the method:
http://www.salesmanago.pl/api/contact/upsert
An example of request data structure:
{
"apiKey" : "your-api-key-123",
"clientId" : "your-client-id-123",
"contact" : { "company" : "Benhauer Sp. z o.o. Sp. K.",
"email" : "[email protected]",
"fax" : "+48345543345",
"name" : "Konrad Test",
"phone" : "+48123321123",
"state" : "PROSPECT",
"address":{
"streetAddress":"Brzyczyńska 123",
"zipCode":"43-305",
"city":"Bielsko-Biała",
"country":"PL"
}
},
"owner" : "[email protected]",
"newEmail" : "",
"forceOptIn" : true,
"forceOptOut" : false,
"forcePhoneOptIn" : true,
"forcePhoneOptOut" : false,
"requestTime" : 1327059355361,
"sha" : "08924f45afc2e4fb8b652c53cdb493c7ddb846a1",
"tags" : [ "API",
"ADmanago"
],
"removeTags" : [ "Test_tag",
"New"
],
"properties":{"custom.nickname":"Konri","custom.sex":"M"},
"birthday": "19801017",
"province": "Wielkopolskie",
"useApiDoubleOptIn":true,
"apiDoubleOptInEmailTemplateId":null,
"apiDoubleOptInEmailAccountId":null,
"apiDoubleOptInEmailSubject":null,
"lang":"PL",
}
Basic elements that can be provided by adding a new contact in the structure include:
name – contact name
*
email – contact email
phone – phone number
fax – fax number
company – contact company
state – contact's state (CUSTOMER, PROSPECT, PARTNER, OTHER, UNKNOWN)
birthday – date of birth, sent as a string of signs in the form: yyyyMMdd or Mmdd
(yyyy – a 4-digit year, MM – a two-digit month, dd – a two-digit day)
province – voivodship,
useApiDoubleOptIn – true value forces using a double-opt-in message,
apiDoubleOptInEmailTemplateId – optional ID of template for double-opt-in,
apiDoubleOptInEmailAccountId – optional ID of e-mail account for double-optin,
apiDoubleOptInEmailSubject – optional message topic for double-opt-in,
lang – language of double-opt-in messages,
address – contact's address
streetAddress – street and house number
zipCode – zip code
city – town/city
country – country
additionally the request should be supplemented with the information about contact's
owner (account the contact will be attributed to):
owner – contact's owner (SALESmanago user account email)
*
Optionally we can change the contact's e-mail address. The field newEmail The newEmail
field should then be filled in:
newEmail – new email address (if we want to modify it)
We can also force the so-called opt-in/opt-out of the contact. We must then fill in the
forceOptIn field:
forceOptOut – forcing opt-out after adding/modification
forceOptIn – forcing opt-in after adding/modification (if the previous option has
not been chosen)
forcePhoneOptOut – forcing opt-out from a phone after adding/modification
forcePhoneOptIn – forcing opt-in to a phone after adding/modification (if the
previous option has not been chosen)
In the request it is possible to mark a contact with tags and remove the existing tags. Tags
are sent as an array of text strings in the tags field
tags – array of contact's tags
removeTags – array of tags to be removed
It is also possible to attribute any number of fields defined by the user to a contact. We
send them through a map:
properties – contact attributes defined by the user. It is advised not to use Polish
signs and spaces in the name, but it is allowed.
*
required fields.
The result of a request is returned as a JSON structure:
{
}
"contactId" : "21c252a6-6de0-436b-bae8-9d0142363266",
"message" : [ ],
"success" : true
where:
success – truth value informing about request results (successful/ not successful)
contactId – unique ID of an updated or recently added contact
message – array of additional information making it possible to identify an error
Adding a new contact
We add a contact by calling the method: http://www.salesmanago.pl/api/contact/insert
This method does not update an existing contact.
An example of a structure of request data:
{
"fax" : "+48345543345",
"phone" : "+48123321123",
"address":{
"zipCode":"43-305",
"country":"PL"
}
},
"newEmail" : "",
"requestTime" : 1327059355361,
"tags" : [ "API",
"ADmanago"
],
"birthday": "19801017",
"useApiDoubleOptIn":true,
"lang":"PL"
}
Basic elements that can be provided when adding a new contact are identical with the
upsert method, with the exception of the lack of fields: forceOptIn, forcePhoneOptIn and
removeTags.
Request result is returned as JSON structure:
{
"message" : [ ],
"success" : true
}
where:
success – truth value informing about the result of request (successful/not
successful)
contactId – is a unique ID of an updated or recently added contact
message – array of additional information enabling error identification
Sending additional monitoring data
In response to a /contact/upsert call we receive a unique ID.
In order to make monitoring of users' behavior on the website more efficient, we must
submit this parameter to at least one subpage visited by the user – eg. after logging in –
at the moment of logging in we make a request /contact/upsert and the returned
contactId value is printed with the JavaScript code of the SALESmanago monitoring
system.
Sample code with a marked contactId value:
<script type="text/javascript">
var _smid = "your-client-id-123";
var _smclientid = "contactIdFromResponse-123";
</script>
<script src="http://www.salesmanago.pl/static/sm.js"
type="text/javascript"></script>
Alternatively, by sending the form by AJAX, it is possible to record only the cookie:
$.ajax({
type:'POST',
url:'/account/registerDemoVideo.htm',
data:$("#registerForm").serialize(),
cache:false,
timeout:240000,
success:function (data) {
if (data == 'Wrong_Email') {
alert('Podany email nie jest prawidłowy. Proszę wpisać
ponownie.');
$("#email").focus();
} else {
createCookie('smclient', data, 365 * 10);
$(".registeredInfo").show();
}
},
error:function (data) {
alert("Błąd – nie udało się zarejestrować");
}});
Modifying an existing contact
We modify a contact by calling a method: http://www.salesmanago.pl/api/contact/update
Sample structure of request data:
{
}
"contactId" : null,
"fax" : "+48345543345",
"phone" : "+48123321123",
"address":{
"zipCode":"43-305",
"country":"PL"
}
},
"requestTime" : 1327059355361,
"tags" : [ "API", "ADmanago"],
"removeTags" : [ "Test_tag", "New"],
"birthday": "1017"
Request data are identical with the upsert method described above. A contact is identified
by email or contactId (returned when adding a contact).
Adding many contacts simultaneously
We add many contacts at the same time using the
http://www.salesmanago.pl/api/contact/batchupsert method call.
{
]}
"requestTime":1348046897664,
"sha":"8d893f41dd479bb0489686f04b0a169005d22559",
"owner":"[email protected]",
"upsertDetails":[
{
"contact":{
"email":"[email protected]",
"name":"Konrad Test1",
"phone":"+48123321123",
"fax":"+48345543345",
"company":"Benhauer Sp. z o.o. Sp. K.",
"externalId":null,
"address":{
"zipCode":"43-305",
"country":"PL"
}
},
"tags":["API", "ADmanago"],
"removeTags":["Test_tag", "New"],
"properties":{
"custom.nickname":"Konri1",
"custom.sex":"M"
},
"birthday": "19801017"
},
{
"contact":{
"email":null,
"name":"Konrad Test2",
"phone":"+48123321123",
"fax":"+48345543345",
"company":"Benhauer Sp. z o.o. Sp. K.",
"externalId":null
},
"newEmail":"[email protected]",
"tags":["API", "ADmanago"],
"properties":{
"custom.nickname":"Konri2",
"custom.sex":"M"
}
}
In the request we provide an array of contacts in the upsertDetails field. Basic elements
that can be provided in contact array element can be found above in the description of the
upsert method (see Adding a contact).
In response we get a request status and, if it is successful, a list of IDs for added contacts.
{
"success":true,
"message":[],
"contactIds":{
"[email protected]":"b257d328-2a95-41ce-915a-94b4274e6c29",
"[email protected]":"bf4d6c03-1ca2-4b3f-8131-c28829236b02"
}}
Deleting a contact
We delete a contact using http://www.salesmanago.pl/api/contact/delete method.
Sample request data structure:
{
"permanently": true/false
}
A contact can be permanently deleted or only marked as deleted. To do this we set a field:
ustawiamy pole - co to znaczy?? albo 'set field value' albo 'select the field'
permanently – defines if a contact is to be fully deleted or only marked as deleted
Checking if a contact is already recorded
To check if a contact is already recorded in the database we use the
http://www.salesmanago.pl/api/contact/hasContact method
{
"owner" : "[email protected]"
}
A true/false status is returned that informs about contact record and if the contact already
exists, its ID is additionally returned.
Managing discount coupons
Redemption of cuppon for contact
You can redeem coupon via API method call:
http://www.salesmanago.pl/api/contact/useContactCoupon
{
"coupon" : "SAMPLE-COUPON-123"
}
Result of method call is used/error depending on success or failure of given call.
Managing mailing list (Opt-in / Opt-out)
Unsubscribing a contact from the list (Opt-out)
We unsubscribe a contact from the mailing list using the
http://www.salesmanago.pl/api/contact/optout method.
{
"requestTime" : 1329128188409,
"sha" : "02bfe70541d3907cf487f26dc2665b184b1221a7",
"email" : "[email protected]"
}
Basic elements that need to be provided when adding a new contact in the structure are:
email – contact's email
*
The result is returned as JSON structure:
{
"message" : [ ],
"success" : true
}
where:
successful)
contactId – unique ID of an updated contact
Adding a contact to the list (Opt-in)
We add a contact to the mailing list using the
http://www.salesmanago.pl/api/contact/optin method.
{
"requestTime" : 1329128188409,
}
*
Request result is returned as JSON structure::
{
}
"message" : [ ],
"success" : true
where:
successful)
Mass unsubscribing contacts from the list (Opt-out)
We unsubscribe mass contacts from the mailing list using the
http://www.salesmanago.pl/api/contact/batchoptout method.
{
"requestTime" : 1329128188409,
"emails" : [
"[email protected]", [email protected]"
]
}
emails – contact emails
*
In response we get the request status and, if it is successful, the list of IDs for
unsubscribed contacts.
{
}}
"success":true,
"message":[],
"contactIds": {
where:
successful)
contactIds – unique IDs of updated contacts
Adding mass contacts to the list (Opt-in)
We add mass contacts to the mailing list by using the
http://www.salesmanago.pl/api/contact/batchoptin method.
{
"requestTime" : 1329128188409,
"emails" : [
"[email protected]", [email protected]"
]
}
emails – contact emails
*
In response we get the request status and, if it is successful, the list of IDs for subscribed
contacts.
{
"success":true,
"message":[],
"contactIds":{
}}
where:
successful)
contactIds – unique IDs of updated contacts
Unsubscribing a contact from the phone list (Opt-out phone)
We unsubscribe a contact from the list using the
http://www.salesmanago.pl/api/contact/phoneoptout method.
{
}
"requestTime" : 1329128188409,
*
{
}
"message" : [ ],
"success" : true
where:
successful)
Adding a contact to the phone list (Opt-in phone)
We add a contact by using the http://www.salesmanago.pl/api/contact/phoneoptin
method.
{
"requestTime" : 1329128188409,
}
*
{
"message" : [ ],
"success" : true
}
where:
successful)
Paged contact list
The request returns a paged contact list. We use the
http://www.salesmanago.pl/api/contact/paginatedContactList method.
{
"requestTime":1416312438,
"sha":"61626d902e12b7f29314862d79288d4a0b2c8481",
"page":0,
"size":10
}
Basic elements that need to be provided when importing the contact list:
*
owner – email address of contact owner .
page – current page (begins with 0)
size – the number of returned lines (up to 1000)
{
"success":true,
"message":[],
"contacts":[
{
"id":"420a5ec8-26e7-409d-848a-c57655348aae",
"name":"Test",
"phone":null,
"fax":null,
"score":0,
"state":"PROSPECT",
"optedOut":false,
"optedOutPhone":false,
"deleted":false,
"invalid":false,
"company":null,
"externalId":null,
"address":
{
"streetAddress":"Test",
"zipCode":"",
"city":"",
"country":""
},
"contactVisits":[],
"contactTags":[],
"contactEvents":[],
"emailMessages":[],
"properties":[],
"contactFunnels":[],
"contactNotes":[],
"contactTasks":[],
"incomingEmailMessages":[],
}
],
"contactExtEvents":[],
"coupons":[],
"modifiedOn":1321856679000
"hasMore":true
}
where:
contact details are the same as for the list method.
Additionally this method returns information about whether there are more contacts
(hasMore).
Contact list import
Import based on email address
We import contacts using the http://www.salesmanago.pl/api/contact/list method.
{ "apiKey" : "your-api-key-123",
"email" : [ "****@gmail.com" ],
"contactId" : [ "123-XYZ" ],
"requestTime" : 1329128188409,
"sha" : "02bfe70541d3907cf487f26dc2665b184b1221a7"
}
*
email – email addresses of the imported contacts ,
*
owner – email address of contact owner .
{ "contacts" : [ { "contactEvents" : [ { "date" : 2012-02-13 10:38:53,
"description" : "Otagowano kontakt. Użyte tagi: ADmanago",
"detail1" : "ADmanago",
"detail2" : "",
"detail3" : "",
"detail4" : "",
"detail5" : ""
}
],
"contactTags" : [ { "tag" : "ADmanago",
"tagName" : "ADMANAGO",
"score" : 12,
}
],
"contactVisits" : [ {
"conversationIntId": null,
"host": "salesmanago.pl",
"time" : 2012-02-13 10:38:53,
"duration" : 12345677,
"visitSource" : "SEARCH_ENGINE",
"visitSourceHost": "www.google.pl",
"visitSourceKeywords" : "SALESmanago",
"visitHost" : null,
"visitScore" : 78,
"url" : null
}
],
"email" : "konrad****@gmail.com",
"emailMessages" : [ {
"name" : "Moja wiadomość ",
"subject" : "Dzień dobry ",
"date" : 2012-02-13 10:38:53,
"sent" : true,
"dateSent" : 2012-02-13 10:38:54,
"opened" : 1,
"dateOpened" : 2012-02-13 10:38:55,
"clicked" : 1,
"dateClicked" : 2012-02-13 10:38:56,
}
],
"incomingEmailMessages" : [ {
"subject" : "Dzień dobry ",
"date" : 2012-02-13 10:38:53,
}
],
"properties":[
{
"name":"promo.validTo",
"value":"2014-04-04"},
{
"name":"promo.coupon",
"value":"a8jg7"},
{
"name":"gender",
"value":"F"}
],
"contactFunnels":[
{
"salesFunnel":"5561397c-9792-4b60-aed1-a045b86c6b13",
"salesStage":"de0cf594-b999-438a-b1f0-8578c36a8da5"
}
],
"contactNotes":[
{
"note":"test note",
"date":1371118080000,
"priv":false
}
]
"contactTasks":[
{
"id":"3039d045-09eb-4169-8cb8-b0fe0359e8f8",
"note":"abcd abcd",
"date":1370922480000,
"cc":"",
"reminder":1370921580000
}
],
"contactExtEvents":[
{
"eventId":"2a91b3fc-995a-4b2f-b0af-9e7d10a822ed",
}
],
"coupons":[
{
],
"date":1366791917000,
"description":"Zakup z kartą \"Super Bonus\"",
"products":"p1",
"location":"Krupnicza 3, Kraków",
"value":144.43,
"contactExtEventType":"CART",
"detail1":"s1",
"detail2":"s2",
"detail3":null,
"detail4":null,
"detail5":null,
"detail6":null,
"detail7":null,
"detail8":null,
"detail9":null,
"detail10":null,
"externalId":"A-123123123"
"name":"test",
"coupon":"GXFCT",
"validTo":1425741448000
}
"id" : "123-abc-345-6a7",
"fax" : 12131415,
"name" : "Konrad ****",
"phone" : 111222333,
"score" : 56,
"optedOut" : false,
"optedOutPhone" : false,
"deleted" : false,
"invalid" : false,
"company" : "Benhauer Sp. z o.o. Sp. K.,
"externalId" : "aaa-123",
"modifiedOn" : 13865885810000,
"address":{
"zipCode":"43-305",
"country":"PL"
}
where:
}
],
"message" : [ ],
"success" : true
contacts – imported contacts
contactEvents – contact events
date – event date
description – event description
detail1 – event details
contactTags – contact tags
tagName – tag name
tag – tag ID
score – tag score
contactVisits – contact visits
conversationIntId – ID of mailing the visit comes from
host – page visited by the contact
time – time of visit
duration – duration
visitSource – source of visit, possible values of this field include:
EMAIL_CONVERSATION - visit from an email (clicked link)
SEARCH_ENGINE - entering from visit from a search engine
ADVERTISEMENT - entering from visit from an ad box
(AdWords)
REFERRER - entering from visit from a referring website
DIRECT - direct entrance or moving to next page
visitSourceHost – referring host (referrer)
visitSourceKeywords – keywords
visitScore – number of points
url – URL of visited page
email – contact's email address
emailMessages – contact's messages
name – message title
subject – message subject
date – creation date
sent – sending status
dateSent – sent date
opened – opening status
dateOpened – opening date
clicked – click status
dateClicked –click date
properties – additional contact details
name – detail's name
value – value
contactFunnels – campaign sales (funnels)
salesFunnel – campaign name
salesStage – stage the contact is at
contactNotes - notes
note – note's content
date – adding date
priv – if it is private
contactTasks – tasks
note – note (task) content
date – task date
cc – notification copy (email)
reminder – reminder date
contactExtEvents – external events
eventId – event ID
date – event date timestamp
description – description
products – products
location – location
value – event value
contactExtEventType – event type
detail1 – detail10 – event details
externalId – external ID of event
coupons – contact's coupons
name – name
coupon – value
validTo – coupon's expiry date
id – contact's ID
state – contact's state
optedOut – information whether the contact is unsubscribed from the
mailing list
optedOutPhone – information if the contact is unsubscribed from sending
sms
deleted – information if the contact is deleted
invalid – information if on whether the contact is invalid
fax – contact's fax number
name – contact's name
phone – phone number
score – the number of points
address – contact's address
streetAddress – street and house number
zipCode – zip code
city – town/city
country – country
company – contact's company
externalId – contact's external ID
modifiedOn – timestamp of latest contact update
success – information whether import was successful
Import based on contact's ID
We import contacts based on ID using the http://www.salesmanago.pl/api/contact/listById
method.
"contactId" : [ "123-XYZ" ],
"requestTime" : 1329128188409,
}
*
contactId – IDs of imported contacts ,
*
owner – email address of contacts' owner .
Request result is returned as JSON structure identical with the previous request.
Importing the list of recently modified contacts
We import contacts using the http://www.salesmanago.pl/api/contact/modifiedContacts
method.
{
}
"requestTime":1362056589362,
"sha":"64656d78b80d5df677700dabd363e1ffe51b59a7",
"from":1359673200361,
"to":1363042800362
*
owner – email address of contacts' owner ,
*
from – beginning range of modification dates
to – ending range of modification dates
{
}
"success":true,
"message":[],
"modifiedContacts":[
{
"id":"f66ca32b-c117-4b52-b3b8-863be077e710",
"email":"aleksander.***@benhauer.pl"
},
{
"id":"426e0ef8-675f-47fc-8ea8-745ac1706904",
"email":"konrad.***@salesmanago.pl"
},
{
"id":"1775d70e-cd61-4dd6-983a-64f067486adf",
"email":"marek.***@salesmanago.pl"
}
]
where:
modifiedContacts – contacts modified in the given time frame,
id – contact's ID,
Contacts' activity
We can obtain information about the activity of contacts in a given period from
SALESmanago. To do this we use the
http://www.salesmanago.pl/api/contact/recentActivity method.
{
"requestTime" : 1329128188409,
"from":1328050800504,
"to":1333231200504,
"allVisits":true
}
from – beginning date (timestamp, i.e. time in milliseconds that passed from
*
midnight 1 January 1970 UTC)
to – beginning date (timestamp, i.e. time in milliseconds that passed from midnight
*
1 January 1970 UTC)
allVisits – if set at true, SALESmanago will return in visit details information about
*
all pages opened by the customer in a given period
ipDetails – if set at true, SALESmanago will return in visit details additional
*
information searched for client IP
{
"success":true,
"message":[],
"monitoredContacts": 12300,
"totalContacts":234000,
"recentActivities": {
"from":1328050800504,
"to":1333231200504,
"customers":[{
"host": "salesmanago.pl",
"time":1330239675000,
"duration":22000,
"visitSource":"REFERRER",
"visitSourceHost":null,
"visitSourceKeywords":"localhost",
"visitSourceDetails":null,
"visitScore":120,
"client":"Benhauer Sp. z o.o. Sp. K. - Konrad Pawlus",
"contactId":"1d8cba47-f4b2-4efe-8250-5bdab5346628",
"ipOrganization": "TP SA",
"ipDetails": {
"ip" : "123.123.123.123",
"countryCode" : "PL",
"countryName" : "Poland",
"regionCode" : "77",
"regionName" : "Malopolskie",
"city" : "Cracow",
"postalCode" : "",
"latitude" : "50.083300",
"longitude" : "19.916700",
"isp" : "Neostrada Plus",
"organization" : "Neostrada Plus",
},
"contactVisits": [{ "time" : 2012-02-13 10:38:53,
"duration" : 12345677,
"visitSource" : "www.google.pl",
"visitSourceKeywords" : "SALESmanago",
"visitHost" : null,
"visitScore" : 78,
"url" : null
}, ...]}],
"partners":[... jw. ...],
"prospects":[... jw. ...],
"anonymous":[... jw. ...],
"visitSources": [
{"label": "example.com", "value": 123},
{"label": "other", "value": 1432},
...],
"visitSearchTerms": [
{"label": "tell me google", "value": 123},
{"label": "what is life?", "value": 1432},
...],
"visitStats": [
{
"date": 1330239675000,
"partnersVisits": 123
"prospectsVisits": 234
"customersVisits": 456
"otherVisits": 4321
},
...],
}
}
where:
successful)
recentActivity – structure consisting from three arrays of visits: customers,
partners, prospective customers (prospects).
from – beginning date
to – ending date
monitoredContacts – the number of monitored contacts
totalContacts – the number of all contacts
customers – list of customer visits
partners – list of partner visits
prospects – list of prospective customer visits
anonymous – list of anonymous visits
element of client's visit in lists:
host – page that was visited
visitSource – visit resources
visitSourceKeywords – key words
visitSourceHost – host
client – client name
email – client's email
contactId – unique client's ID,
ipOrganization – name of organization taken from IP (ISP)
/deprecated/
ipDetails – details decoded from client's IP
ip – IP number
countryCode – ISO code of the country (2-digits)
countryName – country name
regionCode – region code
regionName – region name
city – city/town
postalCode – zip code
latitude – latitude
longitude – longitude
isp – ISP name
organization – organization's name
contactVisits – contact's visits
visitSource – visit's resources
visitSourceKeywords – key words
visitSourceHost – host
visitSources – list of visit sources:
label – source name
value – number of visits
visitSearchTerms – list of searched terms:
label – searched term
value – number of visits
visitStats – visit statistics from the last week:
date – time of visit
partnersVisits – the number of partner's visits
prospectsVisits – the number of prospective customers' visits
customersVisits – the number of customers' visits
otherVisits – the number of other visits
External events
In SALESmanago it is possible to record external events for a contact, not necessarily
connected with their online activity. For example: the purchase of a product in a stationary
shop, visit to a place, etc.
Adding an external event
In order to add an event we use the
http://www.salesmanago.pl/api/contact/addContactExtEvent method.
Sample structure of request recording a new event:
{
}
"requestTime":1356180568127,
"sha":"3e4ec39722326150aae60f41e038d1def4450f46",
"contactEvent":{
"date":1356180568153,
"products":"p01, p02",
"value":1234.43,
"contactExtEventType":"PURCHASE",
"detail1":"C.ID: *** *** 234",
"detail2":"Płatość kartą",
"detail3":null,
}
The above call should include the following values:
*
owner – contact's owner ,
*
email – contact's email for which the event is added ,
contactEvent – event details:
date – event date (timestamp, i.e. time in milliseconds that passed from
*
midnight 1 January 1970 UTC) ,
description – event description,
products – optional list of products separated by commas,
location – optional event location, eg. a shop's or place's address
value – optional event value eg. amount spent
contactExtEventType – event type, possible values: PURCHASE, CART,
*
VISIT, PHONE_CALL, OTHER
detail1, detail2, detail3 – optional event details,
externalId – optional event ID, eg. ID from a teller system, etc.
In response we get the event ID in the SALESmanago system:
{
"success":true,
"message":[],
"eventId":"7284e317-3bb6-4505-afbe-55b9a101339a"
}
where:
eventId – ID of added event,
Modifying events
In order to modify an event we use the
http://www.salesmanago.pl/api/contact/updateContactExtEvent method.
Sample structure of request modifying an event:
{
}
"requestTime":1356180568127,
"contactEvent":{
"eventId":"7284e317-3bb6-4505-afbe-55b9a101339a",
"date":1356180568153,
"products":"p01, p02",
"value":1234.43,
"contactExtEventType":"PURCHASE",
"detail1":"C.ID: *** *** 234",
"detail2":"Płatość kartą",
"detail3":null,
}
In the above request the following values should be sent:
*
owner – contact's owner ,
contactEvent – event details:
*
eventId – event ID (returned by the add method) ,
date – event date (timestamp, i.e. time in milliseconds that passed from
*
midnight 1 January 1970 UTC) ,
description – event description,
products – optional list of products separated with commas,
location – optional event location, e.g. a shop's or place's address
value – optional event value e.g. the amount spent,
contactExtEventType – event type, allowed values: PURCHASE, CART,
VISIT, PHONE_CALL, OTHER
detail1, detail2, detail3 – optional event details,
externalId – optional event ID, e.g. ID from a teller system, etc.,
In response we get the event ID in the SALESmanago system:
{
}
"success":true,
"message":[],
where:
eventId – ID of added event,
Removing an event
In order to remove an event we use the
http://www.salesmanago.pl/api/contact/deleteContactExtEvent method.
Sample structure of request removing an event:
{
}
"requestTime":1356180568127,
The following values should be sent in the above request:
*
eventId – event ID (returned by the add method) ,
The result informs about the status of removing an event:
{
"success":true,
"message":[],
"result":"deleted"
}
Integration of external events, like basket
To get such data we use the addContactExtEvent and updateContactExtEvents method.
IDs of products added to the basket should be stored in the products field. The most
optimal method is transferring the whole basket content with one request – separating
products with commas or semicolons. It is also possible to once send the
addContactExtEvent method by recording the returned result (eventId) – and with the
next adding only update the product list (using the updateContactExtEvent method and
the above mentioned eventId).
The request addContactExtEvent may be made in two ways:
using the email address,
using the contactId (value from the smclient cookie that can be taken with e.g.
javascript).
These two ways cannot be used jointly - we also cannot add external events for
unidentified contacts.
Additionally the script, when not monitored (no smclient and email) - adds products to the
basket:
Such products must then be kept at the shop's side (e.g. in session) - and straight after
contact identification products must be transferred to salesmanago using the
addContactExtEvent method.
Import of tag list
Tags are imported using the http://www.salesmanago.pl/api/contact/tags method.
}
"showSystemTags" : true,
"requestTime" : 1329128188409,
showSystemTags – when set at true, SALESmanago will also return system
*
tags ,
*
owner – email address of contacts' owner .
{ "tags" : [ { "tag" : "ADmanago",
"numberOfTagged" : 12
} ],
"message" : [ ],
"success" : true
}
where:
tags – imported tags
tag – tag name
numberOfTagged – the number of tagged contacts
successful)
Monitoring AJAX/JavaScript events
Except for visits, SALESmanago also makes it possible to record JavaScript events – like
e.g. bookmark openings or file downloads.
In order to record an external event, the SALESmanago method must be called in the
JavaScript script on our website:
smEvent(eventName)
where:
eventName is the name of event e.g. "details-deposit", "details-loan".
such an event must be joined with certain elements that are to be monitored, e.g.:
<a href="download.pdf" onclick="smEvent('PDF-download');return
true;">download</a>
Editing contact's tag list
Tags are imported using the http://www.salesmanago.pl/api/contact/managetags method.
{
}
"clientId":"h4jsu6pc5txybj04",
"apiKey":"-2203694140088941698545922683614585589",
"requestTime":1360792407226,
"sha":"437b8cac9a30283137f611ad820cdbdb937a20f0",
"contactId":null,
"tags":["new_api_tag_a", "new_api_tag_b", "new_api_tag_c"],
"removeTags":["old_api_tag_a", "old_api_tag_b", "old_api_tag_c"]
*
email/contactId – contact's ID (alternately e-mail or SALESmanago contact ID) ,
*
owner – e-mail address of contact's owner ,
tags – array of new tags of a contact
removeTags – array of tags to be removed
{
"success":true,
"message":[],
"contactId":"be691c54-c515-4dc2-8692-325c3faf4cfd"
}
where:
successful)
contactId – ID of modified contact,
Sending email
In order to send an email through API the http://www.salesmanago.pl/api/email/send
method should be used.
{
"clientId": "o7gslwlc8o1e2ry1",
"apiKey": "-8773203084919279780-2743038323156910252",
"requestTime": 1391167514795,
"sha": "184db1df6ec4893a1f50809bf8d1a4fe88cde4dc",
"user": "[email protected]",
"emailId": "029c504e-193a-43f2-84c7-3b7ee3c4438c",
"contacts": [
{
"email": "[email protected]",
"contactId": null,
"properties": [
{
"name": "ext_detal_01",
"value": "value_01"
},
{
"value": "value_02"
}
]
},
{
"email": "[email protected]",
"contactId": null,
"properties": [
{
"value": "value_03"
},
{
"value": "value_04"
}
]
}
],
"date": 1391167515515,
"subject": "Sample API subject",
"campaign": "monitor_me_in_ga"
}
*
emailId – message ID from the SALESmanago system .
*
date – mailing date
subject – mailing subject (if not provided – a default will be used)*
campaign – campaign for tracing Google UTM (if not provided – a default will be
used)*
contacts – array of contacts emails should be sent to*
email/contactId – optional – e-mail address of contact or its ID,
properties – additional attributes of email messages defined by the user. It is
not advised to use Polish signs and spaces in names, but it is allowed. In an
e-mail message the construction $cst.nazwaParametru$ should be used in
order to substitute the proper value.
{
"success": true,
"message": ["Emails are scheduled to send."]
}
where:
successful)
Contacts' tasks
Adding, updating and removing a contact's task is done with the use of one method:
http://www.salesmanago.pl/api/contact/updateTask
{
"requestTime" : 1329128188409,
"finished" : false,
"smContactTaskReq" : {
"id" : "task-id-123",
"note" : "Zadzwonić do klienta",
"date" : 2012-02-13 10:38:53,
"cc" : "[email protected]",
"reminder" : "_30_MIN"
}
}
finished – attributing a true value will cause deletion of task and then only an
additional ID parameter is required. When adding and updating a task, a false value
*
should be attributed .
*
id – task id
note – task note
*
date – date of task execution
cc – list of emails where a reminder will be sent (emails should be separated with
commas)
reminder – reminder about the task. It defines when the reminder should be
*
sent . Allowed values:
15_MIN – 15 minutes before,
30_MIN – 30 minutes before,
1_HOUR – an hour before,
12_HOUR – 12 hours before,
1_DAY – 1 day before,
1_WEEK – 1 week before,
{ "taskId" : "task-Id-123",
"message" : [ ],
"success" : true
}
where:
taskId – id of task that the action concerns.
successful)
Adding automation rules
Adding automation rules is possible through the
http://www.salesmanago.pl/api/rule/insert method.
Sample request structure:
{
"async": true,
"clientId": "YOUR_ID_KLIENTA",
"apiKey": "YOUR_API_SECRET",
"requestTime": 1410858306889,
"sha": "bfdbca9ebd70710ab27a74088a44c98ccb4f2247",
"owner": "[email protected]",
"shared": true,
"active": true,
"deleted": false,
"delayConditionsCheck": true,
"delayConditionsValue": 1,
"delayConditionsPeriod": "DAY",
"name": "Rule insert api test05",
"maxFireTimes": 111,
"minFireInterval": 2,
"checkAgain": true,
"checkAgainAfter": 2,
"events": [
{
"eventType": "CONTACT_WAS_TAGGED_WITH",
"properties": {"tag": "sampleTag234"}
},
{
"eventType": "NEW_EXT_EVENT",
"properties": {
"checkValue": "true",
"newExtEventType": "CART",
"extEventAddedCondition1_Type": ">",
"extEventAddedCondition1_Value": "80"
}
}
],
"conditions": [],
"actions": [
{
"actionType": "ADD_NOTE",
"properties": {
"addNotePrivate": "true",
}
]
"addNoteText": "note sample text 001"
}
}
Basic elements that need to be provided when adding a new rule are:
*
owner – account of rule owner .
*
shared – is the rule shared
*
active – is the rule active .
*
deleted – has the rule been removed .
*
delayConditionsCheck – delay checking the conditions .
*
delayConditionsValue – delay checking the conditions – value .
*
delayConditionsPeriod – delay checking the conditions – period .
*
name – rule name .
*
maxFireTimes – maximum number of rule fires .
*
minFireInterval – minimum interval between rule fires (days) .
*
checkAgain – checking rules again .
*
checkAgainAfter – checking rules again – number of days .
events – events:
eventType – event type (CONTACT_SCORE, CONTACT_OPENED_EMAIL,
CONTACT_CLICKED_EMAIL, INCOMING_EMAIL_SUBJECT,
CONTACT_WAS_TAGGED_WITH, CONTACT_VISITED_URL,
CONTACT_REACHED_SALES_STAGE, DETAILS_ADDED, DETAILS_MODIFIED,
SMS_DELIVERED, TAG_REACHED_SCORE, SMS_REPLIED, STAGE_SCORE,
CONTACT_FROM_PHRASE, CONTACT_FROM_SOURCE, NEW_OWNER,
NEW_EXT_EVENT, VMS_DELIVERED, SOCIAL_EVENT, PROXY_EMAIL,
*
OPTED_OUT, CONTACT_ADDED) .
properties – event details:
conditions – conditions:
conditionType – condition type (CONTACT_SCORE,
CONTACT_OPENED_EMAIL, CONTACT_CLICKED_EMAIL,
INCOMING_EMAIL_SUBJECT, CONTACT_WAS_TAGGED_WITH,
CONTACT_TAGGED_WITH, CONTACT_VISITED_URL,
CONTACT_REACHED_SALES_STAGE, SMS_DELIVERED,
TAG_REACHED_SCORE, SMS_REPLIED, STAGE_SCORE,
CONTACT_FROM_PHRASE, CONTACT_FROM_SOURCE,
CONTACT_HAS_DETAIL, CONTACT_HAS_OWNER,
CONTACT_HAS_EXT_EVENT, VMS_DELIVERED, SOCIAL_EVENT,
CONTACT_RECEIVED_NUMBER_OF_EMAILS, PROXY_EMAIL_SUBJECT,
*
USED_EASYPACK24, CONTACT_STATE) .
properties – condition details:
actions – actions:
actionType – action type (SEND_EMAIL, SEND_ALERT, ADD_TAGS,
DELETE_TAGS, SCORE_TAG, SCORE, ADD_TO_SALES_FUNNEL, SEND_SMS,
RUN_RULE, ADD_OWNER, SEND_VMS, ADD_NOTE, ADD_TASK,
CHANGE_STATE, GENERATE_COUPON, RTB_ADGROUP,
DELETE_CONTACT_FROM_FUNNEL, ADD_MODIFY_DETAIL,
*
DISPLAY_BANNER) .
properties – action details:
Temporary authorization
The SALESmanago system makes it possible to obtain a temporary token using the
username and password. To do this the following method
http://www.salesmanago.pl/api/system/authorise should be called.
{
"userName" : "[email protected]",
"password" : "****"
}
Basic elements that need to be provided when adding a new contact in structure:
*
userName – user name
*
password – password
{
}
"token" : "b426c6663d844305b2539e9bc27b75dc",
"message" : [ ],
"success" : true
where:
successful),
token – is a temporary token that may be used for authorization in exchange for
apiSecret,
clientId – Client ID required for further operations,
message – array of additional information enabling error identification,
Account registration (partners only)
The SALESmanago system makes it possible to register a new account. To do this the
following method http://www.salesmanago.pl/api/system/registeraccount should be used.
{
"clientId":"h4jsu6pc5txybj04",
"apiKey":"-89769101308486819292381884901962874326",
"requestTime":1357130990877,
"sha":"8bc153ea5110a418d7dac3dc4ed11f442e1a08ac",
"password":"haslo123",
"contactPerson":"Konrad Pawlus",
"invoiceCity":"Kraków",
"invoiceCountry":"PL",
"invoiceStreetAddress":"Krupnicza 3",
"invoiceZipCode":"31-123",
"companyName":"Benhauer Sp z o.o. Sp. K.",
"contactCity":"Kraków",
"contactCountry":"PL",
"contactPhone":"0048600500400",
"contactStreetAddress":"Krupnicza 3",
"contactZipCode":"31-123",
"nip":"123-123-123-123",
"lang":"pl",
"version":"PRO"
}
Basic elements that may be provided by adding a new contact in the structure are:
*
email – e-mail address of new account ,
*
password – password for new account ,
contactPerson – contact person,
companyName – company name,
nip – company's NIP number,
invoiceStreetAddress – invoicing address: street and house number,
invoiceCity – invoicing address: town/city,
invoiceZipCode – invoicing address: zip code,
invoiceCountry – invoicing address: 2-letter country code (PL - Polska),
contactStreetAddress – contact address: street and house number,
contactCity – contact address: city/town,
contactZipCode – contact address: zip code,
contactCountry – contact address: 2-letter country code (PL - Polska),
lang – default language (2-letter language code: pl – Polish),
version – account version: PRO, LIGHT, SUPER_LIGHT,
{
}
"success":true,
"message":[],
"clientId":"ujk3j74yfan2jeit",
"apiSecret":"xivw1g7h1m7mxraambh2drwfb8fth0tn"
where:
successful),
clientId – client's ID (used in API communication and monitoring codes),
apiSecret – API key,
message – array of additional information enabling error identification,
NextGen e-Commerce code implementation
In order to gain NextGen functionality you need to add monitoring code presented below:
<script type='text/javascript'>
var _smShopId = '<-- YOUR_SHOP_ID_FROM_SALESMANAGO -->';
(function () {
var sm = document.createElement('script');
sm.type = 'text/javascript';
sm.async = true;
sm.src = ('https:' == document.location.protocol ? 'https://' :
'http://') + '<-- YOUR_ENDPOINT -->.salesmanago.pl/static/smng.js';
var s = document.getElementsByTagName('script')[0];
s.parentNode.insertBefore(sm, s);
})();
</script>
Additionaly you need to add markers into products on lists, as shown on sample below:
by adding CSS class "sm-pid-{UniqueId} sm-product-list". Similar on product
card:
by adding CSS class: "sm-pid-{UniqueId} sm-product-view" UniqueId should
reflect ID inproducts XML feed.

API documentation

Transcription

Similar documents

Whitepages Pro Caller Identification API

Groovy Vampires

los güeros contact information form document information family

Quarterly NL May 2010-b

Dear Future Sponsor

ni.com - SDL.com

Air Pollutant Index - Jabatan Alam Sekitar

Siegfried`s One Stop Shop for partners in the pharmaceutical industry

Roto-Jet® RO-FT API 610 - Process Equipment Company

Untitled - Petromak

Connichiwa – A Framework for Cross