General information

What is the SALESmanago API used for?

SALESmanago API is one of many ways you can integrate your eCommerce website or other software with SALESmanago. Like any other API connection, using SALESmanago API requires at least some technical knowledge, with a deeper understanding needed for more advanced integrations.

Authorization data

{
  "clientId":"your-client-id-123",
  "apiKey":"your-api-key-123",
  "requestTime":1327056031488,
  "sha":"2aa3927a7dee8c2a712adb5375f5fa36dd8fe00c"
}

Authentication

SALESmanago API is open for our clients, meaning that all of them can integrate without additional fees. To start using our API you will first need to obtain authentication data:

clientId – your Client identifier that can be found in SALESmanago ➔ Integration Center ➔ API (API v2 tab).
apiKey – any random string of characters.
sha – value generated from sha1(apiKey+clientId+apiSecret), where the plus sign is used for concatenation. The value of apiSecret is unique for each client and can be found in the aforementioned API v2 tab.

All requests must also contain requestTime – a UNIX timestamp in milliseconds.

Technical details

All endpoints are structured in the following way:
https://xxx.salesmanago.pl/api
where xxx is the ID of your SALESmanago server (in most cases this will be either www, app2, or app3).

All requests are sent using HTTP POST method and are encapsulated in JSON format. As such, the following headers are required:
Accept: application/json, application/json
Content-Type: application/json;charset=UTF-8
Note that most HTTP libraries include those headers on their own when you send a JSON object in the request body.

Monitoring code integration

The Monitoring Code is responsible for monitoring the Contacts on your website and thus highly recommended to implement. To make sure the Monitoring Code does not impact the performance of your website, all JavaScript is loaded asynchronously after the page has loaded.

alt text

You can find your Monitoring Code in SALESmanago ➔ Integration Center ➔ Monitoring Code. This script should be added to your website just before the
</body> closing tag. If your website is custom-built, you should be able to easily add the Monitoring Code to the template. If your website is based on third-party software, you can try searching for “[platform name] add custom javascript”. You can also add the Monitoring Code using Google Tag Manager. To do this, log in to SALESmanago account, navigate to Integration Center ➔ Monitoring Code, and click the button in Use Google Tag Manager (GTM) section.

Email validation

Email addresses are verified according to the RFC882 standard. The at sign must be preceded by up to 64 characters and followed by a valid Internet domain; up to 254 characters in total.

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.

API - Contact management

Adding a new contact or modifying the existing one

Sample request with basic data:

{
  "clientId": "a1b2-...-c3d4",
  "apiKey": "e5f6-...-g7h8",
  "requestTime": 1659938888000,
  "sha": "2aa3-...-e00c",

  "owner": "salesmanago.user@yourcompany.com",
  "contact": {
    "email": "name@example.com",
    "phone": "+15554443322",
    "name": "John Doe",
    "externalId": "U12345",
    "address": {
      "streetAddress": "Main Street 21",
      "zipCode": "90210",
      "city": "San José",
      "country": "US"
    }
  },
  "province": "California",
  "birthday": "19870605",

  "forceOptIn": true,
  "forceOptOut": false,
  "forcePhoneOptIn": false,
  "forcePhoneOptOut": true,

  "tags": [
    "T_SHIRTS",
    "SWEATERS",
    "UPSELL"
  ],
  "removeTags": [
    "FIRST_PURCHASE"
  ]
 }

Sample request with advanced fields:

{
  "clientId": "a1b2-...-c3d4",
  "apiKey": "e5f6-...-g7h8",
  "requestTime": 1659938888000,
  "sha": "2aa3-...-e00c",

  "owner": "salesmanago.user@yourcompany.com",
  "contact": {
    "email": "name@example.com",
    "phone": "+15554443322",
    "fax" : "+15551112233",
    "name": "John Doe",
    "externalId": "U12345",
    "state" : "PROSPECT",
    "address": {
      "streetAddress": "Main Street 21",
      "zipCode": "90210",
      "city": "San José",
      "country": "US"
    }
  },
  "province": "California",
  "birthday": "19870605",

  "forceOptIn": true,
  "forceOptOut": false,
  "forcePhoneOptIn": false,
  "forcePhoneOptOut": true,
  "useApiDoubleOptIn": true,
  "doubleOptInLanguage": "ES",

  "newEmail": "new.email@example.com",

  "tags": [
    "T_SHIRTS",
    "SWEATERS",
    "UPSELL"
  ],
  "removeTags": [
    "FIRST_PURCHASE"
  ],

  "properties": {
    "t_shirt_size": "XL",
    "gender": "Male"
  },
  "dictionaryProperties": [
    {
      "name": "member_since",
      "type": "DATE",
      "value": 1459938888000
    },
    {
      "name": "shoe_size",
      "type": "NUMBER",
      "value": 10
    }
  ],

  "consentDetails": [
    {
      "consentName": "TERMS_OF_SERVICE",
      "consentAccept": true,
      "agreementDate": 1659938888000,
      "ip": "192.168.0.1",
      "optOut": false,
      "consentDescriptionId": 1234
    },
    {
      "consentName": "PHYSICAL_MAIL",
      "consentAccept": false,
      "agreementDate": 1659938888000,
      "ip": "192.168.0.1",
      "optOut": true,
      "consentDescriptionId": 5678
    }
  ]
}

Sample response:


{
  "contactId" : "1a2b-...-3c4d",
  "message" : [],
  "success" : true,
  "externalId": "U12345"
}

You can add or modify a contact by using API method:
https://www.salesmanago.pl/api/contact/upsert

Basic fields:

The only mandatory fields are the authentication fields, the owner field and the email address of the Contact. However, to unlock the full potential of SALESmanago, you can send more Contact data. Later you will then use it in Automation Processes, personalization, segmentation, and other features.

Field	Max. length	Description
owner*	255	Contact’s owner (SALESmanago user account email)
contact	object	Object containing basic Contact’s data
name	255	Contact name
email*	254^[?]	Contact email
contactId	UUID	Contact ID from SALESmanago; you will receive it in response to each request when adding or modifying a Contact. If you identify the Contact using `contactId`, the `email` field is optional.
phone	255	Contact phone number
fax	255	Contact fax number
company	255	Contact company
externalId	255	External Contact identifier, e.g. user identifier from the eCommerce platform
birthday	8	Contact’s date of birth, sent in the form of a string: yyyyMMdd or MMdd where yyyy – a four-digit year, MM – a two-digit month, dd – a two-digit day
address	object	Object containing Contact’s address
streetAddress	255	Street address and apartment number
zipCode	255	Zip code (post code)
city	255	Town/city
country	255	Country, the alpha-2 ISO 3166-1 format is recommended
province	255	Administrative division within a country, e.g. California

Contact’s consents:

New Contacts added to SALESmanago have their Email Marketing status set by default to opt-in, while Mobile Marketing status is set to opt-out. This is useful when you integrate a newsletter subscription form. However, if you transfer contacts from another form, where giving consents is not obligatory, remember to change the statuses of the consents.

Field	Max. length	Description
forceOptIn	true/false	Flag indicating consent to Email Marketing
forceOptOut	true/false	Flag indicating withdrawal of consent to Email Marketing
useApiDoubleOptIn	true/false	Flag indicating if the opt-in status should be confirmed using double opt-in. This applies only to contacts changing their status to opt-in.
doubleOptInLanguage	255	Contact’s language to be used when sending double opt-in email
forcePhoneOptIn	true/false	Flag indicating consent to Mobile Marketing
forcePhoneOptOut	true/false	Flag indicating withdrawal of consent to Mobile Marketing

You can also send other types of consents to SALESmanago, e.g. Consent to the Terms of Service or consent to traditional marketing mailing. For this purpose, use custom consents. Define them in SALESmanago Settings ➔ Other ➔ Consents List. You can update the consent description, which will create a newer version and overwrite the existing one. SALESmanago stores the information which version of the consent has been given/rejected by the Contact.
Using the consentAccept and optOut fields you can set one of three consent statuses on the Contact Card. To do this, send the appropriate consentAccept and optOut flags:

consentAccept=false, optOut=false – consent not confirmed,
consentAccept=true, optOut=false – consent confirmed,
consentAccept=false, optOut=true – consent withdrawn,
consentAccept=true, optOut=true – consent withdrawn.

If a contact already has a “confirmed” or “withdrawn” consent status - it cannot be changed to a “not confirmed” status.

Field	Max. length	Description
consentDetails	array of objects	Array of objects containing additional consents given by the Contact. Each consent type must be predefined in SALESmanago Settings ➔ Other ➔ Consents List.
consentName	255	Name of the consent
consentAccept	true/false	Boolean value of consent (true or false)
agreementDate	UNIX timestamp [ms]	Date of consent. If you do not send this date, the consent will be assigned with the current timestamp.
ip	255	IP address of the Contact.
optOut	true/false	Boolean value of consent withdrawal (true or false).
consentDescriptionId	true/false	Consent description identifier. You can find this identifier in SALESmanago Settings ➔ Other ➔ Consents List.

Additional Contact details

There are three ways to transfer additional Contact details that you can use in Automation Processes, personalization, segmentation, and other features. Enrich your data using:

1. Tags — the most basic additional information. They only have value, so you can assign multiple tags within the same area, e.g. DOG_FOOD, CAT_FOOD.
2. Standard details — more elaborate type of additional information. Standard details are text-based pairs consisting of keys and values, e.g. detail name: trip_direction, value: Bulgaria, or detail name: car_brand, value: TESLA. Both the key and the value can be up to 255 characters long. They don’t have to be predefined in SALESmanago.
3. Dictionary details—similar to standard details. They are pairs consisting of keys and values, with support for number and date values, e.g. detail name: wedding_date, value 1653861600000 (i.e. May 30, 2022), or detail name: shirt_size, value: 12. Dictionary details are defined system-wide, meaning that if you define a dictionary detail for one contact, the detail field will be created for all contacts. You can see the list of dictionary details in SALESmanago Settings ➔ Other ➔ Dictionary Details.

Field	Max. length	Description
tags	255/tag	Array of tags to be assigned to a Contact. Tags can contain standard Latin alphabet characters and underscore characters. If the transferred tags contain unsupported characters, they will be automatically adjusted to the format supported by the system. Special characters will be replaced with the underscore character (_), and diacritical characters will be replaced with their Latin alphabet equivalent.
removeTags	255/tag	Array of tags to be removed. Adding the same tag to both arrays, will remove the tag completely.
properties	255/detail	Array of standard details specified as key-value pairs. It’s not recommended to use special characters, diacritics, or spaces in detail names.
dictionaryProperties	array of objects	Array of objects containing dictionary details definitions. Dictionary details might contain number or date values. If you define a dictionary detail for one contact, the detail will be defined for all contacts.
name	3-255	Detail name. It’s not recommended to use special characters, diacritics, or spaces in the details names.
type	enum NUMBER, DATE	Dictionary detail type: NUMBER or DATE
value	255	Dictionary detail value. For type NUMBER: Positive integer. For type DATE: Unix timestamp [ms] value.

Advanced fields:

You can use advanced fields to change the Contact’s email address or state, send a specific subscription confirmation message or decide how the request is processed.

Field	Max. length	Description
newEmail	254^[?]	New email address (if you want to modify it). Changing the email address of a contact is only possible if the contact is identified with the current email address.
async	true/false	A parameter specifying how to add a Contact to SALESmanago. The default and recommended value is “true”, the selection of which will initiate the execution of the process asynchronously. This means that you will receive the contactId value immediately, while the Contact data will be updated with a slight delay. If you choose to process the Contact synchronously, your request may take more than 1000 ms.
state	enum CUSTOMER, PROSPECT, PARTNER, OTHER, UNKNOWN	Contact status (CUSTOMER, PROSPECT, PARTNER, OTHER, UNKNOWN).
doubleOptInEmailId**	255	Optional ID of email for double opt-in

As a result of request you will receive:


success - boolean value informing about the result of request (successful/not successful)
contactId - unique ID of the Contact. In most cases this identifier should be set as smclient cookie in the Contact’s browser
message - array of additional information containing error messages
externalId - external contact identifier
The useApiDoubleOptIn flag overrides the forceOptIn flag. Using useApiDoubleOptIn together with forceOptIn with cause forceOptIn to be ignored.

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"
      },
      "consentDetails": [
        {
          "consentName": "AGREEMENT",
          "consentAccept": true,
          "agreementDate": 1391167515515,
          "ip":"192.168.7.139",
          "optOut": false,
          "consentDescriptionId": 1
        }
      ],
      "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)
upsertDetails*	1000	Array of Contact objects
email*	254^[?]	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	254^[?]	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
email	254^[?]	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*	254^[?]	contact email

Result of request:

{
  "success": true,
  "message": [],
  "result": "Contact deleted"
}

As a result of request we receive:

It can be used with userId param
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*	254^[?]	contact’s email

Result of request:

{
  "success": true,
  "message": [],
  "result": true,
  "contactId": "99cdc5fe-7376-436e-acb5-7180c97dadb6"
}

As a result of request we receive:

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*	254^[?]	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
    }
  ]
}

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*	254^[?]	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 – emails from the past 3 months
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 contacts’ data

Exemplary json:

{
  "clientId": "yourcliendID",
  "apiKey": "yourAPIkey",
  "requestTime": 1500556989,
  "sha": "4afd12754c746fa9f71648f2e2276ae40eccfe41",
  "owner": "admin@vendor.pl",
  "dateRange": {
    "startDate": 1652359692,
    "endDate": 1652359694
  },
  "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).
externalId - contact external id

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:

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:

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
}

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- 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 (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",
    "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**	254^[?]	contact’s email for which the event is added
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*	254^[?]	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 (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:

Removal of External Event

You can remove External Events using API method:
https://www.salesmanago.pl/api/v2/contact/deleteContactExtEvent

Sample structure of request data:

Using eventId:

{
  "clientId": "your-client-id-123",
  "apiKey": "your-api-key-123",
  "requestTime": 1645453269000,
  "sha": "3e4ec39722326150aae60f41e038d1def4450f46",
  "owner": "owner@example.com",
  "eventId": "7284e317-3bb6-4505-afbe-55b9a101339a"
}

Using externalId:

{
  "clientId": "your-client-id-123",
  "apiKey": "your-api-key-123",
  "requestTime": 1645453269000,
  "sha": "3e4ec39722326150aae60f41e038d1def4450f46",
  "owner": "owner@example.com",
  "externalId": "A-123123123"
}

Result of a request:

{
  "success": true,
  "message": [],
  "result": "Ext event has been scheduled to delete."
}

{
  "success": false,
  "message": ["No eventId/externalId specified"],
  "result": null
}

Available fields in the deleteContactExtEvent method:

Field	Max. length	Description
owner*	255	Contact’s owner (SALESmanago user account email)
eventId**	255	Event ID (returned by addContactExtEvent method)
externalId**	255	External Event ID

** You have to specify at least one of them. If you specify both, the eventId will take priority.

As a result of request you’ll receive:

success – Boolean value informing about the result of request (successful/not successful)
message – Array of additional information enabling error identification
result – An additional information with the result success = true: (“Ext event has been scheduled to delete.”)

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*	254^[?]	contact email
coupon*	255	coupon name

Result of request:

{
  "success": true,
  "message": [],
  "result": null
}

As a result of request we receive:

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*	254^[?]	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
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:

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 - Tags management

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 (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:

Adding or updating an email

Sample request:

{
  "clientId": "client-id-123",
  "apiKey": "api-key-123",
  "requestTime": 1481535098734,
  "sha": "abcd56045567955a533c74ccc6683d09ac6eb0c4",
  "emailId": "1234-...-abcd",
  "emailOwner": "user@example.com",
  "name": "Special discount code",
  "utmCampaign": "Spring/summer campaign",
  "subject": "Special prize for you 🎁 Redeem before it's gone 😍",
  "senderAccountId": "6789-...-efgh",
  "content": "<html><body>...$opt-out$...</body></html>",
  "shared": false
}

In order to add or update an email the below method should be used: https://xxx.salesmanago.com/api/email/upsert

Fields available in the email/upsert method:

Field	Max. length	Description
*emailId*	UUID	Email identifier used during update of already existing email
*emailOwner**	255	SALESmanago user to who should be the owner of created email. You cannot change the email owner during an update.
*name**	255	Email name used to identify email in SALESmanago
*group*	255	Group name to which the email should be assigned. If you leave this field empty, the email will be assigned to a default group.
*subject**	998	Email subject. You can use UTF-8 characters.
*senderAccountId**	UUID	SALESmanago sender account identifier. You can get this value from SALESmanago ➔ Settings ➔ Email Accounts.
*content**	2 MB	HTML email content
*shared*	bool	Flag that allows you to share this email with other users within the same SALESmanago account. The default value is false.
*utmCampaign*	255	Parameter (utm_campaign) used to track your campaign, for example using Google Analytics.

Result of request:

{
  "message": [],
  "success": true,
  "emailId": "1234-...-abcd"
}

As a result of request you will receive:

emailId – email identifier you can use to update the email contents.

success – boolean value informing about the result of request (successful/not successful)

message – array of additional information enabling error identification

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*	254^[?]	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:

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*	254^[?]	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:

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:

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:

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
        }
  ]
}

Export of global statistics for sent emails

Sample structure of the request data:

{
  "clientId": "your-client-id-123",
  "apiKey": "your-api-key-123",
  "requestTime": 1645453269000,
  "sha": "3e4ec39722326150aae60f41e038d1def4450f46",
  "user": "owner@example.com",
  "from": 1645453269000,
  "to": 1645453270000,
  "conversationType": "MAILING"
}

You can export global email statistics using the API method:
https://www.salesmanago.com/api/email/globalConversationStatistics

Fields available in the method apiGlobalConversationStatistics:

Field	Max. length	Description
from*	-	starting date of the export range – date in UNIX timestamp format [ms]
to*	-	ending date of the export range – date in UNIX timestamp format [ms]
conversationType	enum: SMTP, AD_HOC, MAILING, RULE, W, API, TEST_AB, FINAL_TEST_AB, BIRTHDAY, CYCLIC, SCHEDULED, BIRTHDAY_YR, TEST	Type of emails for which statistics are to be exported. If the type is not specified, all the statistics for mass emails will be exported.

Available types of mass emails:

MAILING
TEST_AB
FINAL_TEST_AB
BIRTHDAY
BIRTHDAY_YR
CYCLIC
SCHEDULED

Result of the request:

{
  "success": true,
  "message": [],
  "from": 1645453269000,
  "to": 1645453270000,
  "sent": 32997135,
  "opened": 4115080,
  "clicked": 874927,
  "openedUnique": 2683298,
  "clickedUnique": 471739,
  "softBounce": 647244,
  "hardBounce": 30128,
  "resigned": 6868
}

As a result of the request you will receive:

success – export completion status
message – an array of additional details that allows to identify the error
from – starting date
to – ending date

and statistical data of the indicated range and type:

sent – number of emails sent
opened – number of emails opened
clicked – number of emails clicked
openedUnique – number of unique opens
clickedUnique – number of unique clicks
softBounce – number of soft returns
hardBounce – number of hard bounces
Read more about soft and hard bounces >>
resigned – number of contacts who unsubscribed from newsletter using the footer link

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**	254^[?]	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 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:

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.

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*	254^[?]	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

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)

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

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

Workflow Statisctics

Sample structure of the request data:

{
    "clientId": "axf46o35hgrf015q",
    "apiKey": "test123test",
    "requestTime": 1348046897664,
    "sha": "3436a3efd8c63f72c8ba827d53d1297482e6d85d",
    "workflowId": 10032430,
    "period": "PREVIOUS_YEAR"
}

In order to download workflow statisctics use this method:
https://www.salesmanago.com/api/workflow/statistics

Available fields in the request /api/workflow/statistics: This method does not require any additional fields.

Result of the request:

{
    "success": true,
    "message": [],
    "name": "New Workflow 2022-02-23 12:53",
    "creationDate": 1645617296,
    "launchesNumber": 0,
    "revenueStats": {
        "totalSales": 0.0,
        "totalLastClickSales": 0.0,
        "totalTransactionNumber": 0,
        "totalLastClickTransactionNumber": 0,
        "emailSales": 0.0,
        "emailLastClickSales": 0.0,
        "emailTransactionNumber": 0,
        "emailLastClickTransactionNumber": 0,
        "webPushSales": 0.0,
        "webPushClickSales": 0.0,
        "webPushTransactionNumber": 0,
        "webPushLastClickTransactionNumber": 0,
        "smsSales": 0.0,
        "smsClickSales": 0.0,
        "smsTransactionNumber": 0,
        "smsLastClickTransactionNumber": 0
    },
    "emailStats": {
        "averageOr": "-",
        "uniqueOpens": 0,
        "allOpens": 0,
        "averageCtr": "-",
        "uniqueClicks": 0,
        "allCliks": 0,
        "averageCtor": "-",
        "optOut": "-",
        "contactsOptOut": 0,
        "sentMessages": 0,
        "messageToSend": 0,
        "failedMessages": 0,
        "spam": 0,
        "softBounces": 0,
        "hardBounces": 0
    }
}

As a result of the request we receive:

success – wartość logiczna informująca o rezultacie zapytania (udane / nieudane)
message – tablica dodatkowych informacji pozwalająca zidentyfikować błąd
name - nazwa workflow
creationDate - lista nieusuniętych workflow 2.0
launchesNumber - id workflow
revenueStats - id workflow
totalSales -
totalLastClickSales -
totalTransactionNumber -
totalLastClickTransactionNumber -
emailSales -
emailLastClickSales -
emailTransactionNumber -
emailLastClickTransactionNumber -
webPushSales -
webPushClickSales -
webPushTransactionNumber -
webPushLastClickTransactionNumber -
smsSales -
smsClickSales -
smsTransactionNumber -
smsLastClickTransactionNumber -
emailStats -
averageOr -
uniqueOpens -
allOpens -
averageCtr -
uniqueClicks -
allClicks -
averageCtor -
optOut -
contactsOptOut -
sentMessages -
messageToSend -
failedMessages -
spam -
softBounces -
hardBounces -

API - Web Push

Downloading statistics of sent Web Push notification

Sample request:

{
  "clientId": "a1b2-...-c3d4",
  "apiKey": "e5f6-...-g7h8",
  "requestTime": 1659938888000,
  "sha": "2aa3-...-e00c",

  "wizardId": 123456
}

You can download statistics of sent Web Push notification using the below method:
https://www.salesmanago.pl/api/web/push/stats

Fields available in web/push/stats method:

Field	Max. length	Description
wizardId*	Long (19)	Identifier that was assigned to the sent Web Push notification. To find the identifier, go to Web Push ➔ Sent Notifications and click Analytics next to a given entry. The identifier can be found in the URL.

Result of request:

{
  "success": true,
  "message": [],

  "name": "Example Web Push",
  "date": 1630150200000,
  "totalSent": 500,
  "anonymousSent": 200,
  "totalOpened": 150,
  "totalClicked": 100,
  "richWebPushOpened": 100,
  "richWebPushClicked": 50,
  "sent": [
    "name01@example.com",
    "name02@example.com",
    "name03@example.com",
    "name04@example.com",
    "..."
  ],
  "opened": [
    "name01@example.com",
    "name02@example.com",
    "name03@example.com",
    "name04@example.com",
    "..."
  ],
  "clicked": [
    "name01@example.com",
    "name02@example.com",
    "..."
  ]
}

As a result of request you will receive:

success – boolean value informing about the result of request (successful/not successful)
message – array of additional information containing error messages

name – Web Push notification name
date – sent on date
totalSent – sent Web Push count
anonymousSent – count of Web Push notifications sent to anonymous Contacts
totalOpened – count of delivered Web Push notifications
totalClicked – count of clicked Web Push notifications
richWebPushOpened – count of delivered Rich Web Push notifications
richWebPushClicked – count of clicked Rich Web Push notifications
sent – list of Contact email addresses to whom the Web Push has been sent
opened – list of Contact email addresses to whom the Web Push has been delivered
clicked – list of email addresses of the Contacts that have clicked the 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:

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:

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:

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:

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"
}

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:

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:

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

Returning the number of points in the Loyalty Program

Sample structure of request data:

{
  "clientId": "clientId",
  "apiKey": "apiKey",
  "requestTime": 1481543324302,
  "sha": "sha1",
  "owner": "admin@vendor.pl",
  "email": "email@addresseeType.pl",
  "loyaltyProgram": "Loyalty Program Name"
}

You can check the number of points of specific contact in a selected Loyalty Program using API method:
https://www.salesmanago.pl/api/loyalty/program/v1/getPoints

Available fields in the request getPoints method:

Field	Max. length	Description
clientId*	-	user id
apiKey*	-	API key
sha*	-	generated sha
owner*	-	user email
requestTime*	-	time the request was made (ms)
email*	254^[?]	contact’s email
loyaltyProgram*	255	name of loyalty program

Result of request:

{
  "message": [],
  "success": true,
  "points": 123
}

As a result of request we receive:

API - Product recommendation

Last viewed products

Sample structure of request data:

{
  "clientId": "axf46o35hgrf015q",
  "apiKey": "Hh39uCkBdxTAXAvQE9Ng",
  "requestTime": 1658927874000,
  "sha": "480f4dc004753394507ec94cf8c84fa26f413623",
  "contactUuid": "280f2138-44fb-4c14-aea2-ff0eef25ae1f",
  "shopName": "name"
}

In order to get last viewed products we use the below method:
https://www.salesmanago.pl/api/recommendation/lastViewed

Fields available in lastViewed method:

Field	Max. length	Description
contactUuid*	36	Contact Id in UUID format
shopName*	64	data source name

Result of request:

{
  "message" : [  ],
  "success" : true,
  "productIds" : [
    6754,
    6755
  ]
}

Result of request (error):

{
  "success": false,
  "message": [
    "Contact UUID is null or incorrect"
  ],
  "productIds": null
}

As a result of request you will receive:

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:

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:

Products purchased with the product being viewed

Sample structure of request data:

{
  "clientId": "axf46o35hgrf015q",  
  "apiKey": "Hh39uCkBdxTAXAvQE9Ng",  
  "requestTime": 1481543324302,  
  "sha": "480f4dc004753394507ec94cf8c84fa26f413623",  
  "productId": "5",  
  "shopName": "name"
}

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 method:

Field	Max. length	Description
shopName*	64	data source name
productId*	32	product id

Result of request:

{
  "message" : [  ],
  "success" : true,
  "productIds" : [
    6754,
    6755
  ]
}

Result of request (error):

{
  "success": false,  
  "message": [
    "Product Id is invalid"  
  ],  
  "productIds": null
}

As a result of request you will receive:

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.

Frontend Integration

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.

alt text

[ 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>

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>

General information

What is the SALESmanago API used for?

Authentication

Technical details

Monitoring code integration

Email validation

Sending additional monitoring data

API - Contact management

Adding a new contact or modifying the existing one

Basic fields:

Contact’s consents:

Additional Contact details

Advanced fields:

Asynchronous adding or modifying many contacts simultaneously

Deleting many contacts simultaneously

Deleting a contact

It can be used with userId paramChecking if a contact is already recorded

Export basic contacts’ data by email address

Export basic contacts’ data by contact ID

Export based on email address for the owner

Export based on contact’s ID for the owner

Export contacts’ data

Exporting the list of recently created contacts

Exporting the list of recently modified contacts

Paginated modified contacts list

Contacts’ activity

Paginated contacts list export

Paginated contacts list for provided owner

Changing the main contact owner

Stop contacts’ monitoring

Restore contacts’ monitoring

API- External events

Adding an external event (recommended)

Adding many contact external events simultaneously

Modifying external event (recommended)

Removal of External Event

API - Managing discount coupons

Redemption of coupon for contact

Adding coupon for contact

API - Funnels

Adding funnel

Adding contacts to the funnel

Deleting funnel/stage

Getting the number of contacts in the funnel/stage

API - Tags management

Export of tag list

API - Email messages

Sending email (recommended)

Adding or updating an email

Sending your subscription confirmation

Sending email with attachment

Downloading email messages

Downloading Mass Conversation

Downloading Mass Conversation - Direct emails

Downloading conversation statistics

Downloading contacts to whom email was sent

Export of global statistics for sent emails

API - SMS messages

SMS sending

Downloading Mass Conversation

Downloading statistics of SMS campaigns by conversation ID

Dowloading statistics of SMS campaigns by conversation name

Downloading SMS conversation statistics

API - Tasks

Contacts’ tasks

API - Notes

Adding note

API - Other

Temporary authorization

Getting list of user accounts for a client

API - Workflow

Downloading the list of Workflow 2.0

Workflow Statisctics

API - Web Push

Downloading statistics of sent Web Push notification

Downloading the list of web push notification identifiers

Web Push notification ID list

Export consent forms statistics to a file accessible from the repository

Export Web Push notifications statistics to a file accessible from the repository

Name and ID of a consent form

It can be used with userId param
Checking if a contact is already recorded