General information
Authorization data
{
"clientId":"your-client-id-123",
"apiKey":"your-api-key-123",
"requestTime":1327056031488,
"sha":"2aa3927a7dee8c2a712adb5375f5fa36dd8fe00c"
}
Each API call, except for authentication, has to include authentication data.
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:
https://www.salesmanago.pl/api
For example:
https://xyz.salesmanago.pl/api/contact/upsert
Where xyz is your server’s ID (www or app1, app2, app3…)
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:
After several minutes from implementation, if there are visits on our website, information about the need to implement the code will disappear from the SALESmanago main page.
Sending additional monitoring data
Sample code with a marked contactId value:
<script type="text/javascript">
var _smid = "your-client-id-123";
var _smclientid = "contactIdFromResponse-123";
</script>
<script src="https://www.salesmanago.pl/static/sm.js" type="text/javascript"/>
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('The email is not valid.');
$("#email").focus();
} else {
createCookie('smclient', data, 365 * 10);
$(".registeredInfo").show();
}
},
error:function (data) {
alert("Error - failed to register");
}});
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.
External events integration through JavaScript
Thanks to external events, we can send additional information about the contact from external systems to SALESmanago. The most popular way to use external events in eCommerce is to send information about purchases (external event: purchase) or abandoned carts (external event: cart) made by the contact. This information can be used to:
- collect transaction data – it’s necessary to analyze data in the eCommerce Analytics Dashboard,
- avoid lost sales as a result of an abandoned cart,
- send an email, which thanks your client for purchases,
- the advanced automatic contact segmentation based on the purchase information sent to our system.
Of course, there are other types of external events, that you can use and adjust to your needs. These are:
- VISIT,
- PHONE_CALL,
- RESERVATION,
- CANCELED,
- ACTIVATION,
- MEETING,
- OFFER,
- DOWNLOAD,
- LOGIN,
- TRANSACTION,
- OTHER.
External events can be send through the API.
Another way of transferring external events, is the ability to sent them through JavaScript. Using this option, you don’t need to do it by API.
The method is not recommended. We recommend using the method addContactExtEvent.
Sent external events through JavaScript
[ Step 1.] Monitoring code change on your website – you should implement new monitoring code (find it below). Remember to modify the value in “var _smid =” to your individual client ID.
Monitoring code:
<script type="text/javascript">
var _smid="SHORT_ID_TO_REPLACE";
(function(w, r, a, sm, s){
w['SalesmanagoObject']=r; w[r]=w[r]||function(){(w[r].q=w[r].q||[]).push(arguments)};
sm=document.createElement('script'); sm.type='text/javascript'; sm.async=true; sm.src=a;
s=document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(sm,s);
})(window,'sm',('https:'==document.location.protocol?'https://':'http://')+'endpoint/static/sm.js');
</script>
Your individual Endpoint and Client ID is in SETTINGS -> INTEGRATION -> API ACCESS.
[ Step 2.] Specific external event report – you can send a request to get a response using different external events with the example below:
Raporting of external event code:
<script type="text/javascript">
var d = new Date();
sm('extEvent',
{ owner:'******@******.pl',//USER ACCOUNT IN SALESmanago
email:'nowyevent1@test.pl',//CONTACT EMAIL
contactExtEventType:"PURCHASE",//TYPE OF EXTERNAL EVENT
date:d.getTime(),//DATE OF EXTERNAL EVENT
description:'description about transaction',//DESCRIPTIONS OF EXTERNAL EVENT
products:'p01, p02, p03',//PRODUCTS
location:'location',//LOCATION
value:213.32,//VALUE (JUST DIGITS)
details:['detail', 'detail2'],//DETAILS AS TABLE(UP TO 20)
externalld:'zam'+d.getTime()}//EXTERNAL ID
);
</script>
API - Contact management
Adding a new contact or modifying the existing contact
An example of request data structure:
{
"clientId":"your-client-id-123",
"apiKey":"your-api-key-123",
"requestTime":1327056031488,
"sha":"2aa3927a7dee8c2a712adb5375f5fa36dd8fe00c",
"async" : true,
"contact" : {
"email" : "test-1@konri.com",
"fax" : "+48345543345",
"name" : "Test",
"phone" : "+48123321123",
"company" : "Benhauer",
"externalId" : null,
"state" : "PROSPECT",
"address":{
"streetAddress":"Brzyczynska 123",
"zipCode":"43-305",
"city":"Krakow",
"country":"PL"
}
},
"owner" : "admin@vendor.pl",
"newEmail" : "",
"forceOptIn" : true,
"forceOptOut" : false,
"forcePhoneOptIn" : true,
"forcePhoneOptOut" : false,
"tags" : [ "API","ADmanago"],
"removeTags" : [ "Test_tag","New"],
"properties" : {
"custom.nickname":"Konri",
"custom.sex":"M"
},
"dictionaryProperties": [{
"name": "birthday",
"type": "DATE",
"value": 1488927600000
},
{
"name": "visits",
"type": "NUMBER",
"value": 42
}
],
"birthday" : "19801017",
"province" : "Małopolska",
"useApiDoubleOptIn":true,
"apiDoubleOptInEmailTemplateId":null,
"apiDoubleOptInEmailAccountId":null,
"apiDoubleOptInEmailSubject":null,
"lang":"PL",
"consentDetails": [
{
"consentName": "AGREEMENT",
"consentAccept": true,
"agreementDate": 1391167515515,
"ip":"192.168.7.139",
"optOut": true,
"consentDescriptionId": 123456
},
{
"consentName": "AGREEMENT2",
"consentAccept": false,
"agreementDate": 1391167515789,
"ip":"192.168.7.139",
"optOut": true,
"consentDescriptionId": 345678
}
]
}
The contact is added by calling the method:
https://www.salesmanago.pl/api/contact/upsert
Basic elements that can be provided by adding a new contact in the structure include:
| Field | Description |
|---|---|
| async | this parameter specifies how to add contacts to the SALESmanago system, the recommended and default option is “true” which executes the process depending on the system load, but if you want to add contacts immediately after sending the request, select the “false” option. |
| name | contact name |
| email* | contact email |
| phone | phone number |
| fax | fax number |
| externalId | external contact identifier |
| company | contact company |
| state | contact status (CUSTOMER, PROSPECT, PARTNER, OTHER, UNKNOWN) |
| birthday | date of contact companybirth, 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) |
| useApiDoubleOptIn** | optional ID for the double-opt-in template default false |
| lang** | contact language |
| apiDoubleOptInEmailTemplateId** | optional ID of template for double-opt-in, |
| apiDoubleOptInEmailAccountId** | optional ID of e-mail account for double-opt-in |
| apiDoubleOptInEmailSubject** | optional message topic for double-opt-in |
| address | contact’s address |
| streetAddress | street and house number |
| zipCode | zip code |
| city | town/city |
| country | country |
**When using the useApiDoubleOptIn flag, choose one of the two options:
- the completed lang parameter
- all three parameters: apiDoubleOptInEmailTemplateId, apiDoubleOptInEmailAccountId and apiDoubleOptInEmailSubject.
Additionally the request should be supplemented with the information about contact’s owner (account the contact will be attributed to):
| Field | Description |
|---|---|
| owner* | contact’s owner (SALESmanago user account email) |
Optionally we can change the contact’s e-mail address. The newEmail field should then be filled in:
| Field | Description |
|---|---|
| newEmail | new email address (if we want to modify it) |
For new contacts, the “newEmail” field will be ignored. New contacts will be assigned an address that matches the data in the field: “email.”
We can also force the so-called opt-in/opt-out of the contact. We must then fill in the forceOptIn or forceOptOut field.
In case of absence of this fields contact will be created with opt-in state.
| Field | Description |
|---|---|
| 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.
| Field | Description |
|---|---|
| tags | array of contact’s tags |
| removeTags | array of tags to be removed |
When building an “Upsert” query, it is not recommended to include a command to add and remove the same tag in the same request, as this will remove the tag completely. To update a tag, delete the selected tag in the first request and add this tag in a second, separate request to update it.
It is also possible to attribute any number of fields defined by the user to a contact. We send them through a map:
| Field | Description |
|---|---|
| properties | contact attributes defined by the user. It is advised not to use special characters and spaces in the name, but it is allowed. |
| dictionaryProperties | user-defined attributes of the dictionary, the first to add a particular attribute can be used for the remaining contacts through re-enter the same name and type of the assigned another value. |
| name | name (3-255 signs), |
| type | type (NUMBER or DATE), |
| value | integer greater than 0, for a DATE timestamp type, with the time set to 00:00:00 UTC time |
| consentName | name of the agreement (WARNING - agreement should exist in the system), |
| consentAccept | boolean value of consent (true or false), |
| agreementDate | time in ms of agreement date (in case of absence a current timestamp will be used), |
| ip | IP address of contact, |
| optOut | the boolean value of the withheld consent (true or false) |
| consentDescriptionId | consent description identifier |
Result of request:
{
"contactId" : "21c252a6-6de0-436b-bae8-9d0142363266",
"message" : [],
"success" : true,
"externalId": null
}
As a result of request we receive:
success – boolean value informing about the result of request (successful/not successful)
contactId – unique ID of the updated or newly added contact
message – array of additional information enabling error identification
externalId – external contact identifier
The useApiDoubleOptIn flag overrides the forceOptIn flag.
Using useApiDoubleOptIn together with forceOptIn will cause forceOptIn to be ignored.
Adding a new contact
Sample structure of request data:
{
"apiKey" : "your-api-key-123",
"clientId" : "your-client-id-123",
"sha" : "08924f45afc2e4fb8b652c53cdb493c7ddb846a1",
"requestTime" : 1327059355361,
"contact" : {
"email" : "konrad-test-1@konri.com",
"fax" : "+48345543345",
"name" : "Konrad Test",
"phone" : "+48123321123",
"company" : "Benhauer",
"externalId" : null,
"state" : "PROSPECT",
"address":{
"streetAddress":"Brzyczyńska 123",
"zipCode":"43-305",
"city":"Bielsko-Biała",
"country":"PL"
}
},
"owner" : "admin@vendor.pl",
"forceOptOut" : false,
"forcePhoneOptOut" : false,
"tags" : [ "API",
"ADmanago"
],
"properties":{"custom.nickname":"Konri","custom.sex":"M"},
"dictionaryProperties": [{
"name": "birthday",
"type": "DATE",
"value": 1488927600000
},
{
"name": "visits",
"type": "NUMBER",
"value": 42
}
],
"birthday": "19801017",
"province": "Małopolska",
"useApiDoubleOptIn":true,
"lang":"PL",
"consentDetails": [
{
"consentName": "AGREEMENT",
"consentAccept": true,
"agreementDate": 1391167515515,
"ip":"192.168.7.139",
"optOut": true,
"consentDescriptionId": 123456
},
{
"consentName": "AGREEMENT2",
"consentAccept": false,
"agreementDate": 1391167515789,
"ip":"192.168.7.139",
"optOut": true,
"consentDescriptionId": 345678
}
]
}
Result of request:
{
"contactId" : "21c252a6-6de0-436b-bae8-9d0142363266",
"message" : [ ],
"success" : true,
"externalId": null
}
We add a contact by calling the method:
https://www.salesmanago.pl/api/contact/insert
The basic elements that can be specified by adding a new contact are the same as in the upsert method, except for fields: forceOptIn, forcePhoneOptIn i removeTags.
Available fields in the request insert method:
| Field | Max. length | Description |
|---|---|---|
| owner* | 255 | contact’s owner (SALESmanago user account email) |
| email* | 255 | contact email |
| name | 255 | contact name |
| phone | 255 | phone number |
| fax | 255 | fax number |
| company | 255 | contact company |
| state | 255 | contact’s state (CUSTOMER, PROSPECT, PARTNER, OTHER, UNKNOWN) |
| externalId | 255 | External contact ID |
| birthday | yyyyMMdd/Mmdd | date of contact companybirth, 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 | 255 | contact’s province |
| streetAddress | 255 | street and house number |
| zipCode | 255 | zip code |
| city | 255 | town/city |
| country | 255 | country |
| useApiDoubleOptIn | true/false | optional ID for the double-opt-in template default false |
| lang | 255 | contact language |
| forceOptOut | true/false | forcing opt-out after adding/modification |
| forcePhoneOptOut | true/false | forcing opt-out from a phone after adding/modification |
| tags | 255/tag | array of contact’s tags |
| properties | 255/detal | contact attributes defined by the user. It is advised not to use special characters and spaces in the name, but it is allowed. |
| dictionaryProperties | user-defined attributes of the dictionary, the first to add a particular attribute can be used for the remaining contacts through re-enter the same name and type of the assigned another value. | |
| name | name (3-255 signs), | |
| type | type (NUMBER or DATE), | |
| value | integer greater than 0, for a DATE timestamp type, with the time set to 00:00:00 UTC time | |
| consentName | 255 | name of the agreement (WARNING - agreement should exist in the system), |
| consentAccept | true/false | boolean value of consent (true or false), |
| agreementDate | timestamp | time in ms of agreement date (in case of absence a current timestamp will be used), |
| ip | 255 | IP address of contact, |
| optOut | true/false | the boolean value of the withheld consent (true or false) |
| consentDescriptionId | true/false | consent description identifier |
As a result of request we receive:
success – boolean value informing about the result of request (successful/not successful)
contactId – unique ID of the updated or newly added contact
message – array of additional information enabling error identification
externalId – external contact identifier
Modifying an existing contact
Sample structure of request data:
{
"apiKey" : "your-api-key-123",
"clientId" : "your-client-id-123",
"email" : "konrad@salesmanago.pl",
"contactId" : null,
"contact" : {
"company" : "Benhauer Sp. z o.o. Sp. K.",
"externalId" : null,
"email" : "test-1@konri.com",
"fax" : "+48345543345",
"name" : "Test",
"phone" : "+48123321123",
"state" : "PROSPECT",
"address":{
"streetAddress":"Brzyczynska 123",
"zipCode":"43-305",
"city":"Krakow",
"country":"PL"
}
},
"owner" : "admin@vendor.pl",
"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"},
"dictionaryProperties": [{
"name": "birthday",
"type": "DATE",
"value": 1488927600000
},
{
"name": "visits",
"type": "NUMBER",
"value": 42
}
],
"birthday": "1017",
"province": "Małopolska",
"consentDetails": [
{
"consentName": "AGREEMENT",
"consentAccept": true,
"agreementDate": 1391167515515,
"ip":"192.168.7.139",
"optOut": true,
"consentDescriptionId": 123456
},
{
"consentName": "AGREEMENT2",
"consentAccept": false,
"agreementDate": 1391167515789,
"ip":"192.168.7.139",
"optOut": true,
"consentDescriptionId": 345678
}
]
}
Result of request:
{
"contactId" : "21c252a6-6de0-436b-bae8-9d0142363266",
"message" : [ ],
"success" : true,
"externalId": null
}
We modify a contact by calling a method:
https://www.salesmanago.pl/api/contact/update
Request data are identical with the upsert method described above. A contact is identified by email or contactId (returned when adding a contact). If you specify the email address in the box contact e-mail address is updated.
Available fields in the request update method:
| Field | Max. length | Description |
|---|---|---|
| owner* | 255 | contact’s owner (SALESmanago user account email) |
| email* | 255 | contact email |
| name | 255 | contact name |
| phone | 255 | phone number |
| fax | 255 | fax number |
| company | 255 | contact company |
| state | 255 | contact’s state (CUSTOMER, PROSPECT, PARTNER, OTHER, UNKNOWN) |
| externalId | 255 | External contact ID |
| birthday | yyyyMMdd/Mmdd | date of contact companybirth, 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) |
| streetAddress | 255 | street and house number |
| zipCode | 255 | zip code |
| city | 255 | town/city |
| country | 255 | country |
| forceOptOut | true/false | forcing opt-out after adding/modification |
| forceOptIn | true/false | forcing opt-in after adding/modification (if the previous option has not been chosen) |
| forcePhoneOptOut | true/false | forcing opt-out from a phone after adding/modification |
| forcePhoneOptIn | true/false | forcing opt-in to a phone after adding/modification (if the previous option has not been chosen) |
| tags | 255/tag | array of contact’s tags |
| removeTags | 255/tag | array of tags to be removed |
| properties | 255/detal | contact attributes defined by the user. It is advised not to use special characters and spaces in the name, but it is allowed |
| dictionaryProperties | user-defined attributes of the dictionary, the first to add a particular attribute can be used for the remaining contacts through re-enter the same name and type of the assigned another value. | |
| name | name (3-255 signs), | |
| type | type (NUMBER or DATE), | |
| value | integer greater than 0, for a DATE timestamp type, with the time set to 00:00:00 UTC time | |
| province | 255 | contact’s province |
| consentName | 255 | name of the agreement (WARNING - agreement should exist in the system), |
| consentAccept | true/false | boolean value of consent (true or false), |
| agreementDate | timestamp | time in ms of agreement date (in case of absence a current timestamp will be used), |
| ip | 255 | IP address of contact, |
| optOut | true/false | the boolean value of the withheld consent (true or false) |
| consentDescriptionId | true/false | consent description identifier |
As a result of request we receive:
success – boolean value informing about the result of request (successful/not successful)
contactId – unique ID of the updated or newly added contact
message – array of additional information enabling error identification
externalId – contact external identifier
Adding or modifying many contacts simultaneously
Sample request data structure:
{
"clientId": "your-client-id-123",
"apiKey": "your-api-key-123",
"requestTime": 1348046897664,
"sha": "8d893f41dd479bb0489686f04b0a169005d22559",
"owner": "admin@vendor.pl",
"upsertDetails": [
{
"newEmail": null,
"contact": {
"email": "batchtest2@benhauer.pl",
"name": "Test1",
"phone": "+48123321123",
"fax": "+48345543345",
"company": "Benhauer Sp. z o.o. Sp. K.",
"externalId": null,
"address": {
"streetAddress": "Brzyczynska 123",
"zipCode": "43-305",
"city": "Krakow",
"country": "PL"
}
},
"tags": [
"API",
"ADmanago"
],
"removeTags": [
"Test_tag",
"New"
],
"properties": {
"custom.nickname": "Konri1",
"custom.sex": "M"
},
"dictionaryProperties": [
{
"name": "birthday",
"type": "DATE",
"value": 1488927600000
},
{
"name": "visits",
"type": "NUMBER",
"value": 42
}
],
"birthday": "19801017",
"province": "Małopolska",
"forceOptIn" : true,
"forceOptOut" : false,
"forcePhoneOptIn" : true,
"forcePhoneOptOut" : false
},
{
"contact": {
"email": "batchtest1@benhauer.pl",
"name": "Test2",
"phone": "+48123321123",
"fax": "+48345543345",
"company": "Benhauer Sp. z o.o. Sp. K.",
"externalId": null
},
"newEmail": "batchtestNew@benhauer.pl",
"forceOptIn": true,
"forceOptOut": false,
"forcePhoneOptIn": true,
"forcePhoneOptOut": false,
"tags": [
"API",
"ADmanago"
],
"properties": {
"custom.nickname": "Konri2",
"custom.sex": "M"
},
"birthday": "19801017",
"province": "Małopolska"
}
],
"useApiDoubleOptIn": true,
"lang": "PL"
}
We add or modify many contacts at the same time using the below method:
https://www.salesmanago.pl/api/contact/batchupsert
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 new contact or modifying the existing contact).
Available fields in the request batchupsert method:
| Field | Max. length | Description |
|---|---|---|
| owner* | 255 | contact’s owner (SALESmanago user account email) |
| email* | 255 | contact email |
| name | 255 | contact name |
| phone | 255 | phone number |
| fax | 255 | fax number |
| company | 255 | contact company |
| state | 255 | contact’s state (CUSTOMER, PROSPECT, PARTNER, OTHER, UNKNOWN) |
| externalId | 255 | External contact ID |
| newEmail | 255 | new contact’s email |
| birthday | yyyyMMdd/Mmdd | date of contact companybirth, 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 | 255 | contact’s province |
| streetAddress | 255 | street and house number |
| zipCode | 255 | zip code |
| city | 255 | town/city |
| country | 255 | country |
| forceOptOut | true/false | forcing opt-out after adding/modification |
| forceOptIn | true/false | forcing opt-in after adding/modification (if the previous option has not been chosen) |
| forcePhoneOptOut | true/false | forcing opt-out from a phone after adding/modification |
| forcePhoneOptIn | true/false | forcing opt-in to a phone after adding/modification (if the previous option has not been chosen) |
| tags | 255/tag | array of contact’s tags |
| removeTags | 255/tag | array of tags to be removed |
| properties | 255/detal | contact attributes defined by the user. It is advised not to use special characters and spaces in the name, but it is allowed |
| dictionaryProperties | - | user-defined attributes of the dictionary, the first to add a particular attribute can be used for the remaining contacts through re-enter the same name and type of the assigned another value. |
| name | 255 | name |
| type | NUMBER or DATE | type |
| value | - | integer greater than 0, for a DATE timestamp type, with the time set to 00:00:00 UTC time |
| useApiDoubleOptIn | true/false | use double opt-in option, default true |
| lang | 255 | contact language |
Result of request:
{
"success":true,
"message":[],
"contactIds":{
"batchtest2@benhauer.pl":"b257d328-2a95-41ce-915a-94b4274e6c29",
"batchtestNew@benhauer.pl":"bf4d6c03-1ca2-4b3f-8131-c28829236b02"
},
"invalidContacts": null
}
In response we get a request status and, if it is successful, a list of IDs for added contacts:
success – boolean value informing about the result of request (successful/not successful)
contactId – unique ID of the updated or newly added contact
message – array of additional information enabling error identification
invalidContacts – array of invalid contacts
For new contacts, the “newEmail” field will be ignored. New contacts will be assigned an address that matches the data in the field: “email.”
Asynchronous adding or modifying many contacts simultaneously
Sample request data structure:
{
"clientId": "your-client-id-123",
"apiKey": "your-api-key-123",
"requestTime": 1348046897664,
"sha": "8d893f41dd479bb0489686f04b0a169005d22559",
"owner": "admin@vendor.pl",
"upsertDetails": [
{
"newEmail": null,
"contact": {
"email": "batchtest2@benhauer.pl",
"name": "Test1",
"phone": "+48123321123",
"fax": "+48345543345",
"company": "Benhauer Sp. z o.o. Sp. K.",
"externalId": null,
"address": {
"streetAddress": "Brzyczynska 123",
"zipCode": "43-305",
"city": "Krakow",
"country": "PL"
}
},
"relation" : {
"type": "PARENT",
"email": "child@test.pl"
},
"tags": [
"API",
"ADmanago"
],
"removeTags": [
"Test_tag",
"New"
],
"properties": {
"custom.nickname": "Konri1",
"custom.sex": "M"
},
"dictionaryProperties": [
{
"name": "birthday",
"type": "DATE",
"value": 1488927600000
},
{
"name": "visits",
"type": "NUMBER",
"value": 42
}
],
"birthday": "19801017",
"province": "Małopolska",
"forceOptIn" : true,
"forceOptOut" : false,
"forcePhoneOptIn" : true,
"forcePhoneOptOut" : false
},
{
"contact": {
"email": "batchtest1@benhauer.pl",
"name": "Test2",
"phone": "+48123321123",
"fax": "+48345543345",
"company": "Benhauer Sp. z o.o. Sp. K.",
"externalId": null
},
"newEmail": "batchtestNew@benhauer.pl",
"forceOptIn": true,
"forceOptOut": false,
"forcePhoneOptIn": true,
"forcePhoneOptOut": false,
"tags": [
"API",
"ADmanago"
],
"properties": {
"custom.nickname": "Konri2",
"custom.sex": "M"
},
"birthday": "19801017",
"province": "Małopolska"
}
],
"useApiDoubleOptIn": true,
"lang": "PL",
"fireEvents": false
}
Result of request:
{
"success":true,
"message":["Batch upsert added to execute."],
"requestId":37
}
Exemplary json with the batchupsert status:
{
"clientId": "yourclientID",
"apiKey": "yourAPIkey",
"requestTime": 1500556989,
"sha": "4afd12754c746fa9f71648f2e2276ae40eccfe41",
"owner": "admin@vendor.pl",
"requestId": 37
}
Exemplary response:
{
"success": true,
"message": [],
"fileUrl": "https://salesmanago.s3.amazonaws.com/ye4vodnswfo6zp75/36m0iryqk4wlt6wu/1bau18werv4ixk0d.json?AWSAccessKeyId=AKIAJS5TR7Z2ERLL5DIQ&Expires=1510133411&Signature=YUm1NsYMenpTdl4MC9cxDk%2Ba2nA%3D"
}
We add or modify many contacts at the same time using the below method:
https://www.salesmanago.pl/api/contact/batchupsertv2
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 new contact or modifying the existing contact).
Available fields in the request batchupsertv2 method:
| Field | Max. length | Description |
|---|---|---|
| owner* | 255 | contact’s owner (SALESmanago user account email) |
| email* | 255 | contact email |
| name | 255 | contact name |
| phone | 255 | phone number |
| fax | 255 | fax number |
| company | 255 | contact company |
| state | 255 | contact’s state (CUSTOMER, PROSPECT, PARTNER, OTHER, UNKNOWN) |
| externalId | 255 | External contact ID |
| newEmail | 255 | new contact’s email |
| birthday | yyyyMMdd/Mmdd | date of contact companybirth, 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 | 255 | contact’s province |
| streetAddress | 255 | street and house number |
| zipCode | 255 | zip code |
| city | 255 | town/city |
| country | 255 | country |
| forceOptOut | true/false | forcing opt-out after adding/modification |
| forceOptIn | true/false | forcing opt-in after adding/modification (if the previous option has not been chosen) |
| forcePhoneOptOut | true/false | forcing opt-out from a phone after adding/modification |
| forcePhoneOptIn | true/false | forcing opt-in to a phone after adding/modification (if the previous option has not been chosen) |
| tags | 255/tag | array of contact’s tags |
| removeTags | 255/tag | array of tags to be removed |
| properties | 255/detal | contact attributes defined by the user. It is advised not to use special characters and spaces in the name, but it is allowed |
| dictionaryProperties | - | user-defined attributes of the dictionary, the first to add a particular attribute can be used for the remaining contacts through re-enter the same name and type of the assigned another value. |
| name | 255 | name |
| type | NUMBER or DATE | type |
| value | - | integer greater than 0, for a DATE timestamp type, with the time set to 00:00:00 UTC time |
| useApiDoubleOptIn | true/false | use double opt-in option, default true |
| lang | 255 | contact language |
| fireEvents | true/false | If the method is set to “false” it prevents the rules and Workflows triggered by events created during the contact upsert (import with overwriting and modification of existing contacts) from launching |
For users with permissions to Contact relationship, we additionally have the following fields:
| Field | Max. length | Description |
|---|---|---|
| relation | - | creates a relationship with the specified contact |
| type | CHILD or PARENT | relation type |
| 255 | e-mail of the contact with whom the relationship is to be created, the given contact must already exist in the system |
In response, in “requestId” field, you will receive a number with which you can monitor the upsert status.
To check the process status, you need to send a request to:
https://www.salesmanago.pl/api/job/status
You need to give requestId as in example.
In response, you will receive either the message about the progress of the upsert or a link to the file with updated contacts.
Link is active for several minutes only.
success – boolean value informing about the result of request (successful/not successful)
contactIds – unique ID of the updated or newly added contact
message – array of additional information enabling error identification
invalidContacts – array of invalid contacts
For new contacts, the “newEmail” field will be ignored. New contacts will be assigned an address that matches the data in the field: “email.”
The useApiDoubleOptIn flag overrides the forceOptIn flag.
Using useApiDoubleOptIn together with forceOptIn will cause forceOptIn to be ignored.
Deleting many contacts simultaneously
Sample structure of request data:
{
"clientId": "your-client-id-123",
"apiKey": "your-api-key-123",
"requestTime": 1348046897664,
"sha": "8d893f41dd479bb0489686f04b0a169005d22559",
"owner": "admin@vendor.pl",
"contacts": [
{
"addresseeType": "stage",
"value": "funnel1",
"optValue": "stage1,stage2"
},
{
"addresseeType": "email",
"value": "email1@test.pl, email2@test.pl"
}
]
}
We delete many contacts at the same time using the below method:
https://www.salesmanago.pl/api/contact/batchDelete
Available fields in the request batchDelete method:
| Field | Max. length | Description |
|---|---|---|
| owner* | 255 | contact’s owner (SALESmanago user account email) |
| contacts* | - | array of contacts to delete |
| addresseeType* | 255 | addressing emails type ( EMAIL, CONTACT_ID, TAG, FUNNEL, STAGE) |
| value* | 255 | optional – contact email address, contact identifier, tag or funnel |
| optValue | 255 | list of funnel stages names separated by commas, optional for type STAGE |
Result of request:
{
"success":true,
"message":[],
"result": "Contacts deleted"
}
As a result of request we receive:
success – boolean value informing about the result of request (successful/not successful)
contactIds – array of additional information enabling error identification
result – result of request
Deleting a contact
Sample request data structure:
{
"apiKey" : "your-api-key-123",
"clientId" : "your-client-id-123",
"sha" : "08924f45afc2e4fb8b652c53cdb493c7ddb846a1",
"requestTime" : 1327059355361,
"email" : "test@salesmanago.pl",
"owner" : "admin@vendor.pl"
}
We delete a contact using the below method:
https://www.salesmanago.pl/api/contact/delete
Available fields in the request delete method:
| Field | Max. length | Description |
|---|---|---|
| owner* | 255 | contact’s owner (SALESmanago user account email) |
| email* | 255 | contact email |
Result of request:
{
"success": true,
"message": [],
"result": "Contact deleted"
}
As a result of request we receive:
success – boolean value informing about the result of request (successful/not successful)
message – array of additional information enabling error identification
result - additional information enabling error identification
Checking if a contact is already recorded
Sample request data structure:
{
"clientId": "client-id",
"apiKey": "api-key-123",
"requestTime": 1481532212995,
"sha": "abcd509ac6867955a5333d6eb0c460455c74ccc6",
"email": "***@gmail.com",
"owner": "admin@vendor.pl"
}
To check if a contact is already recorded in the database we use the below method:
https://www.salesmanago.pl/api/contact/hasContact
Available fields in the request hasContact method:
| Field | Max. length | Description |
|---|---|---|
| owner* | 255 | contact’s owner (SALESmanago user account email) |
| email* | 255 | contact’s email |
Result of request:
{
"success": true,
"message": [],
"result": true,
"contactId": "99cdc5fe-7376-436e-acb5-7180c97dadb6"
}
As a result of request we receive:
success – boolean value informing about the result of request (successful/not successful)
message – array of additional information enabling error identification
result - result of request
contactId - found ID contact
Export basic contacts’ data by email address
Sample request data structure:
{
"clientId": "client-id-123",
"apiKey": "api-key-123",
"requestTime": 1481533177752,
"sha": "abcd56045567955a533c74ccc6683d09ac6eb0c4",
"owner": "admin@vendor.pl",
"email": [
"piotr***@gmail.com"
]
}
The list of basic contacts data export by calling:
https://www.salesmanago.pl/api/contact/basic
Available fields in the request basic method:
| Field | Max. length | Description |
|---|---|---|
| owner* | 255 | contact’s owner (SALESmanago user account email) |
| email* | 255 | array of contacts email for the exported contacts |
Result of request:
{
"success": true,
"message": [],
"contacts": [
{
"name": "Piotr",
"email": "piotr****@gmail.com",
"phone": "500100100",
"fax": "",
"score": 1920,
"state": "PROSPECT",
"optedOut": false,
"optedOutPhone": false,
"deleted": false,
"invalid": false,
"company": "Benhauer",
"externalId": null,
"address": {
"streetAddress": "Grzegórzecka 21",
"zipCode": "30-555",
"city": "Kraków",
"country": "Polska"
},
"contactId": "99cdc5fe-7376-436e-acb5-7180c97dadb6",
"birthdayYear": null,
"birthdayMonth": null,
"birthdayDay": null,
"modifiedOn": 1479215570000,
"createdOn": 1432887727000,
"lastVisit": 1481528930000
}
]
}
success – information whether export was successful
message – array of additional information enabling error identification
contacts – exported contacts
name – contact name
email – contact email
phone – contact phone number
fax – contact’s fax number
score – number of points
state – contact’s state (CUSTOMER, PROSPECT, PARTNER, OTHER, UNKNOWN)
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 the contact is invalid
company – contact company name
externalId – contact external id
address – contact’s address
streetAddress – street and house number
zipCode – zip code
city – town/city
country – country
contactId - contact id
birthdayYear – contact birthday year
birthdayMonth – contact birthday month
birthdayDay – contact birthday day
modifiedOn – last contact update date
createdOn – contact creation date
lastVisit – last visit contact date
Export basic contacts’ data by contact ID
Sample request data structure:
{
"clientId": "client-id-123",
"apiKey": "api-key-123",
"requestTime": 1481535098734,
"sha": "abcd56045567955a533c74ccc6683d09ac6eb0c4",
"owner": "admin@vendor.pl",
"id": [
"99cdc5fe-7376-436e-acb5-7180c97dadb6"
]
}
The list of basic contacts data export by calling:
https://www.salesmanago.pl/api/contact/basicById
Available fields in the request basicById method:
| Field | Max. length | Description |
|---|---|---|
| owner* | 255 | contact’s owner (SALESmanago user account email) |
| id* | 255 | array of identifiers for the exported contacts |
Result of request:
{
"success": true,
"message": [],
"contacts": [
{
"name": "Piotr",
"email": "piotr****@gmail.com",
"phone": "500100100",
"fax": "",
"score": 1920,
"state": "PROSPECT",
"optedOut": false,
"optedOutPhone": false,
"deleted": false,
"invalid": false,
"company": "Benhauer",
"externalId": null,
"address": {
"streetAddress": "Grzegórzecka 21",
"zipCode": "30-555",
"city": "Kraków",
"country": "Polska"
},
"contactId": "99cdc5fe-7376-436e-acb5-7180c97dadb6",
"birthdayYear": null,
"birthdayMonth": null,
"birthdayDay": null,
"modifiedOn": 1479215570000,
"createdOn": 1432887727000,
"lastVisit": 1481528930000
}
]
}
success – information whether export was successful
message – array of additional information enabling error identification
contacts – exported contacts
name – contact name
email – contact email
phone – contact phone number
fax – contact’s fax number
score – number of points
state – contact’s state (CUSTOMER, PROSPECT, PARTNER, OTHER, UNKNOWN)
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 the contact is invalid
company – contact company name
externalId – contact external id
address – contact’s address
streetAddress – street and house number
zipCode – zip code
city – town/city
country – country
contactId - contact id
birthdayYear – contact birthday year
birthdayMonth – contact birthday month
birthdayDay – contact birthday day
modifiedOn – last contact update date
createdOn – contact creation date
lastVisit – last visit contact date
Forgetting a contact
Sample request data structure:
{
"apiKey": "our-api-key-123",
"clientId" : "your-client-id-123",
"sha" : "08924f45afc2e4fb8b652c53cdb493c7ddb846a1",
"requestTime" : 1327059355361,
"email" : "test@salesmanago.pl",
"owner" : "admin@vendor.pl"
}
We forget the contact using the method:
https://www.salesmanago.pl/api/contact/forget
A contact can be marked as forgotten.
Available fields in the request delete method:
| Field | Max. length | Description |
|---|---|---|
| email* | 255 | email address which will be forgotten |
| owner* | 255 | the owner of the contact (email address of the SALESmanago user) |
Result of request:
{
"success": true,
"message": [],
"result": "Contact forgotten"
}
As a result, you will receive:
success - boolean value informing about the result of the request (successful/not successful)
message - the array of additional information enabling error identification
result - the outcome of the process
Export based on email address for the owner
Sample structure of request data:
{
"apiKey" : "your-api-key-123",
"clientId" : "your-client-id-123",
"email" : [ "****@gmail.com" ],
"owner" : "admin@vendor.pl",
"requestTime" : 1329128188409,
"sha" : "02bfe70541d3907cf487f26dc2665b184b1221a7"
}
We export contacts using the below method:
https://www.salesmanago.pl/api/contact/list
Available fields in the request list method:
| Field | Max. length | Description |
|---|---|---|
| owner* | 255 | contact’s owner (SALESmanago user account email) |
| email* | 255 | array of contacts email for the exported contacts (** up to 50 contacts at once **) |
Result of request:
{
"success": true,
"message": [],
"contacts": [
{
"id": "99cdc5fe-7376-436e-acb5-7180c97dadb6",
"name": "Konrad",
"email": "your-contact-email@mail.com",
"phone": "123456789",
"fax": "987654321",
"score": 775,
"state": "PROSPECT",
"optedOut": true,
"optedOutPhone": false,
"deleted": false,
"invalid": false,
"company": "Benhauer",
"externalId": "externalId",
"address": {
"streetAddress": "Grzegórzecka 21",
"zipCode": "",
"city": "Kraków",
"country": "Polska"
},
"birthdayYear": 2000,
"birthdayMonth": 1,
"birthdayDay": 1,
"province": "Małopolska",
"mainContactOwner": "admin@vendor.pl",
"modifiedOn": 1479209074000,
"createdOn": 1432887727000,
"purchaseProbability": 0.3541016524943863,
"contactVisits": [
{
"conversationIntId": null,
"host": "10.10.10.10",
"time": 1328050810504,
"duration": null,
"visitSource": "NEXT",
"visitSourceHost": "salesmanago.pl",
"visitSourceKeywords": null,
"visitScore": 1,
"url": "/test.htm",
"location": null
}
],
"contactTags": [
{
"tag": "ADMANAGO",
"tagName": "ADMANAGO",
"score": 12,
"createdOn": 1432887757000,
"tagWithScore": "ADMANAGO (1)"
}
],
"contactEvents": [
{
"date": 1432887757000,
"description": "Note",
"detail1": null,
"detail2": null,
"detail3": null,
"detail4": null,
"detail5": null
}
],
"emailMessages": [
{
"name": "Email",
"subject": "Subject",
"date": 1479209121000,
"sent": false,
"dateSent": null,
"opened": false,
"dateOpened": null,
"clicked": false,
"dateClicked": null,
"emailConversation": 25584162,
"intId": null,
"deliveryStatus": null
}
],
"properties": [
{
"name": "detail",
"value": "detail-value"
}
],
"contactFunnels": [
{
"salesFunnel": "SalesFunnel 1",
"salesFunnelId": "5561397c-9792-4b60-aed1-a045b86c6b13",
"salesStage": "Stage",
"salesStageId": "de0cf594-b999-438a-b1f0-8578c36a8da5"
}
],
"contactNotes": [
{
"note": "Note",
"date": 1479208770000,
"priv": false
}
],
"contactTasks": [
{
"id": "395c5276-a40f-417c-bee8-1d6e80373adb",
"note": "Task",
"date": 1479250800000,
"cc": "",
"reminder": 1479249900000
}
],
"incomingEmailMessages": [
{
"subject": "Temat",
"date": 1479209971000
}
],
"contactExtEvents": [
{
"eventId": "bd2fd558-29da-49b7-be31-6ee551cd5e13",
"date": 1433449419000,
"description": "Cart",
"products": "7,6",
"location": null,
"value": 57.69,
"contactExtEventType": "CART",
"shopDomain":"shop.salesmanago.pl",
"detail1": null,
"detail2": null,
"detail3": null,
"detail4": null,
"detail5": null,
"detail6": null,
"detail7": null,
"detail8": null,
"detail9": null,
"detail10": null,
"detail11": null,
"detail12": null,
"detail13": null,
"detail14": null,
"detail15": null,
"detail16": null,
"detail17": null,
"detail18": null,
"detail19": null,
"detail20": null,
"externalId": null
}
],
"coupons": [
{
"name": "Coupon",
"coupon": "SB173",
"validTo": 1480245622000,
"used": false
}
],
"smsMessages": [
{
"createdDate": 1479209040000,
"dateSent": 1479209971000,
"dateDelivered": null,
"deliveryStatus": null,
"dateReplied": null,
"replayMsg": null,
"content": "Test",
"sentBy": "admin@vendor.pl"
}
],
"consents": [
{
"name": "ZGODA_1",
"description": "Description1",
"ip": "0:0:0:0:0:0:0:1",
"action": "A",
"createdOn": 1546730871000,
"source": "F",
"dateOn": 1546730873000
},
{
"name": "ZGODA_2",
"description": "Description2",
"ip": "0:0:0:0:0:0:0:1",
"action": "D",
"createdOn": 1546730871000,
"source": "C",
"dateOn": 1546730873000
},
{
"name": "ZGODA_3",
"description": "Description3",
"ip": "0:0:0:0:0:0:0:1",
"action": "R",
"createdOn": 1546730871000,
"source": "CC,",
"dateOn": 1546730873000
}
]
}
]
}
As a result of request we receive:
success – information whether export was successful
message – array of additional information enabling error identification
contacts – exported contacts
id – contact ID
name – contact name
email – contact email
phone – contact phone number
fax – contact’s fax number
score – number of points
state – contact’s state (CUSTOMER, PROSPECT, PARTNER, OTHER, UNKNOWN)
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 the contact is invalid
company – contact company name
externalId – contact external ID
address – contact’s address
streetAddress – street and house number
zipCode – zip code
city – town/city
country – country
birthdayYear – contact birthday year
birthdayMonth – contact birthday month
birthdayDay – contact birthday day
province - contact’s province
mainContactOwner – contact’s main contact owner ID
modifiedOn – last contact update date
createdOn – contact creation date
purchaseProbability – prediction value of purchase occurrence
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 - ntering from visit from an ad box (AdWords)
REFERRER - ntering 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
location - location
contactTags – contact tags
tag – tag text
tagName – tag name
score – tag score
createdOn – tag creation date
tagWithScore – tag name with score
contactEvents – events
date – date of event
description – event description
detail1-5 – event details
emailMessages – email messages
name – message name
subject – message subject
date – message creation date
sent – information if the email has been sent
dateSent – message sent date
opened – information if the email has been opened
dateOpened – message opened date
clicked – information if the email has been clicked
dateClicked – message clicked date
emailConversation – conversation ID
deliveryStatus – delivery status
properties – contact details
name – detail name
value – detail value
contactFunnels – contact sales funnels
salesFunnel – funnel name
salesFunnelId – funnel id
salesStage – funnel stage name
salesStageId – funnel stage ID
contactNotes - notes
note – note content
date – note creation date
priv – information if note is private
contactTasks – events
id – event ID
note – event content
date – event creation date
cc – crystal copy of email reminder
reminder – reminder date
incomingEmailMessages – incoming email messages
subject – incoming email message subject
date – incoming message planned delivery date
contactExtEvents – external events
eventId – external event ID
date – event date
description – event description
products – value of “product” field ( e.g. product ID’s)
location – localization
value – event value
contactExtEventType – event type
shopDomain – optional shop domain
detail1-20 – event detail (max 20)
externalId – event external ID
coupons - coupons
name – coupon name
coupon – string of coupon marks
validTo – coupon valid date
used – information if coupon has been used
smsMessages – sms messages
createdDate – message creation date
dateSent – message sent date
dateDelivered – message delivery date
deliveryStatus – delivery status
dateReplied – message reply date
replayMsg – reply content
content – message content
sentBy – email sender messages
consents - consents
name - consent name
description - consent description
ip - source ip from which the action was performed on a consent
action - A - consent confirmation, D - consent removal, R - consent rejection
createdOn - date of creation
dateOn - date of consent activation
source - source of consent - API - api, C - chat, F - form, CC - contact card
Export based on contact’s ID for the owner
Sample structure of request data:
{
"apiKey" : "your-api-key-123",
"clientId" : "your-client-id-123",
"contactId" : [ "123-XYZ" ],
"owner" : "admin@vendor.pl",
"requestTime" : 1329128188409,
"sha" : "02bfe70541d3907cf487f26dc2665b184b1221a7"
}
We export contacts using the below method:
https://www.salesmanago.pl/api/contact/listById
Available fields in the request listById method:
| Field | Max. length | Description |
|---|---|---|
| owner* | 255 | contact’s owner (SALESmanago user account email) |
| contactId* | 255 | array of identifiers for the exported contacts (** up to 50 contacts at once **) |
Request result is returned as JSON structure identical with the previous request.
Export based on email address
Sample structure of request data:
{
"apiKey" : "your-api-key-123",
"clientId" : "your-client-id-123",
"email" : [ "****@gmail.com" ],
"requestTime" : 1329128188409,
"sha" : "02bfe70541d3907cf487f26dc2665b184b1221a7"
}
Contacts by email address (regardless of the owner) export by calling:
https://www.salesmanago.pl/api/contact/listAll
Available fields in the request listAll method:
| Field | Max. length | Description |
|---|---|---|
| email* | 255 | array of contacts email for the exported contacts (** up to 50 contacts at once **) |
Request result is returned as JSON structure identical with the previous request.
Export based on contact’s ID
Sample structure of request data:
{
"apiKey" : "your-api-key-123",
"clientId" : "your-client-id-123",
"contactId" : [ "123-XYZ" ],
"requestTime" : 1329128188409,
"sha" : "02bfe70541d3907cf487f26dc2665b184b1221a7"
}
Contacts by email address (regardless of the owner) export by calling:
https://www.salesmanago.pl/api/contact/listAllById
Available fields in the request listAllById method:
| Field | Max. length | Description |
|---|---|---|
| contactId* | 255 | array of identifiers for the exported contacts (** up to 50 contacts at once **) |
Request result is returned as JSON structure identical with the previous request.
Export contacts’ data
Exemplary json:
{
"clientId": "yourcliendID",
"apiKey": "yourAPIkey",
"requestTime": 1500556989,
"sha": "4afd12754c746fa9f71648f2e2276ae40eccfe41",
"owner": "admin@vendor.pl",
"contacts" : [
{"addresseeType" : "tag", "value" : "TEST, TEST3"},
{"addresseeType" : "email", "value" : "test1@test.pl, test2@test.pl"},
{"addresseeType" : "stage", "value" : "funnel1", "optValue": "stage1"},
{"addresseeType" : "contact_id", "value" : "test123"}
],
"data": [
{"dataType" : "CONTACT"},
{"dataType" : "TAG"},
{"dataType" : "EXT_EVENT"},
{"dataType" : "VISITS"},
{"dataType" : "EMAILS"},
{"dataType" : "FUNNELS"},
{"dataType" : "NOTES"},
{"dataType" : "TASKS"},
{"dataType" : "COUPONS"},
{"dataType" : "SMS"},
{"dataType" : "PROPERTIES"},
{"dataType" : "DICTIONARY_PROPERTIES"}
]
}
Exemplary response:
{
"success": true,
"message": [
"Export added to execute."
],
"requestId": 37
}
Exemplary json with the export status:
{
"clientId": "yourclientID",
"apiKey": "yourAPIkey",
"requestTime": 1500556989,
"sha": "4afd12754c746fa9f71648f2e2276ae40eccfe41",
"owner": "admin@vendor.pl",
"requestId": 37
}
Exemplary response:
{
"success": true,
"message": [],
"fileUrl": "https://salesmanago.s3.amazonaws.com/ye4vodnswfo6zp75/36m0iryqk4wlt6wu/1bau18werv4ixk0d.json?AWSAccessKeyId=AKIAJS5TR7Z2ERLL5DIQ&Expires=1510133411&Signature=YUm1NsYMenpTdl4MC9cxDk%2Ba2nA%3D"
}
The example of the exported data structure:
[
{
"5bb84002-08ae-11e7-a63d-28d24400c116": {
"contactData": {
"email": "test.test@onet.pl",
"id": "5bb84002-08ae-11e7-a63d-28d24400c116",
"createdOn": 1489493057000,
"modifiedOn": 1489493303000,
"name": null,
"score": null,
"fax": null,
"state": "PROSPECT",
"optedOut": false,
"optedOutPhone": false,
"deleted": false,
"invalid": false,
"company": null,
"streetAddress": null,
"zipCode": null,
"city": null,
"country": null,
"birthday": null,
"province": null,
"mainOwner": null,
"lastOptInOn": 1634671777000,
"lastOptOutOn": 1634671197000
},
"tagData": [
{
"tagName": "TEST1",
"score": 1,
"createdOn": 1489493073000
},
{
"tagName": "LESZNO",
"score": 1,
"createdOn": 1489493317000
},
{
"tagName": "TEST3",
"score": 1,
"createdOn": 1489493316000
}
],
"extEventData": [
{
"eventId:": "dsakjl-fsdfsd-fsdfds-fsdf-awrew",
"date": 1523658987421,
"description": "description",
"products": "product1, product2, product3",
"location": "www.salesmanago.pl",
"value": "100.56",
"contactExtEventType": "CART",
"detail1": "online",
"detail2": null,
"detail3": null,
"externalId": "externalId"
}
],
"visitsData": [
{
"host": "salesmanago.pl",
"time": 1245874523658,
"duration": 200,
"visitSource": "www.salesmanago.pl",
"visitSourceHost": "salesmanago.pl",
"visitSourceKeywords": "salesmanago",
"visitScore": 10,
"url": "/cennik",
"location": "https://www.salesmanago.pl"
},
{
"host": "salesmanago.pl",
"time": 1245874523658,
"duration": 200,
"visitSource": "www.salesmanago.pl",
"visitSourceHost": "salesmanago.pl",
"visitSourceKeywords": "salesmanago",
"visitScore": 10,
"url": "/cennik",
"location": "https://www.salesmanago.pl"
}
],
"emailsData": [
{
"name": "#API: dyn",
"subject": "Sample API subject",
"date": 1497445747000,
"sent": false,
"dateSent": null,
"opened": false,
"dateOpened": null,
"clicked": false,
"dateClicked": null,
"emailConversation": null,
"deliveryStatus": null
}
],
"funnelsData": [
{
"salesFunnel": "lejek1",
"salesFunnelId": "fdshs-fdsfds-fdsfds-fdsfds",
"salesStage": "stage1",
"salesStageId": "iuyiuy-iuyiuy-iuyhvh-bvgbg"
}
],
"notesData": [
{
"note": "notatka dla kontatu",
"date": 1245854525698,
"priv": true
},
{
"note": "kupil produkt",
"date": 1245854525698,
"priv": false
}
],
"tasksData": [
{
"id": "ygfrg-fdfdf-fdfds-fsdfsd",
"note": "task dla kontaktu",
"date": 1452565898745,
"cc": "admin@vendor.pl",
"reminder": 1421524587456
}
],
"couponsData": [
{
"name": "coupon1",
"coupon": "couponCode",
"validTo": 1212452325658,
"used": false
}
],
"smsData": [
{
"createdDate": 1245214587452,
"dateSent": 1245214587452,
"dateDelivered": 1245214587452,
"deliveryStatus": "DELIVRD:00",
"dateReplied": null,
"replayMsg": null,
"content": "content",
"sentBy": null
}
]
}
},
{
"5e428789-08ae-11e7-a63d-28d24400c116": {
"contactData": {
"email": "test2@o2.pl",
"id": "5e428789-08ae-11e7-a63d-28d24400c116",
"createdOn": 1489493057000,
"modifiedOn": 1489493303000,
"name": null,
"score": null,
"fax": null,
"state": "PROSPECT",
"optedOut": false,
"optedOutPhone": false,
"deleted": false,
"invalid": false,
"company": null,
"streetAddress": null,
"zipCode": null,
"city": null,
"country": null,
"birthday": null,
"province": null,
"mainOwner": null,
"lastOptInOn": 1634671777000,
"lastOptOutOn": 1634671197000
},
"tagData": [
{
"tag": null,
"tagName": "TEST1",
"score": 1,
"createdOn": 1489493073000
},
{
"tag": null,
"tagName": "LESZNO",
"score": 1,
"createdOn": 1489493317000
},
{
"tag": null,
"tagName": "TEST2",
"score": 1,
"createdOn": 1489493316000
}
],
"extEventData": null,
"visitsData": null,
"emailsData": [
{
"name": "#API: dyn",
"subject": "Sample API subject",
"date": 1497445763000,
"sent": false,
"dateSent": null,
"opened": false,
"dateOpened": null,
"clicked": false,
"dateClicked": null,
"emailConversation": null,
"deliveryStatus": null
}
],
"funnelsData": null,
"notesData": null,
"tasksData": null,
"couponsData": null,
"smsData": null,
"consentsData": [
{
"name": "ZGODA_1",
"description": "Description1",
"ip": "0:0:0:0:0:0:0:1",
"action": "A",
"createdOn": "2018-10-22",
"source": "API",
"dateOn": "2018-10-22"
},
{
"name": "ZGODA_2",
"description": "Description2",
"ip": "0:0:0:0:0:0:0:1",
"action": "D",
"createdOn": "2018-10-22",
"source": "API",
"dateOn": "2018-10-22"
},
{
"name": "ZGODA_3",
"description": "Description3",
"ip": "0:0:0:0:0:0:0:1",
"action": "R",
"createdOn": "2018-10-22",
"source": "API",
"dateOn": "2018-10-22"
}
]
}
}
]
API method limits the scope of the exported data to information that is determined in the request. To specify the group of contacts for which you want to export data, use the shared selectors. Selectors function in the same way as in sending emails. Available selectors:
email - email address of a contact,
tag - name of the tag in the system assigned to a contact or contact groups,
contact_id - external contact identifier,
funnel - name of the sales funnel,
stage - name of the stage in the sales funnel (then you need to specify the name of the funnel and the name of the
funnel stage which contacts are currently at).
The scope of data to export includes:
CONTACT - basic information about a contact such as the name of the contact, email address, telephone number, etc.,
TAG - list of tags assigned to a contact,
EXT_EVENT - list of contact’s external events (e.g. cart, purchase),
VISITS - number of websites visited by a contact during last 7 days,
EMAILS - list of emails sent to a contact and email analytics (information whether contact opened the email, date,
etc.),
FUNNELS - list of sales funnels to which a contact is assigned,
NOTES - list of notes assigned to a contact,
TASKS - list of tasks assigned to a contact,
COUPONS - list of coupons,
SMS - list of the text messages sent to a contact and analytics (information whether contact received the message,
date, etc.).
CONSENTS - list of consents (A - accepted, D - deleted, R - rejected)
PROPERTIES - contact attributes defined by the user. It is advised not to use special characters and spaces in the name, but it is allowed
DICTIONARY_PROPERTIES - user-defined attributes of the dictionary, the first to add a particular attribute can be used for the remaining contacts through re-enter the same name and type of the assigned another value.
You need to choose at least one type of data to export (e.g. tag, contact, funnel). Data types are not codependent hence each type of data can be exported separately. Exported data is available in the json file under the shared link.
Below you can find address to which you need to send an export request.
https://www.salesmanago.pl/api/contact/export/data
In “contact” you need to give a list of contacts which data you want to export. In “data” you need to give a list of data type which you want to export.
In response, you will receive a number with which you can monitor the export status.
“requestId” is the identifier of the export.
To check the export status, you need to send a request to:
https://www.salesmanago.pl/api/job/status
You need to give requestId that was sent in the response with the number to monitor the export status.
In response, you will receive either the message about the progress of the export or a link to the file with exported contact data.
Link is active for several minutes only.
Exporting the list of recently created contacts
Sample request data structure:
{
"clientId": "h4jsu6pc5txybj04",
"apiKey": "qwetreryuii",
"requestTime": 1481531514145,
"sha": "abcd509ac6eb0c460455c74ccc66867955a5333d",
"owner": "admin@vendor.pl",
"from": 1478939514146,
"to": 1481531514132
}
We export contacts using the below method:
https://www.salesmanago.pl/api/contact/createdContacts
Available fields in the request createdContacts method:
| Field | Max. length | Description |
|---|---|---|
| owner* | 255 | contact’s owner (SALESmanago user account email) |
| from* | 255 | beginning range of creation dates |
| to* | 255 | ending range of creation dates |
Result of request:
{
"success": true,
"message": [],
"createdContacts": [
{
"id": "c3477890-3da7-4010-96d0-45aab0586b7f",
"email": "***@gmail.com"
}
]
}
As a result of request we receive:
success – boolean value informing about the result of request (successful/not successful)
message – array of additional information enabling error identification
createdContacts – contacts modified in the given time frame
id – contact’s ID
email – contact’s email
Exporting the list of recently modified contacts
Sample structure of request data:
{
"apiKey" : "your-api-key-123",
"clientId" : "your-client-id-123",
"requestTime":1362056589362,
"sha":"64656d78b80d5df677700dabd363e1ffe51b59a7",
"owner":"admin@vendor.pl",
"from":1359673200361,
"to":1363042800362
}
We export contacts using the below method:
https://www.salesmanago.pl/api/contact/modifiedContacts
Available fields in the request modifiedContacts method:
| Field | Max. length | Description |
|---|---|---|
| owner* | 255 | contact’s owner (SALESmanago user account email) |
| from* | 255 | beginning range of modification dates |
| to* | 255 | ending range of modification dates |
Result of request:
{
"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"
}
]
}
As a result of request we receive:
success – boolean value informing about the result of request (successful/not successful)
message – array of additional information enabling error identification
modifiedContacts – contacts modified in the given time frame
id – contact’s ID
email – contact’s email
Paginated modified contacts list
Maximum time difference between fields ‘from’ and 'to’ is 30 days
Sample structure of request data:
{
"clientId": "jaco",
"apiKey": "jaco",
"requestTime": 1481206581347,
"sha": "627e5189c02a73bb37dd660caefb8a75c5b128b3",
"owner": "admin@admin.pl",
"from" : 0,
"to": 100000000000000,
"page" : 1,
"size" : 2
}
The request returns a paged contact list. We use the below method:
https://www.salesmanago.pl/api/contact/paginatedModifiedContacts
Available fields in the request paginatedModifiedContacts method:
| Field | Max. length | Description |
|---|---|---|
| clientId* | - | user id |
| apiKey* | - | API key |
| sha* | - | generated sha |
| owner* | - | user email |
| requestTime* | - | time the request was made (ms) |
| from* | - | modification date (ms), from which contacts will be searched |
| to* | - | modification date (ms), to which contacts will be searcged |
| page* | - | currently returned result page |
| size* | 1000 | size of returned result page |
Result of request:
{
"success": true,
"message": [],
"modifiedContacts": [
{
"id": "c10019fd-58f2-4a3b-8461-524dc9e8298c",
"email": "jaco@jaco.pl"
},
{
"id": "d256329b-736b-11e7-b8f0-f07959164fe8",
"email": "test.mokrysz+2073importdataurodzin@gmail.com"
}
],
"hasMore": true
}
Result of request:
hasMore – (boolean value) informs if there are more result pages available
modifiedContacts – array of contact objects containing 'id’ and 'name’
id – contact identifier
email – contact email
Contacts’ activity
Sample structure of request data:
{
"apiKey" : "your-api-key-123",
"clientId" : "your-client-id-123",
"requestTime" : 1329128188409,
"sha" : "02bfe70541d3907cf487f26dc2665b184b1221a7",
"from":1328050800504,
"to":1333231200504,
"allVisits":true,
"ipDetails":true
}
We can obtain information about the activity of contacts in a given period from SALESmanago. To do this we use the below method:
https://www.salesmanago.pl/api/contact/recentActivity
Available fields in the request recentActivity method:
| Field | Max. length | Description |
|---|---|---|
| from* | 255 | beginning date (timestamp, i.e. time in milliseconds that passed from midnight 1 January 1970 UTC) |
| to* | 255 | ending date (timestamp, i.e. time in milliseconds that passed from midnight 1 January 1970 UTC) |
| allVisits | true/false | if set at true, SALESmanago will return in visit details information about all pages opened by the customer in a given period |
| ipDetails | true/false | if set at true, SALESmanago will return in visit details additional information searched for client IP |
Result of request:
{
"success":true,
"message":[],
"recentActivities": {
"from":1328050800504,
"to":1333231200504,
"monitoredContacts": 12300,
"totalContacts":234000,
"customers":[{
"uuid": 191615173,
"time":1330239675000,
"duration":22000,
"visitSource":"REFERRER",
"visitSourceHost":null,
"visitSourceKeywords":"localhost",
"visitSourceDetails":null,
"visitScore":120,
"client":"Benhauer Sp. z o.o. Sp. K. - Konrad Pawlus",
"email":"konradpawlus@gmail.com",
"contactId":"1d8cba47-f4b2-4efe-8250-5bdab5346628",
"url": "/test.htm",
"ipOrganization": "TP SA",
"vid": 7,
"cid": null,
"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": [{ "conversationIntId": null,
"host": "10.10.10.10",
"time": 1328050810504,
"duration": null,
"visitSource": "NEXT",
"visitSourceHost": "salesmanago.pl",
"visitSourceKeywords": null,
"visitScore": 1,
"url": "/test.htm",
"location": null
}]}],
"partners":["... jw. ..."],
"prospects":["... jw. ..."],
"anonymous":["... jw. ..."],
"allVisits":["... jw. ..."],
"visitStats": [
{
"date": 1330239675000,
"partnersVisits": 123,
"prospectsVisits": 234,
"customersVisits": 456,
"otherVisits": 4321
}
]
}
}
As a result of request we receive:
success – boolean value informing about the result of request (successful/not successful)
message – array of additional information enabling error identification
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
allVisits – list of all visits
element of client’s visit in lists:
time – time of visit
duration – duration
visitSource – visit resources
visitSourceKeywords – key words
visitSourceHost – host
visitSourceDetails – visit details
visitScore – number of points
url – URL of visited page
client – client name
email – client’s email
contactId – unique client’s ID
vid - vendor ID
cid - contact ID
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
conversationIntId – conversation ID
host – page that was visited
time – time of visit
duration – duration
visitSource – visit’s resources
visitSourceKeywords – key words
visitSourceHost – host
visitScore – number of points
url – URL of visited page
location – visit location
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
Paginated contacts list export
Sample structure of request data:
{
"clientId": "clientId",
"apiKey": "api-key-123",
"requestTime": 1481206581347,
"sha": "5333dabcd509455c74ccc6ac6eb0c4606867955a",
"owner": "admin@vendor.pl",
"page": 1,
"size": 100
}
In response, you will receive a number with which you can monitor the export status. We use the below method:
https://www.salesmanago.pl/api/contact/paginatedContactList/export
Available fields in the request paginatedContactListExport method:
| Field | Max. length | Description |
|---|---|---|
| owner* | 255 | contact’s owner (SALESmanago user account email) |
| page* | - | current page |
| size* | - | the number of returned lines (up to 1000) |
Result of request:
{
"success": true,
"message": [
"Export added to execute."
],
"requestId": 37
}
success – boolean value informing about the result of request (successful/not successful)
message – array of additional information enabling error identification
requestId – the identifier of the export
In response, you will receive “requestId”, which is the export id.
To check the process status, you need to send a POST request to: https://www.salesmanago.pl/api/job/status
You need to give requestId (output of previous method), which contains number to check the status of export.
In response, you will receive either the message about the progress of the export or a link to the file with exported contacts.
Link is active for several minutes only.
Sample structure of request /api/job/status:
{
"clientId": "yourclientID",
"apiKey": "yourAPIkey",
"requestTime": 1500556989,
"sha": "4afd12754c746fa9f71648f2e2276ae40eccfe41",
"owner": "admin@vendor.pl",
"requestId": 123
}
Result of request
{
"success": true,
"message": [],
"fileUrl": "https://salesmanago.s3.amazonaws.com/notrealdata/notrealdata/notrealdata.json"
}
Paginated contacts list for provided owner
Sample structure of request data:
{
"clientId": "jaco",
"apiKey": "jaco",
"requestTime": 1481206581347,
"sha": "627e5189c02a73bb37dd660caefb8a75c5b128b3",
"owner": "admin@admin.pl",
"page": 1,
"size": 2
}
The request returns a paged contact list. We use the below method:
https://www.salesmanago.pl/api/contact/paginatedListById
Available fields in the request paginatedListById method:
| Field | Max. length | Description |
|---|---|---|
| clientId* | - | user id |
| apiKey* | - | API key |
| sha* | - | generated sha |
| owner* | - | user email |
| requestTime* | - | time the request was made (ms) |
| page* | - | currently returned result page |
| size* | 1000 | size of returned result page |
Result of request:
{
"success": true,
"message": [],
"contacts": [
{
"id": "c10019fd-58f2-4a3b-8461-524dc9e8298c",
"name": "jac jacek",
"email": "jaco@jaco.pl",
"phone": null,
"fax": null,
"score": 0,
"state": "PROSPECT",
"optedOut": false,
"optedOutPhone": false,
"deleted": false,
"invalid": false,
"company": null,
"externalId": null,
"address": null,
"birthdayYear": null,
"birthdayMonth": null,
"birthdayDay": null,
"province": "",
"mainContactOwner": "admin@admin.pl",
"contactVisits": [],
"contactTags": [
{
"tag": "TAG",
"tagName": "TAG",
"score": 1,
"createdOn": 1500625819000,
"tagWithScore": "TAG (1)"
}
],
"contactEvents": [],
"emailMessages": [],
"properties": [],
"contactFunnels": [],
"contactNotes": [],
"contactTasks": [
{
"id": "f5ada145-ebc8-4be0-bad5-3df34f3cfecd",
"note": "",
"date": 1499378400000,
"cc": "",
"reminder": 1499377500000
},
{
"id": "708aa28a-fd6a-44ea-9652-b88cf73496d4",
"note": "",
"date": 1499378400000,
"cc": "xyz@xyz.xyz",
"reminder": 1499376600000
}
],
"incomingEmailMessages": [],
"contactExtEvents": [],
"coupons": [],
"smsMessages": [],
"modifiedOn": 1500626587000,
"createdOn": 1500559084000
},
{
"id": "d256329b-736b-11e7-b8f0-f07959164fe8",
"name": "test.mokrysz+2073importdataurodzin@gmail.com",
"email": "test.mokrysz+2073importdataurodzin@gmail.com",
"phone": null,
"fax": null,
"score": 0,
"state": "PROSPECT",
"optedOut": false,
"optedOutPhone": false,
"deleted": false,
"invalid": false,
"company": null,
"externalId": null,
"address": null,
"birthdayYear": "1985",
"birthdayMonth": "5",
"birthdayDay": "30",
"province": "",
"mainContactOwner": "admin@admin.pl",
"contactVisits": [],
"contactTags": [],
"contactEvents": [],
"emailMessages": [],
"properties": [],
"contactFunnels": [],
"contactNotes": [],
"contactTasks": [],
"incomingEmailMessages": [],
"contactExtEvents": [],
"coupons": [],
"smsMessages": [],
"modifiedOn": 1501229258000,
"createdOn": 1501229258000
}
],
"hasMore": true
}
Result of request:
hasMore – (boolean value) informs if there are another result pages avaiable
Request result is returned as JSON structure identical with the previous request.
Changing the main contact owner
Sample request data structure:
{
"clientId": "your-client-id-123",
"apiKey": "your-api-key-123",
"requestTime": "1327056031488",
"sha": "2aa3927a7dee8c2a712adb5375f5fa36dd8fe00c",
"contact": "contact@email.com",
"owner": "Owner@email.com",
"newOwner": "newOwner@email.com"
}
We set new owner using the below method:
https://www.salesmanago.pl/api/contact/setMainOwner
Available fields in the request setMainOwner method:
| Field | Max. length | Description |
|---|---|---|
| contact* | 255 | contact’s email |
| owner* | 255 | contact’s owner |
| newOwner* | 255 | new contact’s owner (SALESmanago user account email) |
Result of request:
{
"success": true,
"message": []
}
As a result of request we receive:
success – boolean value informing about the result of request (successful/not successful)
message – array of additional information enabling error identification
Stop contacts’ monitoring
Sample request data structure:
{
"clientId": "ye4vodnswfo6zp75",
"apiKey": "12345trewq",
"async": false,
"requestTime": 1512720868000,
"sha": "36ec9c925975fa077aa39660386e41de3e25349a",
"owner": "admin@vendor.pl",
"contacts" : [
{"addresseeType" : "email", "value" : "test2@test.pl"}
]
}
In order to stop monitoring contacts through API the below method should be used:
https://www.salesmanago.pl/api/contact/stopMonitoring
Available fields in the request stopMonitoring method:
| Field | Max. length | Description |
|---|---|---|
| owner* | 255 | contact’s owner (SALESmanago user account email) |
| contacts* | - | array of contacts |
Result of request:
{
"success": true,
"message": [
"Contacts have stopped being monitored."
]
}
As a result of request we receive:
success – boolean value informing about the result of request (successful/not successful)
message – array of additional information enabling error identification
Restore contacts’ monitoring
Sample request data structure:
{
"clientId": "ye4vodnswfo6zp75",
"apiKey": "12345trewq",
"async": false,
"requestTime": 1512720868000,
"sha": "36ec9c925975fa077aa39660386e41de3e25349a",
"owner": "admin@vendor.pl",
"contacts" : [
{"addresseeType" : "email", "value" : "test2@test.pl"}
]
}
In order to restore monitoring of contacts via API the following method should be used:
https://www.salesmanago.pl/api/contact/restoreMonitoring
Available fields in the request restoreMonitoring method:
| Field | Max. length | Description |
|---|---|---|
| owner* | 255 | contact’s owner (SALESmanago user account email) |
| contacts* | - | array of contacts |
Result of request:
{
"success": true,
"message": [
"Contacts have restored being monitored."
]
}
As a result of request we receive:
success – boolean value informing about the result of request (successful/not successful)
message – array of additional information enabling error identification
API - Managing discount coupons
Redemption of coupon for contact
Sample request data structure:
{
"apiKey" : "your-api-key-123",
"clientId" : "your-client-id-123",
"sha" : "08924f45afc2e4fb8b652c53cdb493c7ddb846a1",
"requestTime" : 1327059355361,
"email" : "test@salesmanago.pl",
"coupon" : "SAMPLE-COUPON-123"
}
You can redeem coupon via API method call:
https://www.salesmanago.pl/api/contact/useContactCoupon
Available fields in the request useContactCoupon method:
| Field | Max. length | Description |
|---|---|---|
| email* | 255 | contact email |
| coupon* | 255 | coupon name |
Result of request:
{
"success": true,
"message": [],
"result": null
}
As a result of request we receive:
success – boolean value informing about the result of request (successful/not successful)
message – array of additional information enabling error identification
result - result of method call is used/error depending on success or failure of given call
Adding coupon for contact
Sample request data structure:
{
"clientId": "client-id",
"apiKey": "api-key-123",
"requestTime": 1481528920123,
"sha": "abcd5460455c09ac6eb0c74cc333dc66867955a5",
"name": "Coupon123",
"email": "***@gmail.com",
"length": 7,
"valid": 1484207320124,
"coupon": "couponVal"
}
You can add coupon via API method call:
https://www.salesmanago.pl/api/contact/addContactCoupon
Available fields in the request addContactCoupon method:
| Field | Max. length | Description |
|---|---|---|
| email* | 255 | contact email |
| name* | 64 | coupon name |
| length** | - | length of coupon in case of automatic generation (the value from 5 to 64) |
| valid | - | expiration date of coupon (timestamp in miliseconds), by default: year and a day |
| coupon** | 32 | value of coupon in case of manual input (5 characters minimum) |
**Only one of these fields is mandatory.
Result of request:
{
"success": true,
"message": [],
"result": null,
"coupon": "couponVal"
}
As a result of request we receive:
success – boolean value informing about the result of request (successful/not successful)
message – array of additional information enabling error identification
result - result of request
coupon - created coupon value
API - Funnels
Adding funnel
Sample structure of request data:
{
"clientId": "clientId",
"apiKey": "apiKey",
"requestTime": 1234567896541,
"sha": "4f69782e826841f794080cae87648e42",
"owner": "owner@mail.com",
"funnel": "funnel_name",
"group": "funnel group",
"potValue": 4,
"stages" : [
{"name": "stage name", "order": 1},
{"name": "second stage name", "order": 2}
]
}
To add funnels, use the method:
https://www.salesmanago.pl/api/funnel/add
Available fields in the add method request:
| Field | Max. length | Description |
|---|---|---|
| clientId* | - | user id |
| apiKey* | - | API key |
| requestTime* | - | time the request was made (ms) |
| sha* | - | generated sha |
| owner* | - | user email |
| funnel* | - | name of funnel |
| group | - | group funnel |
| potValue | - | default value of contacts |
| stages* | - | list of funnel stages |
| name* | 255 | funnel stage name (min. 3 characters) |
| order* | - | the sequence of stages (min. value 1, the values of the sequence should form a sequence of 1,2,3…number of stages) |
Result of request:
{
"success": true,
"message": [
"Funnel funnel_name was added."
]
}
As a result of request we receive:
success – boolean value informing about the result of request (successful/not successful)
message – array of additional information
Adding contacts to the funnel
Sample structure of request data:
{
"clientId": "ye4vodnswfo6zp75",
"apiKey": "qwertgfdsa1234",
"requestTime": 1496399754907,
"sha": "07f7333f11745f30e1bd5adec2092d89ab2f00a7",
"owner": "owner@mail.com",
"funnel": "funnel_name",
"stage": "stage name",
"potValue": 4,
"modify": true,
"contacts": [
{"addresseeType": "EMAIL",
"value": "test1@test.pl, test2@test.pl, test3@test.pl"
}
]
}
To add contact to funnels, use the method:
https://www.salesmanago.pl/api/funnel/addContact
Available fields in the addContact method request:
| Field | Max. length | Description |
|---|---|---|
| clientId* | - | user id |
| apiKey* | - | API key |
| requestTime* | - | time the request was made (ms) |
| sha* | - | generated sha |
| owner* | - | user email |
| funnel* | - | name of funnel |
| stage* | - | name of stage |
| potValue | - | default value of contacts |
| modify | - | (boolean value) the contact is to be marked as modified when added to the funnel default false |
| contacts* | - | the email address of the contact, its ID, tag or funnel |
Result of request:
{
"success":true,
"message":[],
"addedContacts": {
"07381ccd-8d0f-4458-89d9-58ed23634209": true,
"bd7bd136-3702-401c-8b4a-3a40dd7546d8": true,
"e4743be9-24ed-4d23-b032-b7c68f0a660b": true,
"e99d6439-2191-4c55-9116-12b9bc63fa93": true,
"5b45e6bc-72ea-45bc-8d61-985e9066bd3a": true
}
}
As a result of request we receive:
success – boolean value informing about the result of request (successful/not successful)
message – array of additional information
Deleting funnel/stage
Sample structure of request data:
{
"clientId": "clientId",
"apiKey": "apiKey",
"requestTime": 1234567896541,
"sha": "4f69782e826841f794080cae87648e42",
"owner": "owner@mail.com",
"funnel": "funnel_name",
"stage": "stage name"
}
To delete funnels, use the method:
https://www.salesmanago.pl/api/funnel/delete
Available fields in the delete method request:
| Field | Max. length | Description |
|---|---|---|
| clientId* | - | user id |
| apiKey* | - | API key |
| requestTime* | - | time the request was made (ms) |
| sha* | - | generated sha |
| owner* | - | user email |
| funnel* | - | name of funnel |
| stage | - | name of stage |
stage - optional parameter - when empty, the method removes the entire funnel when the completed deletes the selected stage in the funnel
Result of request:
{
"success": true,
"message": [
"Specified funnel stage will be deleted in a few seconds"
]
}
As a result of request we receive:
success – boolean value informing about the result of request (successful/not successful)
message – array of additional information
Getting the number of contacts in the funnel/stage
Sample structure of request data:
{
"clientId": "clientId",
"apiKey": "apiKey",
"requestTime": 1234567896541,
"sha": "4f69782e826841f794080cae87648e42",
"owner": "owner@mail.com",
"funnel": "funnel_name",
"stage": "stage name"
}
To get count of contact, use the method:
https://www.salesmanago.pl/api/funnel/count
Available fields in the count method request:
| Field | Max. length | Description |
|---|---|---|
| clientId* | - | user id |
| apiKey* | - | API key |
| requestTime* | - | time the request was made (ms) |
| sha* | - | generated sha |
| owner* | - | user email |
| funnel* | - | name of funnel |
| stage | - | name of stage |
stage - optional parameter - when empty, the method returns the number of contacts across the funnel when the complement returns the number in the selected step
Result of request:
{
"success": true,
"message": [],
"count": 123
}
As a result of request we receive:
success – boolean value informing about the result of request (successful/not successful)
message – array of additional information
count – number of contacts in the funnel/stage
API - Managing mailing list (Opt-in / Opt-out)
Unsubscribing a contact from the list (Opt-out)
Sample structure of request data:
{
"apiKey" : "your-api-key-123",
"clientId" : "your-client-id-123",
"requestTime" : 1329128188409,
"sha" : "02bfe70541d3907cf487f26dc2665b184b1221a7",
"email" : "john.doe@email.com",
"contactId": "21c252a6-6de0-436b-bae8-9d0142363266"
}
We unsubscribe a contact from the mailing list using the below method:
https://www.salesmanago.pl/api/contact/optout
Available fields in the request optout method:
| Field | Max. length | Description |
|---|---|---|
| email* | 255 | contact’s email (can be used as alternative for contactId) |
| contactId* | 255 | contact’s identifier (can be used as alternative for contact email) |
Result of request:
{
"contactId" : "21c252a6-6de0-436b-bae8-9d0142363266",
"message" : [ ],
"success" : true
}
As a result of request we receive:
success – boolean value informing about the result of request (successful/not successful)
contactId – unique ID of the updated or newly added contact
message – array of additional information enabling error identification
Adding a contact to the list (Opt-in)
Sample structure of request data:
{
"apiKey" : "your-api-key-123",
"clientId" : "your-client-id-123",
"requestTime" : 1329128188409,
"sha" : "02bfe70541d3907cf487f26dc2665b184b1221a7",
"email" : "konrad-test-optout-1@konri.com",
"contactId": "21c252a6-6de0-436b-bae8-9d0142363266"
}
We add a contact to the mailing list using the below method:
https://www.salesmanago.pl/api/contact/optin
Available fields in the request optin method:
| Field | Max. length | Description |
|---|---|---|
| email* | 255 | contact’s email |
| contactId* | 255 | contact’s identifier (can be used as alternative for contact email) |
Result of request:
{
"contactId" : "21c252a6-6de0-436b-bae8-9d0142363266",
"message" : [ ],
"success" : true
}
As a result of request we receive:
success – boolean value informing about the result of request (successful/not successful)
contactId – unique ID of the updated or newly added contact
message – array of additional information enabling error identification
Mass unsubscribing contacts from the list (Opt-out)
Sample structure of request data:
{
"apiKey" : "your-api-key-123",
"clientId" : "your-client-id-123",
"requestTime" : 1329128188409,
"sha" : "02bfe70541d3907cf487f26dc2665b184b1221a7",
"emails" : [
"batchtest2@benhauer.pl", "batchtest1@benhauer.pl"
]
}
We unsubscribe mass contacts from the mailing list using the method below:
https://www.salesmanago.pl/api/contact/batchoptout
Available fields in the request batchoptout method:
| Field | Max. length | Description |
|---|---|---|
| emails* | 255/email | array of contacts email |
Result of request:
{
"success":true,
"message":[],
"contactIds":{
"batchtest2@benhauer.pl":"b257d328-2a95-41ce-915a-94b4274e6c29",
"batchtest1@benhauer.pl":"bf4d6c03-1ca2-4b3f-8131-c28829236b02"
}
}
As a result of request we receive:
success – boolean value informing about the result of request (successful/not successful)
contactIds – unique IDs of updated contacts
message – array of additional information enabling error identification
Adding mass contacts to the list (Opt-in)
Sample structure of request data:
{
"apiKey" : "your-api-key-123",
"clientId" : "your-client-id-123",
"requestTime" : 1329128188409,
"sha" : "02bfe70541d3907cf487f26dc2665b184b1221a7",
"emails" : [
"batchtest2@benhauer.pl", "batchtest1@benhauer.pl"
]
}
We add mass contacts to the mailing list by using the below method:
https://www.salesmanago.pl/api/contact/batchoptin
Available fields in the request batchoptin method:
| Field | Max. length | Description |
|---|---|---|
| emails* | 255/email | array of contacts email |
Result of request:
{
"success":true,
"message":[],
"contactIds":{
"batchtest2@benhauer.pl":"b257d328-2a95-41ce-915a-94b4274e6c29",
"batchtest1@benhauer.pl":"bf4d6c03-1ca2-4b3f-8131-c28829236b02"
}
}
As a result of request we receive:
success – boolean value informing about the result of request (successful/not successful)
contactIds – unique IDs of updated contacts
message – array of additional information enabling error identification
Adding a contact to the phone list (Opt-in phone)
Sample structure of request data:
{
"apiKey" : "your-api-key-123",
"clientId" : "your-client-id-123",
"requestTime" : 1329128188409,
"sha" : "02bfe70541d3907cf487f26dc2665b184b1221a7",
"email" : "konrad-test-optout-1@konri.com"
}
We add a contact by using below method:
https://www.salesmanago.pl/api/contact/phoneoptin
Available fields in the request phoneoptin method:
| Field | Max. length | Description |
|---|---|---|
| email* | 255 | contact’s email |
Result of request:
{
"contactId" : "21c252a6-6de0-436b-bae8-9d0142363266",
"message" : [ ],
"success" : true
}
As a result of request we receive:
success – boolean value informing about the result of request (successful/not successful)
contactId – unique ID of the updated or newly added contact
message – array of additional information enabling error identification
Unsubscribing a contact from the phone list (Opt-out phone)
Sample structure of request data:
{
"apiKey" : "your-api-key-123",
"clientId" : "your-client-id-123",
"requestTime" : 1329128188409,
"sha" : "02bfe70541d3907cf487f26dc2665b184b1221a7",
"email" : "john.doe@email.com",
"contactId": "21c252a6-6de0-436b-bae8-9d0142363266"
}
We unsubscribe a contact from the list using below method:
https://www.salesmanago.pl/api/contact/phoneoptout
Available fields in the request phoneoptout method:
| Field | Max. length | Description |
|---|---|---|
| email* | 255 | contact’s email |
| contactId* | 255 | contact’s identifier (can be used as alternative for contact email) |
Result of request:
{
"contactId" : "21c252a6-6de0-436b-bae8-9d0142363266",
"message" : [ ],
"success" : true
}
As a result of request we receive:
success – boolean value informing about the result of request (successful/not successful)
contactId – unique ID of the updated or newly added contact
message – array of additional information enabling error identification
API - 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. Before adding an external event, the contact has to already be in SALESmanago.
Adding an external event (deprecated)
Sample structure of request recording a new event:
{
"clientId": "your-client-id-123",
"apiKey": "your-api-key-123",
"requestTime": 1356180568127,
"sha": "3e4ec39722326150aae60f41e038d1def4450f46",
"owner": "admin@vendor.pl",
"email": "konrad@benhauer.com",
"forceOptIn": true,
"sendTransactionalEmail": true,
"transactionalEmailTemplateId": "template-id",
"transactionalEmailAccountId": "emial-acount-id",
"transactionalEmailSubject": "subject",
"contactEvent": {
"date": 1356180568153,
"description": "Zakup z kartą \"Super Bonus\"",
"products": "p01, p02",
"location": "Shop_ID",
"value": 1234.43,
"contactExtEventType": "PURCHASE",
"detail1": "C.ID: *** *** 234",
"detail2": "Płatość kartą",
"detail3": null,
"externalId": "A-123123123",
"shopDomain": "shop.salesmanago.pl"
}
}
In order to add an event we use the below method:
https://www.salesmanago.pl/api/contact/addContactExtEvent
Available fields in the request addContactExtEvent method:
| Field | Max. length | Description |
|---|---|---|
| owner* | 255 | contact’s owner (SALESmanago user account email) |
| email*/contactId* | 255 | contact’s email for which the event is added |
| forceOptIn | true/false | value true will create contact as opt-in |
| sendTransactionalEmail | true/false | value true will sent transactional email |
| transactionalEmailTemplateId | 255 | transactional email template identifier |
| transactionalEmailAccountId | 255 | email account identifier from which transaction email will be sent |
| transactionalEmailSubject | 255 | transactional email subject |
| date* | timestamp | event date (timestamp, i.e. time in milliseconds that passed from midnight 1 January 1970 UTC) |
| description | 2048 | event description |
| products | 512 | optional list of products separated by commas |
| E-shop ID (location) | 36 | unique shop identifier – this identifier is used to connect information about the product sent in the external event with a particular product feed. Maximum number of characters without spaces is 36 (possible characters: letters a-z, numbers 1-9, /_-.). Unique shop identifier has to be exactly the same as the value in the LOCATION field in external events sent from a particular shop. IMPORTANT: If you have only one product feed, the system will connect an external event and the product feed that you have in the system automatically. When you use multistore option, remember about coherence in sending external events with a unique identifier. |
| value | (19 2) | optional event value eg. amount spent (max 19 digits + 2 after the decimal point) |
| contactExtEventType* | 255 | event type, possible values: PURCHASE, CART, VISIT, PHONE_CALL, OTHER, RESERVATION, CANCELLED, ACTIVATION, MEETING, OFFER, DOWNLOAD, LOGIN, TRANSACTION, CANCELLATION, RETURN, SURVEY, APP_STATUS, APP_TYPE_WEB, APP_TYPE_MANUAL, APP_TYPE_RETENTION, APP_TYPE_UPSALE, LOAN_STATUS, LOAN_ORDER, FIRST_LOAN, REPEATED_LOAN |
| detail1-20 | 255/detal | optional event details |
| externalId | 255 | optional event ID, eg. ID from a teller system, etc. |
| shopDomain | - | optional shop domain |
Result of request:
{
"eventId":"7284e317-3bb6-4505-afbe-55b9a101339a",
"message" : [ ],
"success" : true
}
As a result of request we receive:
success – boolean value informing about the result of request (successful/not successful)
eventId – ID of added event
message – array of additional information enabling error identification
Adding an external event (recommended)
Sample structure of request recording a new event:
{
"clientId":"your-client-id-123",
"apiKey":"your-api-key-123",
"requestTime":1356180568127,
"sha":"3e4ec39722326150aae60f41e038d1def4450f46",
"owner":"admin@vendor.pl",
"email":"test@benhauer.com",
"forceOptIn": true,
"contactEvent":{
"date":1356180568153,
"description":"Purchase card \"Super Bonus\"",
"products":"p01, p02",
"location":"Shop_ID",
"value":1234.43,
"contactExtEventType":"PURCHASE",
"detail1":"C.ID: *** *** 234",
"detail2":"Payment by credit card",
"detail3":null,
"externalId":"A-123123123",
"shopDomain":"shop.salesmanago.pl"
}
}
In order to add an event we use the below method:
https://www.salesmanago.pl/api/v2/contact/addContactExtEvent
Available fields in the request addContactExtEvent method:
| Field | Max. length | Description |
|---|---|---|
| owner* | 255 | contact’s owner (SALESmanago user account email) |
| email*/contactId* | 255 | contact’s email for which the event is added |
| forceOptIn | true/false | value true will create contact as opt-in |
| date* | timestamp | event date (timestamp, i.e. time in milliseconds that passed from midnight 1 January 1970 UTC) |
| description | 2048 | event description |
| products | 512 | optional list of products separated by commas |
| E-shop ID (location) | 36 | unique shop identifier – this identifier is used to connect information about the product sent in the external event with a particular product feed. Maximum number of characters without spaces is 36 (possible characters: letters a-z, numbers 1-9, /_-.). Unique shop identifier has to be exactly the same as the value in the LOCATION field in external events sent from a particular shop. IMPORTANT: If you have only one product feed, the system will connect an external event and the product feed that you have in the system automatically. When you use multistore option, remember about coherence in sending external events with a unique identifier. |
| value | (19 2) | optional event value eg. amount spent (max 19 digits + 2 after the decimal point) |
| contactExtEventType* | 255 | event type, possible values: PURCHASE, CART, VISIT, PHONE_CALL, OTHER, RESERVATION, CANCELLED, ACTIVATION, MEETING, OFFER, DOWNLOAD, LOGIN, TRANSACTION, CANCELLATION, RETURN, SURVEY, APP_STATUS, APP_TYPE_WEB, APP_TYPE_MANUAL, APP_TYPE_RETENTION, APP_TYPE_UPSALE, LOAN_STATUS, LOAN_ORDER, FIRST_LOAN, REPEATED_LOAN |
| detail1-20 | 255/detal | optional event details |
| externalId | 255 | optional event ID, eg. ID from a teller system, etc. |
| shopDomain | - | optional shop domain |
Result of request:
{
"eventId":"7284e317-3bb6-4505-afbe-55b9a101339a",
"message" : [ ],
"success" : true
}
As a result of request we receive:
success – boolean value informing about the result of request (successful/not successful)
eventId – ID of added event
message – array of additional information enabling error identification
Adding many contact external events simultaneously
Sample structure of request recording a new events:
{
"clientId": "your-client-id-123",
"apiKey": "your-api-key-123",
"sha": "09b42a100849de3e4f7fad4f445eb47e833dba87",
"requestTime":1327056031488,
"owner":"user@vendor.pl",
"events": [
{
"contactId":"001e720f-b2ab-4203-a25f-b089557cf0da",
"contactEvent":{
"date":356180568153,
"description":"Bought with \"Super Bonus\"",
"products":"p01, p02",
"location":"Shop_ID",
"value":1234.43,
"contactExtEventType":"PURCHASE",
"detail1":"C.ID: *** *** 234",
"detail2":"Paid with card",
"detail3":null,
"externalId":"B-99999999",
"shopDomain":"shop.salesmanago.pl"
}
},
{
"email":"best.user@best.pl",
"contactEvent":{
"date":356180568153,
"description":"Bought with \"Super Bonus\"",
"products":"p01, p02",
"location":"Shop_ID",
"value":1234.43,
"contactExtEventType":"PURCHASE",
"detail1":"C.ID: *** *** 234",
"detail2":"Paid with card",
"externalId":"A-123123123",
"shopDomain":"shop.salesmanago.pl"
}
},
{
"email":"best.user@best.pl",
"contactEvent":{
"date":356180568153,
"description":"Bought with \"Super Bonus\"",
"products":"p02, p03",
"location":"Shop_ID",
"value":1234.43,
"contactExtEventType":"PURCHASE",
"detail1":"C.ID: *** *** 234",
"detail2":"Paid with card",
"detail3":null,
"externalId":"A-123123123",
"shopDomain":"shop.salesmanago.pl"
}
}
]
}
In order to add an events simultaneously we use the below method:
https://www.salesmanago.pl/api/contact/batchAddContactExtEvent
Available fields in the request batchAddContactExtEvent method:
| Field | Max. length | Description |
|---|---|---|
| owner* | 255 | contact’s owner (SALESmanago user account email) |
| events* | - | external events list (list cannot be empty and it’s limited to 1000) |
Single object in array consist of:
| Field | Max. length | Description |
|---|---|---|
| email* | 255 | contact’s email for which the event is added |
| contactId | 255 | contact id from SALESmanago system (can be used as alternative for contact email) |
| contactEvent* | - | external event object ( read more - Adding Event ) |
Result of request:
{
"success": true,
"message": [],
"failedContacts": [],
"createdAmount": 10,
"failedAmount": 0
}
As a result of request we receive:
success – boolean value informing about the result of request (successful/not successful)
message – array of additional information enabling error identification
failedContacts – array of contacts with event creation fail
createdAmount – amount of created events
failedAmount – amount of failed events
Modifying external event (deprecated)
Sample structure of request modifying an event:
{
"clientId":"your-client-id-123",
"apiKey":"your-api-key-123",
"requestTime":1356180568127,
"sha":"3e4ec39722326150aae60f41e038d1def4450f46",
"owner":"admin@vendor.pl",
"contactEvent":{
"eventId":"7284e317-3bb6-4505-afbe-55b9a101339a",
"date":1356180568153,
"description":"Purchase card \"Super Bonus\"",
"products":"p01, p02",
"location":"Shop_ID",
"value":1234.43,
"contactExtEventType":"PURCHASE",
"detail1":"C.ID: *** *** 234",
"detail2":"Payment by credit card",
"detail3":null,
"externalId":"A-123123123",
"shopDomain":"shop.salesmanago.pl"
}
}
In order to modify an event we use the below method:
https://www.salesmanago.pl/api/contact/updateContactExtEvent
Available fields in the request updateContactExtEvent method:
| Field | Max. length | Description |
|---|---|---|
| owner* | 255 | contact’s owner (SALESmanago user account email) |
| eventId* | 255 | event ID (returned by the add method) |
| date* | timestamp | event date (timestamp, i.e. time in milliseconds that passed from midnight 1 January 1970 UTC) |
| description | 2048 | event description |
| products | 512 | optional list of products separated with commas |
| E-shop ID (location)* | 36 | unique shop identifier – this identifier is used to connect information about the product sent in the external event with a particular product feed. Maximum number of characters without spaces is 36 (possible characters: letters a-z, numbers 1-9, /_-.). Unique shop identifier has to be exactly the same as the value in the LOCATION field in external events sent from a particular shop. IMPORTANT: If you have only one product feed, the system will connect an external event and the product feed that you have in the system automatically. When you use multistore option, remember about coherence in sending external events with a unique identifier. |
| value | (19 2) | optional event value e.g. the amount spent (max 19 digits + 2 after the decimal point) |
| contactExtEventType* | 255 | event type, allowed values: PURCHASE, CART, VISIT, PHONE_CALL, OTHER, RESERVATION, CANCELLED, ACTIVATION, MEETING, OFFER, DOWNLOAD, LOGIN, TRANSACTION |
| detail1-20 | 255/detal | optional event details, |
| externalId | 255 | optional event ID, e.g. ID from a teller system, etc. |
| shopDomain | - | optional shop domain |
Result of request:
{
"eventId":"7284e317-3bb6-4505-afbe-55b9a101339a",
"message" : [ ],
"success" : true
}
As a result of request we receive:
success – boolean value informing about the result of request (successful/not successful)
eventId – ID of added event
message – array of additional information enabling error identification
Modifying external event (recommended)
Sample structure of request modifying an event:
{
"clientId":"your-client-id-123",
"apiKey":"your-api-key-123",
"requestTime":1356180568127,
"sha":"3e4ec39722326150aae60f41e038d1def4450f46",
"owner":"admin@vendor.pl",
"contactEvent":{
"eventId":"7284e317-3bb6-4505-afbe-55b9a101339a",
"date":1356180568153,
"description":"Purchase card \"Super Bonus\"",
"products":"p01, p02",
"location":"Shop_ID",
"value":1234.43,
"contactExtEventType":"PURCHASE",
"detail1":"C.ID: *** *** 234",
"detail2":"Payment by credit card",
"detail3":null,
"externalId":"A-123123123",
"shopDomain":"shop.salesmanago.pl"
}
}
In order to modify an event we use the below method:
https://www.salesmanago.pl/api/v2/contact/updateContactExtEvent
Available fields in the request updateContactExtEvent method:
| Field | Max. length | Description |
|---|---|---|
| owner* | 255 | contact’s owner (SALESmanago user account email) |
| eventId* | 255 | event ID (returned by the add method) |
| date* | timestamp | event date (timestamp, i.e. time in milliseconds that passed from midnight 1 January 1970 UTC) |
| description | 2048 | event description |
| products | 512 | optional list of products separated with commas |
| E-shop ID (location)* | 36 | unique shop identifier – this identifier is used to connect information about the product sent in the external event with a particular product feed. Maximum number of characters without spaces is 36 (possible characters: letters a-z, numbers 1-9, /_-.). Unique shop identifier has to be exactly the same as the value in the LOCATION field in external events sent from a particular shop. IMPORTANT: If you have only one product feed, the system will connect an external event and the product feed that you have in the system automatically. When you use multistore option, remember about coherence in sending external events with a unique identifier. |
| value | (19 2) | optional event value e.g. the amount spent (max 19 digits + 2 after the decimal point) |
| contactExtEventType* | 255 | event type, allowed values: PURCHASE, CART, VISIT, PHONE_CALL, OTHER, RESERVATION, CANCELLED, ACTIVATION, MEETING, OFFER, DOWNLOAD, LOGIN, TRANSACTION |
| detail1-20 | 255/detal | optional event details, |
| externalId | 255 | optional event ID, e.g. ID from a teller system, etc. |
| shopDomain | - | optional shop domain |
Result of request:
{
"eventId":"7284e317-3bb6-4505-afbe-55b9a101339a",
"message" : [ ],
"success" : true
}
As a result of request we receive:
success – boolean value informing about the result of request (successful/not successful)
eventId – ID of added event
message – array of additional information enabling error identification
Removing an event
Sample structure of request removing an event:
{
"clientId":"your-client-id-123",
"apiKey":"your-api-key-123",
"requestTime":1356180568127,
"sha":"3e4ec39722326150aae60f41e038d1def4450f46",
"owner":"admin@vendor.pl",
"eventId":"7284e317-3bb6-4505-afbe-55b9a101339a"
}
In order to remove an event we use the below method:
https://www.salesmanago.pl/api/contact/deleteContactExtEvent
Available fields in the request deleteContactExtEvent method:
| Field | Max. length | Description |
|---|---|---|
| owner* | 255 | contact’s owner (SALESmanago user account email) |
| eventId* | 255 | event ID (returned by the add method) |
Result of request:
{
"success":true,
"message":[],
"result":"Ext event has been deleted."
}
As a result of request we receive:
success – boolean value informing about the result of request (successful/not successful)
result – result of request
message – array of additional information enabling error identification
Integration of external events, like basket
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.
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>
API - Tags management
Export of tag list
Sample structure of request data:
{
"apiKey" : "your-api-key-123",
"clientId" : "your-client-id-123",
"showSystemTags" : true,
"owner" : "admin@vendor.pl",
"requestTime" : 1329128188409,
"sha" : "02bfe70541d3907cf487f26dc2665b184b1221a7"
}
Tags are exported using the below method:
https://www.salesmanago.pl/api/contact/tags
Available fields in the request tags method:
| Field | Max. length | Description |
|---|---|---|
| owner* | 255 | contact’s owner (SALESmanago user account email) |
| showSystemTags* | true/false | when set at true, SALESmanago will also return system tags |
Result of request:
{
"tags" : [ { "tag" : "ADmanago",
"numberOfTagged" : 12
} ],
"message" : [ ],
"success" : true
}
As a result of request we receive:
tags – exported tags
tag – tag name
numberOfTagged – the number of tagged contacts
success – boolean value informing about the result of request (successful/not successful)
message – array of additional information enabling error identification
API - Email messages
Sending email (deprecated)
Sample structure of request data:
{
"clientId": "o7gslwlc8o1e2ry1",
"apiKey": "-8773203084919279780-2743038323156910252",
"requestTime": 1391167514795,
"sha": "184db1df6ec4893a1f50809bf8d1a4fe88cde4dc",
"user": "admin@finplan.pl",
"emailId": "029c504e-193a-43f2-84c7-3b7ee3c4438c",
"html" : "<html><body>email-html-content</body></html>",
"contacts": [
{
"addresseeType" : "EMAIL",
"email": "user1@example.com",
"contactId": null,
"properties": [
{
"name": "ext_detal_01",
"value": "value_01"
},
{
"name": "ext_detal_02",
"value": "value_02"
}
],
"tag" : null
},
{
"addresseeType" : "EMAIL",
"email": "user2@example.com",
"contactId": null,
"properties": [
{
"name": "ext_detal_03",
"value": "value_03"
},
{
"name": "ext_detal_04",
"value": "value_04"
}
],
"tag" : null
}
],
"excludeContacts": [
{
"addresseeType" : "EMAIL",
"email": "user3@example.com",
"contactId": null,
"tag" : null,
"properties": []
}
],
"date": 1391167515515,
"subject": "Sample API subject",
"campaign": "monitor_me_in_ga",
"immediate" : false,
"rule" : false
}
In order to send an email through API the below method should be used:
https://www.salesmanago.pl/api/email/send
Available fields in the request send method:
| Field | Max. length | Description |
|---|---|---|
| user* | 255 | user’s email |
| emailId* | 255 | message ID from the SALESmanago system |
| date* | 255 | mailing date |
| subject | 2048 | mailing subject (if not provided – a default will be used) |
| campaign | 255 | campaign for tracing Google UTM (if not provided – a default will be used) |
| html | - | HTML email body (if not provided – a default will be used) |
| contacts* | - | array of contacts to which email will be sent |
| addresseeType* | 255 | addressing emails type ( EMAIL, CONTACT_ID, TAGS) |
| email/contactId/tag* | 255 | e-mail address of contact, its ID or tag |
| properties | 255 | additional attributes of email messages defined by the user. It is not advised to use diacritical marks and spaces in names, but it is allowed. In an e-mail message the construction $cst.parameterName$ should be used in order to substitute the proper value. |
| excludeContacts | - | array of contacts which will be excluded from dispatch |
| immediate | true/false | attributing a true value will cause immediate dispatch of mail |
| rule | true/false | attributing a true value will cause message mark as rule email |
Result of request:
{
"success": true,
"message": ["Emails are scheduled to send."],
"conversationId": "dc4ef436-3d1b-4a85-b061-77236b1766e1"
}
As a result of request we receive:
success – boolean value informing about the result of request (successful/not successful)
message – array of additional information enabling error identification
conversationId – conversation ID
Sending email (recommended)
Sample structure of request data:
{
"clientId": "ye4vodnswfo6zp75",
"apiKey": "qwertgfdsa1234",
"requestTime": 1496399754907,
"sha": "02d89ab2f7333f11745f30e100a7fbd5adec2097",
"user": "admin@vendor.pl",
"emailId": "emailid",
"date": 1234562541250,
"html": "<html> <body> text $opt-out$ </body> </html>",
"campaign": "campaign name",
"subject": "subject of your email",
"contacts": [
{
"addresseeType": "EMAIL",
"value": "test1@test.pl, test2@test.pl, test3@test.pl",
"properties": [
{
"name": "name",
"value": "value"
},
{
"name": "name",
"value": "value"
}
]
},
{
"addresseeType": "CONTACT_ID",
"value": "contact-id-1, contact-id-2, contact-id-3, contact-id-3"
},
{
"addresseeType": "TAG",
"value": "tag1, tag2",
"properties": [
{
"name": "name",
"value": "value"
},
{
"name": "name",
"value": "value"
}
]
},
{
"addresseeType": "FUNNEL",
"value": "funnel-name-1, funnel-nam-2",
"properties": [
{
"name": "name",
"value": "value"
},
{
"name": "name",
"value": "value"
}
]
},
{
"addresseeType": "STAGE",
"value": "funnel-name",
"optValue": "stage-name-1, stage-name-2"
}
],
"excludeContacts": [
{
"addresseeType": "EMAIL",
"value": "test5@test.pl, test6@test.pl, test8@test.pl",
"properties": [
{
"name": "name",
"value": "value"
}
]
},
{
"addresseeType": "TAG",
"value": "exclude-tag-1",
"properties": []
}
]
}
In order to send an email through API the below method should be used:
https://www.salesmanago.pl/api/email/sendEmail
Available fields in the request sendEmail method:
| Field | Max. length | Description |
|---|---|---|
| user* | 255 | user’s email |
| emailId* | 255 | message ID from the SALESmanago system |
| date* | 255 | mailing date |
| subject | 2048 | mailing subject (if not provided – a default will be used) |
| campaign | 255 | campaign for tracing Google UTM (if not provided – a default will be used) |
| html | - | HTML email body (if not provided – a default will be used). An opt-out link ($opt-out$) is required |
| contacts* | - | array of contacts to which email will be sent |
| addresseeType* | 255 | addressing emails type ( EMAIL, CONTACT_ID, TAG, FUNNEL, STAGE) |
| value* | 255 | optional – contact email address, contact identifier, tag or funnel |
| optValue | 255 | for the STAGE type we can provide as an option names of stages in the funnel to which the mailing is addressed; each name is separated by a comma. |
| properties | 255 | additional attributes of email messages defined by the user. It is not advised to use diacritical marks and spaces in names, but it is allowed. In an e-mail message the construction $cst.parameterName$ should be used in order to substitute the proper value. |
| excludeContacts | - | array of contacts which will be excluded from dispatch |
Result of request:
{
"success": true,
"message": [
"Emails are scheduling to send."
],
"conversationId": "conversation-id"
}
As a result of request we receive:
success – boolean value informing about the result of request (successful/not successful)
message – array of additional information enabling error identification
conversationId - mailing identifier
Sending email with attachment
Sample structure of request data:
POST /api/email/sendWithAttachment HTTP/1.1
HOST: dev.salesmanago.pl
content-type: multipart/form-data; boundary=----WebKitFormBoundary1aTYxdL1yD9GkrBw
accept: application/json, application/*+json
cookie: JSESSIONID=B79601649C8C221E3024EF909FD27A51; SERVERID=A
content-length: 81854
------WebKitFormBoundary1aTYxdL1yD9GkrBw
Content-Disposition: form-data; name="attachment"; filename="poster.gif"
Content-Type: image/gif
<-- zawartość pliku -->
------WebKitFormBoundary1aTYxdL1yD9GkrBw
Content-Disposition: form-data; name="emailSendRequest"
{
"clientId": "r60ta7pkk1cqh1iy",
"apiKey": "sdfsfsfsdf",
"requestTime": 1391167514795,
"sha": "229c9b4e06d6742330d7fe7c6882469bcac90686",
"user": "test@test.com",
"emailId": "1ece2b0d-9061-4295-9ad4-34ab82fa852e",
"html" : "<html><body>email-html-content</body></html>",
"contacts": [
{
"addresseeType" : "EMAIL",
"email": "test@test.com",
"contactId": null,
"tag" : null,
"properties": [
{ "name": "ext_detal_01", "value": "value_01" }
,
{ "name": "ext_detal_02", "value": "value_02" }
]
},
{
"addresseeType" : "EMAIL",
"email": "test.stepniak+1@gmail.com",
"contactId": null,
"tag" : null,
"properties": [
{ "name": "ext_detal_03", "value": "value_03" }
,
{ "name": "ext_detal_04", "value": "value_04" }
]
}
],
"excludeContacts": [
{
"addresseeType" : "EMAIL",
"email": "user3@example.com",
"contactId": null,
"tag" : null,
"properties": []
}
],
"date": 1391167515515,
"subject": "Sample API subject",
"campaign": "monitor_me_in_ga",
"immediate" : false,
"rule" : false
}
In order to send an email through API the below method should be used:
https://www.salesmanago.pl/api/email/sendWithAttachment
Available fields in the request sendWithAttachment:
| Pole | Max. długość | Opis |
|---|---|---|
| user* | 255 | user’s email |
| emailId* | 255 | message ID from the SALESmanago system |
| date* | 255 | mailing date |
| subject | 2048 | mailing subject (if not provided – a default will be used) |
| campaign | 255 | campaign for tracing Google UTM (if not provided – a default will be used) |
| html | - | HTML email body (if not provided – a default will be used) |
| contacts* | - | array of contacts to which email will be sent |
| addresseeType* | 255 | addressing emails type ( EMAIL, CONTACT_ID, TAGS) |
| email/contactId/tag* | 255 | optional – e-mail address of contact, its ID or tag |
| properties | 255 | additional attributes of email messages defined by the user. It is not advised to use diacritical marks and spaces in names, but it is allowed. In an e-mail message the construction $cst.parameterName$ should be used in order to substitute the proper value. |
| excludeContacts | - | array of contacts which will be excluded from dispatch |
| immediate | true/false | attributing a true value will cause immediate dispatch of mail |
| rule | true/false | attributing a true value will cause message mark as rule email |
| attachment* | - | attached file |
Result of request:
{
"success": true,
"message": ["Emails are scheduled to send."],
"conversationId":"6bd61df3-44f3-825c-8c18-3d7813fea03b"
}
As a result of request we receive:
success – boolean value informing about the result of request (successful/not successful)
message – array of additional information enabling error identification
conversationId – email conversation identifier
Adding email messages
Sample structure of request data:
{
"clientId": "h4jsu6pc5txybj04",
"apiKey": "qwetreryuii",
"requestTime": 1481543324302,
"sha": "abcd509ac6eb0c460455c74ccc66867955a5333d",
"user": "admin@vendor.pl",
"name": "Email name",
"campaign": "Campaign name",
"subject": "Email subject",
"contentBoxMap": {
"customField": "fieldValue"
},
"shared": true,
"dynamic": true,
"emailAccountId": "1d35aaaa-8dac-423f-8325-f767816fb096",
"templateId": "e88a18f9-3dfe-4cf8-937e-960c3d217c97"
}
To add email messages, use the method:
https://www.salesmanago.pl/api/email/addEmail
Available fields in the request addEmail method:
| Field | Max. length | Description |
|---|---|---|
| user* | 255 | user’s email |
| name* | 255 | email message name |
| campaign | 255 | campaign name |
| subject* | 2048 | email message subject |
| contentBoxMap | 255/box | map containing the names and values of specific fields |
| shared | true/false | boolean value that indicates whether the template is shared |
| dynamic | true/false | boolean value that indicates whether the template is dynamic |
| emailAccountId* | 255 | email account ID |
| templateId* | 255 | email template ID |
Result of request:
{
"success": true,
"message": [],
"emailId": "cf55c3d5-9e1c-4f87-be2d-450bef5e3dd4"
}
As a result of request we receive:
success – boolean value informing about the result of request (successful/not successful)
message – array of additional information enabling error identification
emailId - created email ID
Adding or modifying email message
Sample structure of request data:
{
"clientId": "h4jsu6pc5txybj04",
"apiKey": "qwetreryuii",
"requestTime": 1481543324302,
"sha": "abcd509ac6eb0c460455c74ccc66867955a5333d",
"user": "admin@vendor.pl",
"name": "Email name",
"campaign": "Campaign name",
"subject": "Email subject",
"shared": true,
"dynamic": true,
"emailAccountId": "1d35aaaa-8dac-423f-8325-f767816fb096",
"templateId": "e88a18f9-3dfe-4cf8-937e-960c3d217c97"
}
To add or modify email messages use the method:
https://www.salesmanago.pl/api/email/upsertByName
Available fields in the request upsertByName method:
| Field | Max. length | Description |
|---|---|---|
| user* | 255 | user’s email |
| name* | 255 | email message name |
| campaign | 255 | campaign name |
| subject | 2048 | email message subject |
| shared | true/false | boolean value that indicates whether the template is shared |
| dynamic | true/false | boolean value that indicates whether the template is dynamic |
| emailAccountId* | 255 | email account ID |
| templateId* | 255 | email template ID |
Result of request:
{
"success": true,
"message": [],
"emailId": "cf55c3d5-9e1c-4f87-be2d-450bef5e3dd4"
}
As a result of request we receive:
success – boolean value informing about the result of request (successful/not successful)
message – array of additional information enabling error identification
templateId - created / modified email message ID
Adding email template
Sample structure of request data:
{
"clientId": "client-id-123",
"apiKey": "api-key-123",
"requestTime": 1481536595205,
"sha": "a533abcd509ac6ebccc660c460455c748679553d",
"user": "admin@vendor.pl",
"name": "Email Template name",
"emailContent": "html email content",
"shared": true,
"dynamic": true,
"parametrized": true,
"fromUrl": true,
"titleUrl": true,
"urlTemplate": "www.example.pl/template.html",
"customFields": "customField"
}
To add an email template use the method:
https://www.salesmanago.pl/api/email/addTemplate
Available fields in the request addTemplate method:
| Field | Max. length | Description |
|---|---|---|
| user* | 255 | user’s email |
| name* | 255 | template name |
| emailContent* | - | html email content |
| shared | true/false | boolean value that indicates whether the template is shared |
| dynamic | true/false | boolean value that indicates whether the template is dynamic |
| parametrized | true/false | boolean value that indicates whether the template accepts parameters before sending |
| fromUrl | true/false | boolean value that indicates whether the template is to use a template from the link html |
| titleUrl | true/false | boolean value that indicates whether the template is to use the title of the e-mail link |
| urlTemplate* | 255 | template url |
| customFields | 255 | additional template fields |
Result of request:
{
"success": true,
"message": [],
"templateId": "f69b9e97-dd34-468c-add2-e8efc09e7bb7"
}
As a result of request we receive:
success – boolean value informing about the result of request (successful/not successful)
message – array of additional information enabling error identification
templateId - created email template ID
Adding or modifying email template
Sample structure of request data:
{
"clientId": "client-id-123",
"apiKey": "api-key-123",
"requestTime": 1481536595205,
"sha": "a533abcd509ac6ebccc660c460455c748679553d",
"user": "admin@vendor.pl",
"name": "Email Template name",
"emailContent": "html email content",
"shared": true,
"dynamic": true,
"parametrized": true,
"fromUrl": true,
"titleUrl": true,
"urlTemplate": "www.example.pl/template.html",
"customFields": "customField"
}
To add or modify a template email use the method:
https://www.salesmanago.pl/api/email/upsertTemplate
Available fields in the request upsertTemplate method:
| Field | Max. length | Description |
|---|---|---|
| user* | 255 | user’s email |
| name* | 255 | template name |
| emailContent* | - | html email content |
| shared | true/false | boolean value that indicates whether the template is shared |
| dynamic | true/false | boolean value that indicates whether the template is dynamic |
| parametrized | true/false | boolean value that indicates whether the template accepts parameters before sending |
| fromUrl | true/false | boolean value that indicates whether the template is to use a template from the link html |
| titleUrl | true/false | boolean value that indicates whether the template is to use the title of the e-mail link |
| urlTemplate* | 255 | template url |
| customFields | 255 | additional template fields |
Result of request:
{
"success": true,
"message": [],
"templateId": "f69b9e97-dd34-468c-add2-e8efc09e7bb7"
}
As a result of request we receive:
success – boolean value informing about the result of request (successful/not successful)
message – array of additional information enabling error identification
templateId - created email template ID
Downloading email messages
Sample structure of request data:
{
"clientId": "client-id-123",
"apiKey": "api-key-123",
"sha": "abcd50460455c79ac6eb0c4ccc66867955a5333d",
"requestTime":1327056031488,
"owner": "admin@vendor.pl"
}
In order to download created messages the below method should be used:
https://www.salesmanago.pl/api/email/messages
Available fields in the request /api/email/messages method:
| Field | Max. length | Description |
|---|---|---|
| owner* | 255 | user email |
Result of request:
{
"success": true,
"message": [],
"standardMessages": [
{
"id": "f98243e0-fe89-4a71-88c3-2b966505cde8",
"name": "Message1",
"subject": "Subject 1",
"createdOn": 1515594292000,
"shared": false,
"emailAccountId": "11f2a086-1bcb-47eb-943c-4de682b39536",
"templateId": "402b6894-3cce-4117-9a36-8bb7f3344de1",
"userAccountId": "3373ad25-d13a-484c-a24d-d37ba3d5cce0",
"modifiedOn": 1515594292000,
"campaign": "default",
"notVisibleOnList": false,
"dynamic": false,
"ignoreLimits": false,
"emailCreator": false
},
{
"id": "639e5c7c-1589-4fb3-92d9-e126434c7603",
"name": "Message 2",
"subject": "Subject 2",
"createdOn": 1515595800000,
"shared": false,
"emailAccountId": "11f2a086-1bcb-47eb-943c-4de682b39536",
"templateId": "32d60879-5049-4f97-97d5-1a7a8843355c",
"userAccountId": "3373ad25-d13a-484c-a24d-d37ba3d5cce0",
"modifiedOn": 1515595800000,
"campaign": "",
"notVisibleOnList": false,
"dynamic": false,
"ignoreLimits": false,
"emailCreator": true
}
]
}
As a result of request we receive:
success – boolean value informing about the result of request (successful/not successful)
message – array of additional information enabling error identification
standardMessages - list of created messages with the following parameters:
id - identifier of the message
name - name of the message
subject - subject of the message
createdOn - message creation date ( Timestamp )
shared - boolean value that indicates whether the message is shared
emailAccountId - email account ID to which the message is assigned
templateId - email template ID
userAccountId - account ID of the user who created the message
modifiedOn - message modification date ( Timestamp )
campaign - campaign name
notVisibleOnList - boolean value that indicates whether the message is visible
dynamic - boolean value that indicates whether the message is dynamic
ignoreLimits - boolean value that indicates whether the message ignores sending filters
emailCreator - boolean value that indicates whether the message was prepared in the creator
Downloading Mass Conversation
Sample structure of request data:
{
"clientId":"your-client-id-123",
"apiKey":"your-api-key-123",
"requestTime":1485520055,
"sha":"11fbaf0ad77f1491979594f58ba10565b30926",
"from":1491965421341,
"to":1491979590565
}
To download mass conversation id’s list use the method:
https://www.salesmanago.pl/api/email/massConversationList
Available fields in the request massConversationList method:
| Field | Max. length | Description |
|---|---|---|
| from* | Timestamp | beginning range of conversations creation dates |
| to* | Timestamp | ending range of conversations creation dates |
Result of request:
{
"success": true,
"message": [],
"conversationList": [
"86dfe8bd-f21d-4f5e-9f53-19c929877d3c",
"5c27d476-282d-4235-9393-300d359b2d51"
]
}
As a result of request we receive:
success – boolean value informing about the result of request (successful/not successful)
message – array of additional information enabling error identification
conversationList - mass email conversations identifiers list
Downloading Mass Conversation - Direct emails
Sample structure of request data:
{
"clientId":"your-client-id-123",
"apiKey":"your-api-key-123",
"requestTime":1485520055,
"sha":"11fbaf0ad77f1491979594f58ba10565b30926",
"from":1491965421341,
"to":1491979590565
}
To download mass conversation id’s list use the method:
https://www.salesmanago.pl/api/email/massDirectConversationList
Available fields in the request massDirectConversationList method:
| Field | Max. length | Description |
|---|---|---|
| from* | Timestamp | beginning range of conversations creation dates |
| to* | Timestamp | ending range of conversations creation dates |
Result of request:
{
"success": true,
"message": [],
"conversationList": [
"86dfe8bd-f21d-4f5e-9f53-19c929877d3c",
"5c27d476-282d-4235-9393-300d359b2d51"
]
}
As a result of request we receive:
success – boolean value informing about the result of request (successful/not successful)
message – array of additional information enabling error identification
conversationList - mass email conversations identifiers list
Downloading conversation statistics
Sample structure of request data:
{
"clientId": "client-id-123",
"apiKey": "api-key-123",
"sha": "abcd50460455c79ac6eb0c4ccc66867955a5333d",
"requestTime":1327056031488,
"user": "user@user.com",
"conversationId": "dc4ef436-3d1b-4a85-b061-77236b1766e1"
}
To download conversation statistics use the method:
https://www.salesmanago.pl/api/email/conversationStatistics
Available fields in the request conversationStatistics method:
| Field | Max. length | Description |
|---|---|---|
| conversationId* | 255 | conversation ID |
| user* | 255 | e-mail address of user |
Result of request:
{
"success": true,
"message": [],
"requestId": 123
}
In response, you will receive “requestId”, which is the export id.
To check the process status, you need to send a POST request to:
https://www.salesmanago.pl/api/job/status
You need to give requestId (output of previous method), which contains number to check the status of export.
In response, you will receive either the message about the progress of the export or a link to the file with exported contacts.
Link is active for several minutes only.
Sample structure of request /api/job/status:
{
"clientId": "yourclientID",
"apiKey": "yourAPIkey",
"requestTime": 1500556989,
"sha": "4afd12754c746fa9f71648f2e2276ae40eccfe41",
"owner": "admin@vendor.pl",
"requestId": 123
}
Result of request
{
"success": true,
"message": [],
"fileUrl": "https://salesmanago.s3.amazonaws.com/notrealdata/notrealdata/notrealdata.json"
}
Result of request exported data of /api/email/conversationStatistics:
{
"conversationId": "example_id_123",
"name": "Name",
"subject": "Subject",
"sentMessage": 2,
"openedMessage": 2,
"uniqueOpens": 2,
"clickedMessage": 1,
"uniqueClicks": 1,
"errorMessage": 0,
"softBounce": 0,
"hardBounce": 0,
"resigned": 0,
"dateSent": 1536748629000,
"openedBy": [
{
"email": "example_email_1@test.pl",
"contactId": "78376c41-b78a-4c68-a4ac-dcc638c90ede",
"externalId": "externalId_1",
"dateOpened": 1536752109000,
"dateClicked": 1536752229000,
"bounce": null,
"optedOut": false
},
{
"email": "example_email_2@test.pl",
"contactId": "f761f4d7-d833-4ff4-80c8-b104fc662f9c",
"externalId": "externalId_2",
"dateOpened": 1536752109000,
"dateClicked": null,
"bounce": null,
"optedOut": false
}
],
"clickedBy": [
{
"email": "example_email_1@test.pl",
"contactId": "78376c41-b78a-4c68-a4ac-dcc638c90ede",
"externalId": "externalId_1",
"dateOpened": 1536752109000,
"dateClicked": 1536752229000,
"bounce": null,
"optedOut": false
}
],
"softBouncedBy": null,
"hardBouncedBy": null,
"resignedBy": null
}
Downloading contacts to whom email was sent
Sample structure of request data:
{
"apiKey": "our-api-key-123",
"clientId" : "your-client-id-123",
"sha" : "08924f45afc2e4fb8b652c53cdb493c7ddb846a1",
"requestTime" : 1327059355361,
"user": "user@user.com",
"conversationId": "5f0baebd-96bc-4a55-9ffe-709b04992327"
}
In order to download conversation statistics the below method should be used:
https://www.salesmanago.pl/api/email/messageStatistics
Available fields in the request messageStatistics method:
| Field | Max. length | Description |
|---|---|---|
| conversationId* | 255 | conversation identifier |
| user* | 255 | e-mail address of user |
As a result of request we receive:
{
"success": true,
"message": [],
"requestId": 123
}
In response, you will receive “requestId”, which is the export id.
To check the process status, you need to send a POST request to:
https://www.salesmanago.pl/api/job/status
You need to give requestId (output of previous method), which contains number to check the status of export.
In response, you will receive either the message about the progress of the export or a link to the file with exported contacts.
Link is active for several minutes only.
Sample structure of request /api/job/status:
{
"clientId": "yourclientID",
"apiKey": "yourAPIkey",
"requestTime": 1500556989,
"sha": "4afd12754c746fa9f71648f2e2276ae40eccfe41",
"owner": "admin@vendor.pl",
"requestId": 123
}
Result of request
{
"success": true,
"message": [],
"fileUrl": "https://salesmanago.s3.amazonaws.com/notrealdata/notrealdata/notrealdata.json"
}
Result of request exported data of /api/email/messageStatistics:
{
"conversationId": "5f0baebd-96bc-4a55-9ffe-709b04992327",
"name": "Test email",
"subject": "Lorem ipsum",
"sentMessage": 317,
"sentTo": [
{
"email": "test1@gmail.com",
"contactId": "7bc9092c-0221-483b-92d3-d97ddcda1fa3",
"dateOpened": 1533170052000
},
{
"email": "test2@gmail.com",
"contactId": "7bc9092c-0221-483b-92d3-d97ddcda1fa3",
"dateOpened": 1533170052000
},
{
"email": "test3@gmail.com",
"contactId": "7bc9092c-0221-483b-92d3-d97ddcda1fa3",
"dateOpened": 1533256452000
}
]
}
Sending your subscription confirmation
Sample structure of request data:
{
"clientId":"vgqgnhyxnk46va7s",
"apiKey":"api_key_code",
"requestTime":1488803352992,
"sha":"0fd94b6bcf9d97dc79df6951575ebdeaf4617c96",
"email":"test@test.com",
"owner":"test@owner.pl",
"tag":"Tag",
"lang":"PL",
"apiDoubleOptInEmailTemplateId":"",
"apiDoubleOptInEmailAccountId":"",
"apiDoubleOptInEmailSubject":""
}
To send a confirmation email through API, the method below should be used:
https://www.salesmanago.pl/api/email/sendConfirmation
The main aim of sendConfirmation method is to send email which confirms subscription (known as doubleOptIn). The message will be send to contacts that exist and do not have status Optln. Optional criterion is to add a tag, which must have an email for confirmation purpose.
Available fields in the request sendConfirmation method:
| Field | Max. length | Description |
|---|---|---|
| email* | 255 | contact’s email |
| owner* | 255 | contact’s owner email |
| tag | 255 | optional parameter defining tag which must have email contacts for confirmation purpose |
| lang** | 255 | language of sent email |
| apiDoubleOptInEmailTemplateId** | 255 | optional template ID for double-opt-in, |
| apiDoubleOptInEmailAccountId** | 255 | optional email account ID for double-opt-in, |
| apiDoubleOptInEmailSubject** | 255 | optional email subject for double-opt-in |
**Choose one of the two options:
- the completed lang parameter
- all three parameters: apiDoubleOptInEmailTemplateId, apiDoubleOptInEmailAccountId and apiDoubleOptInEmailSubject.
Result of request:
{
"success":true,
"message":["Contact exists - confirmation email sent"],
"contactExists":true,
"contactId":"4850e968-45fa-4910-bf8c-0d2cfdbaa42b"
}
As a result of request we receive:
success – boolean value informing about the result of request (successful/not successful)
message – array of additional information enabling error identification
contactExists – boolean value informing whether a particular contact exists in a database
contactId – contact ID
API - SMS messages
SMS sending
Sample structure of request data:
{
"clientId": "xxyyzz",
"apiKey": "yourApiKey",
"sha": "4288423ba34736e50f852228ea1d0c79628d3e16",
"requestTime":1327056031488,
"user": "user@vendor.pl",
"contacts": [
{
"email": "contact@gmail.com"
},
{
"email": "test@gmail.com"
},
{
"contactId": "c4c52fea-47b1-1b1e-8680-40a230eb49bc"
},
{
"tag": "SM_TEST"
}
],
"text": "Hello world!",
"date": 1403187522125,
"gateway": "SMSAPI",
"name": "api-test"
}
In order to send a SMS message through API the below method should be used:
https://www.salesmanago.pl/api/sms/send
Available fields in the request send method:
| Field | Max. length | Description |
|---|---|---|
| user* | 255 | user email |
| date | - | current timestamp (ms) |
| text* | - | message text |
| templateIntId* | 255 | sms template id, which gonna be used as message text (alternative for “text” field) |
| contacts* | - | contact object list |
| gateway | 255 | gateway name |
| name | 255 | campaign name |
Contact object list (“contacts” field) is an array containing fields:
| Field | Max. length | Description |
|---|---|---|
| email** | 255 | contact email |
| contactId** | 255 | contact id |
| tag** | 255 | tag assigned to the SALESmanago contact group (in the “contacts” field you can use up to 10 “tag” objects) |
**At least one of the fields listed is required.
Result of request:
{
"success": true,
"message": [
"API Smses are scheduled to send."
]
}
As a result of request we receive:
success – boolean value informing about the result of request (successful/not successful)
message – array of additional information enabling error identification
Downloading statistics of SMS campaigns by conversation ID
Sample structure of request data:
{
"clientId": "client-id-123",
"apiKey": "api-key-123",
"sha": "abcd50460455c79ac6eb0c4ccc66867955a5333d",
"requestTime":1327056031488,
"conversationId": "2924d07f-dc0e-495b-b375-14ef95a485cd"
}
In order to download statistics of SMS campaigns the below method should be used:
https://www.salesmanago.pl/api/sms/conversationStatistics
Available fields in the request conversationStatistics method:
| Field | Max. length | Description |
|---|---|---|
| conversationId* | 255 | conversation ID |
Result of request:
{
"success": true,
"message": [],
"conversationId": "2924d07f-dc0e-495b-b375-14ef95a485cd",
"name": "test",
"messages": 2,
"sentMessages": 2,
"deliveredCount": 1,
"delivered": [
{
"email": "example_mail_1@test.pl",
"id": "ca7126a8-9eb4-480a-900a-daca3d47780f",
"dateTimestamp": 1513853328000,
"contactExternalId": "extId"
}
],
"repliedCount": 1,
"replied": [
{
"email": "example_mail_1@test.pl",
"id": "ca7126a8-9eb4-480a-900a-daca3d47780f",
"dateTimestamp": 1513853328000,
"contactExternalId": "extId"
}
],
"notDeliveredCount": 1,
"notDelivered": [
{
"email": "example_mail_2@test.pl",
"id": "9ca03a61-04a2-4d89-ae9c-1b3394814f52",
"contactExternalId": "extId_2"
}
]
}
As a result of the request we receive:
success – success - boolean value informing about the result of request (successful/not successful)
message – message - array of additional information enabling error identification
conversationId - conversation ID
name - conversation name
messages - number of messages to send
sentMessages - number of messages sent
deliveryCount - number of messages delivered
delivered - list of contacts to whom a message was delivered. It consists of the following fields:
email - email address of the contact
id - identifier of the contact
dateTimestamp - reply date to a message
contactExternalId - external ID of the contact
repliedCount - number of messages to which a reply was sent
replied - list of contacts to whom a message was delivered. It consists of the following fields:
email - email address of the contact
id - identifier of the contact
dateTimestamp - reply date to a message
contactExternalId - external ID of the contact
notDeliveredCount - number of not delivered messages
notDelivered - list of contacts to whom a message was delivered. It consists of the following fields:
email - email address of the contact
id - identifier of the contact
dateTimestamp - reply date to a message
Dowloading statistics of SMS campaigns by conversation name
Sample structure of request data:
{
"clientId": "client-id-123",
"apiKey": "api-key-123",
"sha": "abcd50460455c79ac6eb0c4ccc66867955a5333d",
"requestTime":1327056031488,
"name": "test"
}
In order to download statistics of SMS campaigns the below method should be used:
https://www.salesmanago.pl/api/sms/conversationStatisticsByName
Available fields in the request conversationStatisticsByName method:
| Field | Max. length | Description |
|---|---|---|
| name* | 255 | conversation name |
Result of request:
{
"success": true,
"message": [],
"count": 59,
"conversationStatistics": [
{
"success": true,
"message": [],
"conversationId": "2924d07f-dc0e-495b-b375-14ef95a485cd",
"messages": 2,
"sentMessages": 2,
"deliveredCount": 1,
"delivered": [
{
"email": "example_mail_1@test.pl",
"id": "ca7126a8-9eb4-480a-900a-daca3d47780f",
"dateTimestamp": 1513853328000,
"contactExternalId": "extId"
}
],
"repliedCount": 1,
"replied": [
{
"email": "example_mail_1@test.pl",
"id": "ca7126a8-9eb4-480a-900a-daca3d47780f",
"dateTimestamp": 1513853328000,
"contactExternalId": "extId"
}
],
"notDeliveredCount": 1,
"notDelivered": [
{
"email": "example_mail_2@test.pl",
"id": "9ca03a61-04a2-4d89-ae9c-1b3394814f52",
"contactExternalId": "extId_2"
}
]
}
]
}
As a result of the request we receive:
success – success - boolean value informing about the result of request (successful/not successful)
message – message - array of additional information enabling error identification
count – number of conversations
conversationStatistics - statistics of SMS campaigns
conversationId - mailing identifier
messages - number of messages to send
sentMessages - number of messages sent
deliveryCount - number of messages delivered
delivered - list of contacts to whom a message was delivered. It consists of the following fields:
email - email address of the contact
id - identifier of the contact
dateTimestamp - reply date to a message
contactExternalId - external ID of the contact
repliedCount - number of messages to which a reply was sent
replied - list of contacts to whom a message was delivered. It consists of the following fields:
email - email address of the contact
id - identifier of the contact
dateTimestamp - reply date to a message
contactExternalId - external ID of the contact
notDeliveredCount - number of not delivered messages
notDelivered - list of contacts to whom a message was delivered. It consists of the following fields:
email - email address of the contact
id - identifier of the contact
dateTimestamp - reply date to a message
Downloading SMS conversation statistics
Sample structure of request data:
{
"apiKey": "our-api-key-123",
"clientId" : "your-client-id-123",
"sha" : "08924f45afc2e4fb8b652c53cdb493c7ddb846a1",
"requestTime" : 1327059355361,
"conversationId": "ace8beeb-a0dc-4234-afc8-e6274de9e0ae"
}
In order to download conversation statistics the below method should be used:
https://www.salesmanago.pl/api/sms/smsConversationStatistics
Available fields in the request smsConversationStatistics method:
| Field | Max. length | Description |
|---|---|---|
| conversationId* | 255 | conversation identifier |
As a result of request we receive:
{
"success": true,
"message": [],
"conversationId": "ace8beeb-a0dc-4234-afc8-e6274de9e0ae",
"messages": 3,
"sentCount": 3,
"sent": [
{
"email": "test1@testowy.pl",
"id": "09d20ef2-1a4e-11e7-baad-0cc47a6bceb8",
"dateTimestamp": 1564408685000,
"contactExternalId": null
},
{
"email": "test2@testowy.pl",
"id": "0ae3be46-ca11-11e7-adbf-0cc47a6bceb8",
"dateTimestamp": 1564408684000,
"contactExternalId": null
},
{
"email": "test3@testowy.pl",
"id": "0afd8128-ca11-11e7-adbf-0cc47a6bceb8",
"dateTimestamp": 1564408868000,
"contactExternalId": null
}
],
"deliveredCount": 2,
"delivered": [
{
"email": "test1@testowy.pl",
"id": "09d20ef2-1a4e-11e7-baad-0cc47a6bceb8",
"dateTimestamp": 1564408691000,
"contactExternalId": null
},
{
"email": "test2@testowy.pl",
"id": "0ae3be46-ca11-11e7-adbf-0cc47a6bceb8",
"dateTimestamp": 1564408691000,
"contactExternalId": null
}
]
}
As a result of request we receive:
success – boolean value informing about the result of the request (successful/not successful)
message – array of additional information enabling error identification
conversationId - conversation identifier
messages - number of messages
sentCount - number of messages sent
sent - list of contacts to whom message was sent
deliveredCount - number of delivered messages
delivered - list of contacts to whom a message was delivered.
Downloading Mass Conversation
Sample structure of request data:
{
"clientId":"h4jsu6pc5txybj04",
"apiKey":"your-api-key-123",
"requestTime":1485520055,
"sha":"11fbaf0ad77f1491979594f58ba10565b30926",
"from":1491965421341,
"to":1491979590565
}
To download mass conversation id’s list use the method:
https://www.salesmanago.pl/api/sms/massConversationList
Available fields in the request massConversationList method:
| Field | Max. length | Description |
|---|---|---|
| from* | Timestamp | beginning range of conversations creation dates |
| to* | Timestamp | ending range of conversations creation dates |
Result of request:
{
"success": true,
"message": [],
"conversationList": [
"86dfe8bd-f21d-4f5e-9f53-19c929877d3c",
"5c27d476-282d-4235-9393-300d359b2d51"
]
}
As a result of request we receive:
success – boolean value informing about the result of request (successful/not successful)
message – array of additional information enabling error identification
conversationList - mass sms conversations identifiers list
API - Tasks
Contacts’ tasks
Sample structure of request data:
{
"apiKey" : "your-api-key-123",
"clientId" : "your-client-id-123",
"requestTime" : 1329128188409,
"sha" : "02bfe70541d3907cf487f26dc2665b184b1221a7",
"finished" : false,
"smContactTaskReq" : {
"contactEmail" : "john.doe@email.com",
"id" : "task-id-123",
"note" : "Call to client",
"date" : 1359673200361,
"cc" : "john.doe@email.com",
"reminder" : "30_MIN",
"realized" : false
}
}
Adding, updating and removing a contact’s task is done with the use of one method:
https://www.salesmanago.pl/api/contact/updateTask
Available fields in the request updateTask method:
| Field | Max. length | Description |
|---|---|---|
| finished | true/false | 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 |
| contactEmail** | 255 | contact email to which the task will be assigned |
| id | 255 | task ID |
| note | 2048 | task note |
| date** | 255 | date of task execution |
| cc | 255 | list of emails where a reminder will be sent (emails should be separated with commas) |
| reminder** | 255 | 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 |
| realized | true/false | assigning the value true will mark the task as completed |
** Fields required while adding a task
Result of request:
{
"taskId" : "task-Id-123",
"message" : [ ],
"success" : true
}
As a result of request we receive:
taskId – id of task that the action concerns
success – boolean value informing about the result of request (successful/not successful)
message – array of additional information enabling error identification
API - Notes
Adding note
Sample structure of request data:
{
"clientId":"your-client-id-123",
"apiKey":"your-api-key-123",
"requestTime":1327056031488,
"sha":"2aa3927a7dee8c2a712adb5375f5fa36dd8fe00c",
"owner": "owner@test.pl",
"contactId": "",
"email": "test1@test.pl",
"priv": false,
"note": "Note which will be assigned to contacts"
}
To add note to contact, use the method:
https://www.salesmanago.pl/api/contact/addNote
Available fields in the addNote method request:
| Field | Max. length | Description |
|---|---|---|
| owner* | 255 | contact’s owner (SALESmanago user account email) |
| email* | 255 | contact’s email for which the note is added |
| contactId* | 255 | contact’s identifier for which the note is added (can be used as alternative for contact email) |
| priv | true/false | defines whether the note should be private, i.e. visible only by the adder (default false) |
| note* | 1024 | note content |
Result of request:
{
"success": true,
"message": [
"Note was added to contact"
]
}
As a result of request we receive:
success – boolean value informing about the result of request (successful/not successful)
message – array of additional information
API - Other
Getting list of user accounts for a client
Sample structure of request data:
{
"clientId": "your-api-key-123",
"apiKey": "your-client-id-123",
"requestTime": 1234567896541,
"sha": "4f69782e826841f794080cae87648e42"
}
To get the list of user accounts for a client, use this method:
https://www.salesmanago.pl/api/user/listByClient
Available fields in the request listByClient method:
This method does not require any additional fields
Result of request:
{
"success": true,
"message": [],
"users": [
"admin@vendor.pl",
"test@test.pl"
]
}
success – boolean value informing about the inquiry (successful/not successful)
message – table of additional information enabling mistake identification
users – list of email users
Temporary authorization
Sample structure of request data:
{
"userName" : "admin@vendor.pl",
"password" : "****"
}
The SALESmanago system makes it possible to obtain a temporary token using the username and password. To do this the following method should be called:
https://www.salesmanago.pl/api/system/authorise
Available fields in the request authorise method:
| Field | Max. length | Description |
|---|---|---|
| userName* | 255 | user name |
| password* | 255 | password |
Result of request:
{
"token" : "b426c6663d844305b2539e9bc27b75dc",
"clientId" : "your-client-id-123",
"validTo" : 1359673200361,
"message" : [ ],
"success" : true
}
As a result of request we receive:
token – is a temporary token that may be used for authorization in exchange for apiSecret
clientId – client ID required for further operations
validTo – valid date
message – array of additional information enabling error identification
success – boolean value informing about the result of request (successful/not successful)
API - Workflow
Downloading the list of Workflow 2.0
Sample structure of the request data:
{
"clientId" : "your-client-id-123",
"apiKey" : "your-api-key-123",
"requestTime" : 1234567896541,
"sha" : "4f69782e826841f794080cae87648e42"
}
In order to download Workflow 2.0 list you have to use the following method:
https://www.salesmanago.pl/api/workflow/list
Available fields in the request api/workflow/list method: This method does not require any additional fields.
Result of the request:
{
"success": true,
"message": [],
"workflows": [
{
"id": 1000001,
"name": "workflow 1"
},
{
"id": 1000002,
"name": "workflow 2"
}
]
}
As a result of the request we receive:
success – boolean value informing about the result of the request (successful/not successful).
message – the array of additional information enabling error identification.
workflows - list of undeleted workflow 2.0
id - id of the workflow
name - the name of the workflow
API - Web Push
Downloading statistics of sending web push notifications
Sample structure of request data:
{
"apiKey": "our-api-key-123",
"clientId" : "your-client-id-123",
"sha" : "08924f45afc2e4fb8b652c53cdb493c7ddb846a1",
"requestTime" : 1327059355361,
"wizardId": 23657
}
In order to download statistics of sending web push notifications the below method should be used:
https://www.salesmanago.pl/api/web/push/stats
Available fields of the request web/push/stats method:
| Field | Max. length | Description |
|---|---|---|
| wizardId* | 255 | mailing identifier |
As a result of request we receive:
{
"success": true,
"message": [],
"name": "webpush name",
"date": 1590582123218,
"totalSent": 44,
"anonymousSent": 35,
"totalOpened": 12,
"totalClicked": 5,
"richWebPushOpened": 2,
"richWebPushClicked": 2,
"sent": [
"test1@gmail.com",
"test2@gmail.com",
"test3@gmail.com",
"test4@gmail.com",
"test5@gmail.com",
"test6@gmail.com",
"test7@gmail.com",
"test8@gmail.com",
"test9@gmail.com"
],
"opened": [
"test1@gmail.com",
"test2@gmail.com",
"test3@gmail.com",
"test4@gmail.com",
"test5@gmail.com"
],
"clicked": [
"test1@gmail.com",
"test2@gmail.com"
]
}
As a result of request we receive:
success – boolean value informing about the result of the request (successful/not successful)
message – array of additional information enabling error identification
name - name of web push notification
date - send date of web push
totalSent - number of web push notifications sent
anonymousSent - number of web push notifications sent to anonymous contacts
totalOpened - number of openings
totalClicked - number of clicks
richWebPushOpened - number of openings of rich web push notifications
richWebPushClicked - number of clicks in rich web push notifications
sent - list of contacts to whom web push notifications were sent
opened - list of contacts who opened web push notification
clicked - list of contacts who clicked web push notification
Downloading the list of web push notification identifiers
Sample structure of request data:
{
"apiKey": "our-api-key-123",
"clientId" : "your-client-id-123",
"sha" : "08924f45afc2e4fb8b652c53cdb493c7ddb846a1",
"requestTime" : 1327059355361,
"from":1572605631000,
"to":1573558527000
}
In order to donwload the list of web push notification identifiers the below method should be used:
https://www.salesmanago.pl/api/web/push/ids
Available fields of the request web/push/ids:
| Field | Max. length | Description |
|---|---|---|
| from* | Timestamp | the beginning of the date range of sent web push notifications |
| to* | Timestamp | the end of the range date of sent web push notifications |
As a result of request we receive:
{
"success": true,
"message": [],
"webPushIds": [
1,2,3
]
}
As a result of request we receive:
success – boolean value informing about the result of the request (successful/not successful)
message – array of additional information enabling error identification
webPushIds - the list of sent web push notifications’ id
Web Push notification ID list
Sample structure of request data:
{
"apiKey": "test123test",
"clientId" : "ye4vodnswfo6zp75",
"sha" : "dsadsadasdsadsadsadsadsadsadb",
"requestTime" :1626774053,
"from":1595238047,
"to":1626774053
}
Use the following method to get a list of Web Push Notification IDs:
https://www.salesmanago.pl/api/notification/conversation/ids
Complete the available fields in the request to authorise the method:
| Field | Max. length | Description |
|---|---|---|
| apiKey* | - | API key |
| clientId* | - | user id |
| sha* | - | generated sha |
| requestTime* | - | time the request was made (ms) |
| from* | - | modification date (ms), from which contacts will be searched |
| to* | - | modification date (ms), to which contacts will be searched |
Result of request:
{
"success": true,
"message": [
"Conversation list"
],
"pushConversationIds": [
16,
17,
18,
19
]
}
As a result of the request you will get:
success – boolean value informing about the result of request (successful/not successful)
message – array of additional information enabling error identification
pushConversationIds – array of web push id
Export consent forms statistics to a file accessible from the repository
Sample structure of request data:
{
"apiKey": "test123test",
"clientId" : "ye4vodnswfo6zp75",
"sha" : "1a3225a77b341043e17672f369e9150afed488eb",
"requestTime" :1626774053,
"user":"superuser@gmail.com",
"intId":101044
}
Use the following method to export consent forms statistics to a file that will be accessible from the repository:
https://www.salesmanago.pl/api/notification/consent/form/stats
Complete the available fields in the request to authorise the method:
| Field | Max. length | Description |
|---|---|---|
| apiKey* | - | API key |
| clientId* | - | user id |
| sha* | - | generated sha |
| requestTime* | - | time the request was made (ms) |
| user* | 255 | user email |
| intId* | form id |
Result of request:
{
"success": true,
"message": [
"Export added to execute."
],
"requestId": 2660
}
As a result of the request you will get:
success – boolean value informing about the result of request (successful/not successful)
message – array of additional information enabling error identification
requestId – number value of request
In response, you will receive “requestId”, which is the export id.
To check the process status, you need to send a POST request to: https://www.salesmanago.pl/api/job/status
You need to give requestId (output of previous method), which contains number to check the status of export.
In response, you will receive either the message about the progress of the export or a link to the file with exported contacts.
Link is active for several minutes only.
Sample structure of request /api/job/status:
{
"clientId": "yourclientID",
"apiKey": "yourAPIkey",
"requestTime": 1500556989,
"sha": "4afd12754c746fa9f71648f2e2276ae40eccfe41",
"owner": "admin@vendor.pl",
"requestId": 123
}
Result of request
{
"success": true,
"message": [],
"fileUrl": "https://salesmanago.s3.amazonaws.com/notrealdata/notrealdata/notrealdata.json"
}
Export Web Push notifications statistics to a file accessible from the repository
Sample structure of request data:
{
"apiKey": "test123test",
"clientId" : "ye4vodnswfo6zp75",
"sha" : "1a3225a77b341043e17672f369e9150afed488eb",
"user": "superuser@gmail.com",
"itemId": "1",
"webPushSourceType": "MASS"
}
Use the following method to export Web Push notifications statistics to a file that will be accessible from the repository:
https://www.salesmanago.pl/api/notification/push/stats
Complete the available fields in the request to authorise the method:
| Field | Max. length | Description |
|---|---|---|
| apiKey* | - | API key |
| clientId* | - | user id |
| sha* | - | generated sha |
| user* | 255 | user email |
| itemId* | user email | |
| webPushSourceType* | webpush type |
Result of request:
{
"success": true,
"message": [
"Export added to execute."
],
"requestId": 2659
}
As a result of the request you will get:
success – boolean value informing about the result of request (successful/not successful)
message – array of additional information enabling error identification
requestId – number value of request
In response, you will receive “requestId”, which is the export id.
To check the process status, you need to send a POST request to: https://www.salesmanago.pl/api/job/status
You need to give requestId (output of previous method), which contains number to check the status of export.
In response, you will receive either the message about the progress of the export or a link to the file with exported contacts.
Link is active for several minutes only.
Sample structure of request /api/job/status:
{
"clientId": "yourclientID",
"apiKey": "yourAPIkey",
"requestTime": 1500556989,
"sha": "4afd12754c746fa9f71648f2e2276ae40eccfe41",
"owner": "admin@vendor.pl",
"requestId": 123
}
Result of request
{
"success": true,
"message": [],
"fileUrl": "https://salesmanago.s3.amazonaws.com/notrealdata/notrealdata/notrealdata.json"
}
Name and ID of a consent form
Sample structure of request data:
{
"apiKey": "test123test",
"clientId" : "ye4vodnswfo6zp75",
"sha" : "1a3225a77b341043e17672f369e9150afed488eb",
"requestTime" :1626774053
}
Use the following method to get the name and ID of the consent form:
https://www.salesmanago.pl/api/notification/consent/form/data
Using this method, when you request with a specific Client’s ID, you’ll get the information about the ID and the name of the form the contact is subscribed to.
Complete the available fields in the request to authorise the method:
| Field | Max. length | Description |
|---|---|---|
| apiKey* | - | API key |
| clientId* | - | user id |
| sha* | - | generated sha |
| requestTime* | - | time the request was made (ms) |
Result of request:
{
"success": true,
"message": [],
"consentFormList": [
{
"intId": 101045,
"name": "Nowy formularz zgody 2021-06-22 14:49"
},
{
"intId": 101044,
"name": "Nowy formularz zgody 2021-06-02 12:05"
}
]
}
As a result of the request you will get:
success – boolean value informing about the result of request (successful/not successful)
message – array of additional information enabling error identification
consentFormList – array of object with intId and form name
intId – number value of form id
name – string value of form name
API - Loyalty Program
Adding contact to Loyalty Program
Sample structure of request data:
{
"clientId": "clientId",
"apiKey": "apiKey",
"requestTime": 1481543324302,
"sha": "sha1",
"owner": "admin@vendor.pl",
"contacts": [
{
"addresseeType": "email",
"value": "email@addresseeType.pl"
}
],
"loyaltyProgram": "Loyalty Program Name"
}
We’re adding contact to Loyalty Program by using the below method:
https://www.salesmanago.pl/api/loyalty/program/v1/addContact
Available fields in the request addContact method:
| Field | Max. length | Description |
|---|---|---|
| owner* | 255 | contact’s owner (SALESmanago user account email) |
| contacts* | 255 | array of contacts to adding. |
| loyaltyProgram* | 255 | name of loyalty program |
Result of request:
{
"message": [],
"success": true,
"points": 123
}
As a result of request we receive:
success – boolean value informing about the result of request (successful/not successful)
message – array of additional information enabling error identification
points – number of points
Removing contact from Loyalty Program
Sample structure of request data:
{
"clientId": "clientId",
"apiKey": "apiKey",
"requestTime": 1481543324302,
"sha": "sha1",
"owner": "admin@vendor.pl",
"contacts": [
{
"addresseeType": "email",
"value": "email@addresseeType.pl"
}
],
"loyaltyProgram": "Loyalty Program Name"
}
We’re removing contact from Loyalty Program by using the below method:
https://www.salesmanago.pl/api/loyalty/program/v1/removeContact
Available fields in the request removeContact method:
| Field | Max. length | Description |
|---|---|---|
| owner* | 255 | contact’s owner (SALESmanago user account email) |
| contacts* | 255 | array of contacts to adding. |
| loyaltyProgram* | 255 | name of loyalty program |
Result of request:
{
"message": [],
"success": true
}
As a result of request we receive:
success – boolean value informing about the result of request (successful/not successful)
message – array of additional information enabling error identification
Adding/removing contact points to Loyalty Program
Sample structure of request data:
{
"clientId": "clientId",
"apiKey": "apiKey",
"requestTime": 1481543324302,
"sha": "sha1",
"owner": "admin@vendor.pl",
"contacts": [
{
"addresseeType": "email",
"value": "email@addresseeType.pl"
}
],
"loyaltyProgram": "Loyalty Program Name",
"points": 12,
"modificationType": "SUBTRACT",
"comment": "Comment text"
}
We’re adding/removing contact points to Loyalty Program by using the below method:
https://www.salesmanago.pl/api/loyalty/program/v1/modifyPoints
Available fields in the request modifyPoints method:
| Field | Max. length | Description |
|---|---|---|
| owner* | 255 | contact’s owner (SALESmanago user account email) |
| contacts* | 255 | list of Contacts to have the number of points changed (in accordance to other API methods with addresseeType) |
| loyaltyProgram* | 255 | name of loyalty program |
| points* | 255 | number of points |
| modificationType* | SUBTRACT - subtracting points, ADD - adding points | modification type |
| comment | 255 | comment of modification |
Result of request:
{
"message": [],
"success": true
}
As a result of request we receive:
success – boolean value informing about the result of request (successful/not successful)
message – array of additional information enabling error identification
API - Product recommendation
Last viewed products
Sample structure of request data:
{
"clientId": "your-client-id-123",
"apiKey": "salesmanago",
"requestTime": 1481543324302,
"sha": "02bfe70541d3907cf487f26dc2665b184b1221a7",
"contactUuid": "170675fb1b0-56e5eec9cf80-7a8a851e-b0d145fc-b61bb5fc-bcced77f3c28",
"shopName": "dataSource"
}
In order to get last viewed products we use the below method:
https://www.salesmanago.pl/api/recommendation/lastViewed
Available fields in the request lastViewed:
| Field | Max. length | Description |
|---|---|---|
| contactUuid* | 255 | smuuid cookie value |
| shopName* | 255 | data source name |
Result of request:
{
"message" : [ ],
"success" : true,
"productIds" : [
6754,
6755
]
}
As a result of request we receive:
success – boolean value informing about the result of request (successful/not successful)
message – array of additional information enabling error identification
productIds – array of product ids
Most purchased products
Sample structure of request data:
{
"clientId": "your-client-id-123",
"apiKey": "salesmanago",
"requestTime": 1481543324302,
"sha": "02bfe70541d3907cf487f26dc2665b184b1221a7",
"shopName": "dataSource"
}
In order to get most purchased products we use the below method:
https://www.salesmanago.pl/api/recommendation/mostPurchased
Available fields in the request mostPurchased:
| Field | Max. length | Description |
|---|---|---|
| shopName* | 255 | data source name |
Result of request:
{
"message" : [ ],
"success" : true,
"productIds" : [
6754,
6755
]
}
As a result of request we receive:
success – boolean value informing about the result of request (successful/not successful)
message – array of additional information enabling error identification
productIds – array of product ids
Products purchased by contact (only for monitored contacts)
Sample structure of request data:
{
"clientId": "your-client-id-123",
"apiKey": "salesmanago",
"requestTime": 1481543324302,
"sha": "02bfe70541d3907cf487f26dc2665b184b1221a7",
"smClient": "fecfca38-1f97-437d-91c4-2f30a67e31fa",
"shopName": "dataSource"
}
In order to get products purchased by contact we use the below method:
https://www.salesmanago.pl/api/recommendation/purchasedByContact
Available fields in the request purchasedByContact:
| Field | Max. length | Description |
|---|---|---|
| shopName* | 255 | data source name |
| smClient* | 255 | smclient cookie value |
Result of request:
{
"message" : [ ],
"success" : true,
"productIds" : [
6754,
6755
]
}
As a result of request we receive:
success – boolean value informing about the result of request (successful/not successful)
message – array of additional information enabling error identification
productIds – array of product ids
Products purchased with the product being viewed
Sample structure of request data:
{
"clientId": "your-client-id-123",
"apiKey": "salesmanago",
"requestTime": 1481543324302,
"sha": "02bfe70541d3907cf487f26dc2665b184b1221a7",
"productId": 207,
"shopName": "dataSource"
}
In order to get products purchased with the product being viewed we use the below method:
https://www.salesmanago.pl/api/recommendation/purchasedTogether
Available fields in the request purchasedTogether:
| Field | Max. length | Description |
|---|---|---|
| shopName* | 255 | data source name |
| productId* | 255 | product id |
Result of request:
{
"message" : [ ],
"success" : true,
"productIds" : [
6754,
6755
]
}
As a result of request we receive:
success – boolean value informing about the result of request (successful/not successful)
message – array of additional information enabling error identification
productIds – array of product ids
API - Vision
Product recommendations based on SALESmanago Cinderella AI
Sample structure of request data:
{
"clientId" : "your-client-id-123",
"apiKey" : "your-api-key-123",
"requestTime":1611512104000,
"sha" : "08924f45afc2e4fb8b652c53cdb493c7ddb846a1",
"urlImg":"https://urlimg.com/name.jpg",
"vendorDataSourceIntId":123
}
In order to get product recommendations based on SALESmanago Cinderella AI we use the below method:
https://www.salesmanago.pl/api/vision
Available fields in the request vision:
| Field | Max. length | Description |
|---|---|---|
| urlImg* | 255 | the url of the searched image |
| vendorDataSourceIntId* | 255 | product feed ID - is available in settings -> integration -> product feeds |
Result of request:
{
"success": true,
"message": [],
"vision": {
"status": "ok",
"photo": "https://urlimg.com/name.jpg",
"result": [
{
"id": "123",
"score": 0.3589041829109192
},
{
"id": "456",
"score": 0.34405747056007385
},
{
"id": "789",
"score": 0.3198060393333435
}
],
"bq_errors": 0
}
}
As a result of request we receive:
success – boolean value informing about the result of request (successful/not successful)
message – array of additional information enabling error identification
status - search status
photo - the url of the searched image
result - search results
id - product ID
score - match percentage
bq_errors - the number of incorrect matches
API - Customer Preference Center
Customer Preference Center
To retrieve a pre-authorized view of Customer Preference Center call:
https://www.salesmanago.pl/api/customerPreferenceCenter/generateEndpoint
Sample structure of request data:
{
"clientId": "5vvtmri5ocom6n8g",
"apiKey": "-8773203084919279780-2743038323156910252",
"requestTime": 1391167514795,
"sha": "184db1df6ec4893a1f50809bf8d1a4fe88cde4dc",
"preferenceCenterId" : "7bd071c1-cb96-45a7-8e95-c512c76189a2",
"contactId": "47d82f5a-87d3-11eb-a567-f8a2d6e832bf"
}
Result of request:
{
"success": true,
"message": [],
"endpoint": "https://www.salesmanago.pl/customerPreferenceCenter/#/7bd071c1-cb96-45a7-8e95-c512c76189a2/47d82f5a-87d3-11eb-a567-f8a2d6e832bf/?key=240491"
}
Available fields in the request generateEndpoint method:
| Field | Max. length | Description |
|---|---|---|
| preferenceCenterId* | 255 | Customer Preference Center identifier (can be copied from Access tab in the last step of Customer Preference Center wizard, or a pop-up that appears after saving a Center) |
| contactId* | 255 | SALESmanago Contact Identifier (you can use ‘smclient’ cookie value). |
As a result of request we receive:
success – Boolean value informing about the result of request (successful/not successful)
message – Array of additional information enabling error identification
endpoint – URL containing a view of the Customer Preference Center user dashboard. The view is authorized with the key parameter, meaning that contact will not be required to confirm access with an email message.