NAV
API v2 API v3 Frontend SDK
json

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:

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

Technical details

All endpoints are structured in the following way:
https://xxx.salesmanago.com/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 SALESmanagoIntegration CenterMonitoring 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 CenterMonitoring 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.

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://xxx.salesmanago.com/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:

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
questionmark
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
questionmark
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://xxx.salesmanago.com/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://xxx.salesmanago.com/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://xxx.salesmanago.com/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://xxx.salesmanago.com/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:

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

Checking if a contact is already recorded

Sample request data structure:

{
  "clientId": "client-id",
  "apiKey": "api-key-123",
  "requestTime": 1481532212995,
  "sha": "abcd509ac6867955a5333d6eb0c460455c74ccc6",
  "email": "***@gmail.com",
  "owner": "admin@vendor.pl"
}

To check if a contact is already recorded in the database we use the below method: https://xxx.salesmanago.com/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:

success – boolean value informing about the result of request (successful/not successful)
message – array of additional information enabling error identification
result - result of request
contactId - found ID contact

Export basic contacts’ data by email address

Sample request data structure:

{
  "clientId": "client-id-123",
  "apiKey": "api-key-123",
  "requestTime": 1481533177752,
  "sha": "abcd56045567955a533c74ccc6683d09ac6eb0c4",
  "owner": "admin@vendor.pl",
  "email": [
    "piotr***@gmail.com"
  ]
}

The list of basic contacts data export by calling:
https://xxx.salesmanago.com/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://xxx.salesmanago.com/api/contact/basicById

Available fields in the request basicById method:

Field Max. length Description
owner* 255 contact’s owner (SALESmanago user account email)
id* 255 array of identifiers for the exported contacts

Result of request:

{
  "success": true,
  "message": [],
  "contacts": [
    {
      "name": "Piotr",
      "email": "piotr****@gmail.com",
      "phone": "500100100",
      "fax": "",
      "score": 1920,
      "state": "PROSPECT",
      "optedOut": false,
      "optedOutPhone": false,
      "deleted": false,
      "invalid": false,
      "company": "Benhauer",
      "externalId": null,
      "address": {
        "streetAddress": "Grzegórzecka 21",
        "zipCode": "30-555",
        "city": "Kraków",
        "country": "Polska"
      },
      "contactId": "99cdc5fe-7376-436e-acb5-7180c97dadb6",
      "birthdayYear": null,
      "birthdayMonth": null,
      "birthdayDay": null,
      "modifiedOn": 1479215570000,
      "createdOn": 1432887727000,
      "lastVisit": 1481528930000
    }
  ]
}

success – information whether export was successful
message – array of additional information enabling error identification
contacts – exported contacts
name – contact name
email – contact email
phone – contact phone number
fax – contact’s fax number
score – number of points
state – contact’s state (CUSTOMER, PROSPECT, PARTNER, OTHER, UNKNOWN)
optedOut – information whether the contact is unsubscribed from the mailing list
optedOutPhone - information if the contact is unsubscribed from sending sms
deleted – information if the contact is deleted
invalid – information if the contact is invalid
company – contact company name  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 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://xxx.salesmanago.com/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",
      "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
        }
      ],
      "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
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 Contacts by Contact ID

Sample request:

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


  "owner": "salesmanago.user@yourcompany.com",
  "contactId" : ["ab12-...-cd34", "ef56-...-ab78"]
}

To export Contacts by Contact ID, use the following method:
https://xxx.salesmanago.com/api/contact/listById

Fields available in listById method:

Field Max. length Description
owner* 255 Contacts’ owner (SALESmanago user account email)
contactId* 50*36 Array of IDs (UUID) for the Contacts to be exported (** maximum 50 IDs per request **)

Sample response:

{
  "success": true,
  "message": [],
  "contacts": [
    {
      "id": "ab12-...-cd34",
      "name": "John Doe",
      "email": "name@example.com",
      "phone": "+15554443322",
      "fax" : "+15551112233",
      "score": 777,
      "state": "PROSPECT",
      "optedOut": true,
      "optedOutPhone": false,
      "deleted": false,
      "invalid": false,
      "company": "Acme Corporation",
      "externalId": "U12345",
      "address": {
        "streetAddress": "Main Street",
        "zipCode": "AB 00000",
        "city": "Anytown",
        "country": "United States"
      },
      "birthdayYear": 1987,
      "birthdayMonth": 6,
      "birthdayDay": 5,
      "province": "California",
      "mainContactOwner": "salesmanago.user@yourcompany.com",
      "modifiedOn": 1659938888000,
      "createdOn": 1459938888000,
      "purchaseProbability": 0.314159265359,
      "contactVisits": [
        {
          "conversationIntId": null,
          "host": "192.168.1.1",
          "time": 1659938888000,
          "duration": null,
          "visitSource": "NEXT",
          "visitSourceHost": "example.com",
          "visitSourceKeywords": null,
          "visitScore": 1,
          "url": "/example.html",
          "location": null
        }
      ],
      "contactTags": [
        {
          "tag": "SWEATERS",
          "tagName": "SWEATERS",
          "score": 3,
          "createdOn": 1459938888000,
          "tagWithScore": "SWEATERS (3)"
        }
      ],
      "emailMessages": [
        {
          "name": "Special discount code",
          "subject": "Special prize for you 🎁 Redeem before it's gone 😍",
          "date": 1659938888000,
          "sent": true,
          "dateSent": 1659938888000,
          "opened": true,
          "dateOpened": 16599399999000,
          "clicked": false,
          "dateClicked": null,
          "emailConversation": 123456,
          "intId": null,
          "deliveryStatus": null
        }
      ],
      "properties": [
        {
          "name": "sweater_size",
          "value": "XL"
        }
      ],
      "contactFunnels": [
        {
          "salesFunnel": "Example funnel",
          "salesFunnelId": "1234-...-5678",
          "salesStage": "Example stage",
          "salesStageId": "abcd-...-efab"
        }
      ],
      "contactNotes": [
        {
          "note": "Example note",
          "date": 1659938888000,
          "priv": false
        }
      ],
      "contactTasks": [
        {
          "id": "1234-...-5678",
          "note": "Example task",
          "date": 1659938888000,
          "cc": "",
          "reminder": 16599399999000
        }
      ],
      "contactExtEvents": [
        {
          "eventId": "ab12-...-cd34",
          "date": 1659938888000,
          "description": "https://example.com/cartRecovery/controller/cartId=1234-5678-9098",
          "products": "p0123, p4567",
          "location": "examplecom",
          "value": 189.99,
          "contactExtEventType": "PURCHASE",
          "shopDomain":"example.com",
          "detail1": "1,4,1",
          "detail2": "189.99",
          "detail3": "dresses",
          "detail4": "black,black,white",
          "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": "ID-123456"
        }
      ],
      "coupons": [
        {
          "name": "10% Voucher",
          "coupon": "A1B2C3D4",
          "validTo": 16599399999000,
          "used": false
        }
      ],
      "smsMessages": [
        {
          "createdDate": 1659938888000,
          "dateSent": 1659938888000,
          "dateDelivered": 16599399999000,
          "deliveryStatus": true,
          "dateReplied": null,
          "replayMsg": null,
          "content": "Welcome to Example.com",
          "sentBy": "salesmanago.user@yourcompany.com"
        }
      ],
      "consents": [
        {
          "name": "TERMS_OF_SERVICE",
          "description": "I hereby accept TOS",
          "ip": "192.168.0.1",
          "action": "A",
          "createdOn": 1659938888000,
          "source": "F",
          "dateOn": 1546730873000
        },
        {
          "name": "PHYSICAL_MAIL",
          "description": "I hereby consent to receive marketing materials by postal service",
          "ip": "192.168.0.1",
          "action": "D",
          "createdOn": 1459938888000,
          "source": "C",
          "dateOn": 1659938888000
        }      ]
    }
  ],
  "unavailableContacts": ["ef56-...-ab78"]
}

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
contacts—array of objects with Contact data
unavailableContacts—array of Contact IDs to which the given owner has no access

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" : "CONSENTS"},
        {"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": "xxx.salesmanago.com",
          "value": "100.56",
          "contactExtEventType": "CART",
          "detail1": "online",
          "detail2": null,
          "detail3": null,
          "externalId": "externalId"
        }
      ],
      "visitsData": [
        {
          "host": "salesmanago.pl",
          "time": 1245874523658,
          "duration": 200,
          "visitSource": "xxx.salesmanago.com",
          "visitSourceHost": "salesmanago.pl",
          "visitSourceKeywords": "salesmanago",
          "visitScore": 10,
          "url": "/cennik",
          "location": "https://xxx.salesmanago.com"
        },
        {
          "host": "salesmanago.pl",
          "time": 1245874523658,
          "duration": 200,
          "visitSource": "xxx.salesmanago.com",
          "visitSourceHost": "salesmanago.pl",
          "visitSourceKeywords": "salesmanago",
          "visitScore": 10,
          "url": "/cennik",
          "location": "https://xxx.salesmanago.com"
        }
      ],
      "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
        }
      ],
     "contactPropertiesData": [
      {
       "name": "t_shirt_size",
       "value": "XL"
      }
     ],
     "contactDictionaryPropertiesData": [
      {
       "name": "birthday",
       "type": "DATE",
       "value": 1488927600000
      },
      {
       "name": "shoe_size",
       "type": "NUMBER",
       "value": 9
      }
     ]
    }
  },
  {
    "5e428789-08ae-11e7-a63d-28d24400c116": {
      "contactData": {
        "email": "test2@o2.pl",
        "id": "5e428789-08ae-11e7-a63d-28d24400c116",
        "createdOn": 1489493057000,
        "modifiedOn": 1489493303000,
        "name": null,
        "score": null,
        "fax": null,
        "state": "PROSPECT",
        "optedOut": false,
        "optedOutPhone": false,
        "deleted": false,
        "invalid": false,
        "company": null,
        "streetAddress": null,
        "zipCode": null,
        "city": null,
        "country": null,
        "birthday": null,
        "province": null,
        "mainOwner": null,
        "lastOptInOn": 1634671777000,
        "lastOptOutOn": 1634671197000
      },
      "tagData": [
        {
          "tag": null,
          "tagName": "TEST1",
          "score": 1,
          "createdOn": 1489493073000
        },
        {
          "tag": null,
          "tagName": "LESZNO",
          "score": 1,
          "createdOn": 1489493317000
        },
        {
          "tag": null,
          "tagName": "TEST2",
          "score": 1,
          "createdOn": 1489493316000
        }
      ],
      "extEventData": null,
      "visitsData": null,
      "emailsData": [
        {
          "name": "#API: dyn",
          "subject": "Sample API subject",
          "date": 1497445763000,
          "sent": false,
          "dateSent": null,
          "opened": false,
          "dateOpened": null,
          "clicked": false,
          "dateClicked": null,
          "emailConversation": null,
          "deliveryStatus": null
        }
      ],
      "funnelsData": null,
      "notesData": null,
      "tasksData": null,
      "couponsData": null,
      "smsData": null,
     "consentsData": [
      {
       "name": "ZGODA_1",
       "description": "Description1",
       "ip": "0:0:0:0:0:0:0:1",
       "action": "A",
       "createdOn": "2018-10-22",
       "source": "API",
       "dateOn": "2018-10-22"
      },
      {
       "name": "ZGODA_2",
       "description": "Description2",
       "ip": "0:0:0:0:0:0:0:1",
       "action": "D",
       "createdOn": "2018-10-22",
       "source": "API",
       "dateOn": "2018-10-22"
      },
      {
       "name": "ZGODA_3",
       "description": "Description3",
       "ip": "0:0:0:0:0:0:0:1",
       "action": "R",
       "createdOn": "2018-10-22",
       "source": "API",
       "dateOn": "2018-10-22"
      }
     ]
    }
  }
]

API method limits the scope of the exported data to information that is determined in the request. To specify the group of contacts for which you want to export data, use the shared selectors. Selectors function in the same way as in sending emails. Available selectors:

email - email address of a contact,
tag - name of the tag in the system assigned to a contact or contact groups,
contact_id - external contact identifier,
funnel - name of the sales funnel,
stage - name of the stage in the sales funnel (then you need to specify the name of the funnel and the name of the funnel stage which contacts are currently at).

The scope of data to export includes:

CONTACT - basic information about a contact such as the name of the contact, email address, telephone number, etc.,
TAG - list of tags assigned to a contact,
EXT_EVENT - list of contact’s external events (e.g. cart, purchase),
VISITS - number of websites visited by a contact during last 7 days,
EMAILS - list of emails sent to a contact and email analytics (information whether contact opened the email, date, etc.),
FUNNELS - list of sales funnels to which a contact is assigned,
NOTES - list of notes assigned to a contact,
TASKS - list of tasks assigned to a contact,
COUPONS - list of coupons,
SMS - list of the text messages sent to a contact and analytics (information whether contact received the message, date, etc.).
CONSENTS - list of consents (A - accepted, D - deleted, R - rejected)
PROPERTIES - contact attributes defined by the user. It is advised not to use special characters and spaces in the name, but it is allowed
DICTIONARY_PROPERTIES - user-defined attributes of the dictionary, the first to add a particular attribute can be used for the remaining contacts through re-enter the same name and type of the assigned another value.

You need to choose at least one type of data to export (e.g. tag, contact, funnel). Data types are not codependent hence each type of data can be exported separately. Exported data is available in the json file under the shared link.

Below you can find address to which you need to send an export request.
https://xxx.salesmanago.com/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://xxx.salesmanago.com/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://xxx.salesmanago.com/api/contact/createdContacts

Available fields in the request createdContacts method:

Field Max. length Description
owner* 255 contact’s owner (SALESmanago user account email)
from* 255 beginning range of creation dates
to* 255 ending range of creation dates

Result of request:

{
  "success": true,
  "message": [],
  "createdContacts": [
    {
      "id": "c3477890-3da7-4010-96d0-45aab0586b7f",
      "email": "***@gmail.com"
    }
  ]
}

As a result of request we receive:

success – boolean value informing about the result of request (successful/not successful)
message – array of additional information enabling error identification
createdContacts – contacts modified in the given time frame
  id – contact’s ID
  email – contact’s email

Exporting the list of recently modified contacts

Sample structure of request data:

{ 
    "apiKey" : "your-api-key-123",
    "clientId" : "your-client-id-123",
    "requestTime":1362056589362,
    "sha":"64656d78b80d5df677700dabd363e1ffe51b59a7",
    "owner":"admin@vendor.pl",
    "from":1359673200361,
    "to":1363042800362
}

We export contacts using the below method:
https://xxx.salesmanago.com/api/contact/modifiedContacts

Available fields in the request modifiedContacts method:

Field Max. length Description
owner* 255 contact’s owner (SALESmanago user account email)
from* 255 beginning range of modification dates
to* 255 ending range of modification dates

Result of request:

{
    "success":true,
    "message":[],
    "modifiedContacts":[
        {
            "id":"f66ca32b-c117-4b52-b3b8-863be077e710",
            "email":"aleksander.***@benhauer.pl"
        },
        {
            "id":"426e0ef8-675f-47fc-8ea8-745ac1706904",
            "email":"konrad.***@salesmanago.pl"
        },
        {
            "id":"1775d70e-cd61-4dd6-983a-64f067486adf",
            "email":"marek.***@salesmanago.pl"
        }
    ]
}

As a result of request we receive:

success – boolean value informing about the result of request (successful/not successful)
message – array of additional information enabling error identification
modifiedContacts – contacts modified in the given time frame
  id – contact’s ID
  email – contact’s email

Recently modified Contacts (paginated list)

This method lets you get a list of Contacts that were last modified in a specified period. The maximum time span between from and to is 30 days.

Sample request:

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

  "owner": "salesmanago.user@yourcompany.com",
  "from" : 1657267688000,
  "to": 1659938888000,
  "page" : 1,
  "size" : 1000
}

Endpoint:
https://xxx.salesmanago.com/api/contact/paginatedModifiedContacts

Fields available in paginatedModifiedContacts method:

Field Max. length Description
owner* 255 Contact owner (SALESmanago user account email)
from* UNIX timestamp (ms)

The date range of the last modification from which the Contacts are to be listed. The maximum filtering span is 30 days.

to* UNIX timestamp (ms)
page* 1+ Page number starting with 1, from which the results are to be listed
size* 1000 Number of results per page

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

modifiedContacts – array containing the results
contactId – unique ID of the Contact
email – email address of the Contact

Sample response:

{
  "success": true,
  "message": [],
  "modifiedContacts": [
    {
      "id": "c100-...-298c",
      "email": "name@example.com"
    },
    {
      "id": "d256-...-4fe8",
      "email": "name2@example.com"
    }
  ],
  "hasMore": true
}

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://xxx.salesmanago.com/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://xxx.salesmanago.com/api/contact/paginatedContactList/export

Available fields in the request paginatedContactListExport method:

Field Max. length Description
owner* 255 contact’s owner (SALESmanago user account email)
page* - current page
size* - the number of returned lines (up to 1000)

Result of request:

{
   "success": true,
   "message": [
      "Export added to execute."
   ],
   "requestId": 37
}

success – boolean value informing about the result of request (successful/not successful)
message – array of additional information enabling error identification
requestId – the identifier of the export

In response, you will receive “requestId”, which is the export id.

To check the process status, you need to send a POST request to: https://xxx.salesmanago.com/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"
}


Contacts assigned to a specific owner (paginated list)

Sample request:

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

  "owner": "salesmanago.user@yourcompany.com",
  "page": 1,
  "size": 1000
}

This method lets you get a list of Contacts that are assigned to the owner specified in the owner field.

Endpoint:
https://xxx.salesmanago.com/api/contact/paginatedListById

Fields available in paginatedListById method:

Field Max. length Description
owner* 255 Contact owner (SALESmanago user account email)
page* 1+ Page number starting with 1, from which the results are to be listed
size* 1000 Number of results per page

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

hasMore – boolean value informing that there are additional pages containing results for the request

IMPORTANT: The other fields have been described in contact/list method

Sample response:

{
  "success": true,
  "message": [],
  "contacts": [
    {
      "id": "1a2b-...-3c4d",
      "name": "John Doe",
      "email": "name@example.com",
      "phone": "+15554443322",
      "fax": null,
      "score": 123,
      "state": "PROSPECT",
      "optedOut": false,
      "optedOutPhone": false,
      "deleted": false,
      "invalid": false,
      "company": "Big Company LLC",
      "externalId": "U12345",
      "address": {
        "streetAddress": "Main Street 21",
        "zipCode": "90210",
        "city": "San José",
        "country": "US"
      },
      "birthdayYear": 1987,
      "birthdayMonth": 06,
      "birthdayDay": 05,
      "province": "California",
      "mainContactOwner": "salesmanago.user@yourcompany.com",
      "contactVisits": [],
      "contactTags": [
        {
          "tag": "T_SHIRTS",
          "tagName": "T_SHIRTS",
          "score": 12,
          "createdOn": 1659938888000,
          "tagWithScore": "T_SHIRTS (12)"
        }
      ],
      "contactEvents": [],
      "emailMessages": [],
      "properties": [],
      "contactFunnels": [],
      "contactNotes": [],
      "contactTasks": [],
      "contactExtEvents": [],
      "coupons": [],
      "smsMessages": [],
      "modifiedOn": 1559938888000,
      "createdOn": 1459938888000
    },
    {
      "id": "d256-...-4fe8",
      "name": "Victoria Doe",
      "email": "name2@example.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": "salesmanago.user@yourcompany.com",
      "contactVisits": [],
      "contactTags": [],
      "contactEvents": [],
      "emailMessages": [],
      "properties": [],
      "contactFunnels": [],
      "contactNotes": [],
      "contactTasks": [],
      "contactExtEvents": [],
      "coupons": [],
      "smsMessages": [],
      "modifiedOn": 1549938888000,
      "createdOn": 1449938888000
    }
  ],
  "hasMore": true
}

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://xxx.salesmanago.com/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://xxx.salesmanago.com/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://xxx.salesmanago.com/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

Sample request with basic data:

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

    "owner": "salesmanago.user@yourcompany.com",
    "email": "name@example.com",
    "contactEvent": {
        "date": 1659938888000,
        "contactExtEventType": "PURCHASE",
        "products": "p0123, p4567",
        "value": 189.99,
        "location": "examplecom"
    }
}

Sample request with advanced data:

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

  "owner": "salesmanago.user@yourcompany.com",
  "email": "name@example.com",
  "contactEvent": {
    "date": 1659938888000,
    "contactExtEventType": "PURCHASE",
    "products": "p0123, p4567",
    "value": 189.99,
    "location": "examplecom",
    "externalId": "ID-123456",
    "detail1": "1,4,1",
    "detail2": "189.99",
    "detail3": "dresses",
    "detail4": "black,black,white",
    "description": "https://example.com/cartRecovery/controller/cartId=1234-5678-9098"
  }
}

You can add a new External Event using the below method:
https://xxx.salesmanago.com/api/v2/contact/addContactExtEvent

What are External Events?

External Events represent the most important actions performed by a Contact, such as buying products (PURCHASE) or adding them to the cart (CART). You can use External Events to create Automation Processes, build transaction statistics, and feed data for product recommendation strategies.

Important: An External Event can only be assigned to an existing Contact. If a Contact does not exist in SALESmanago when you transfer an External Event using the v2/contact/addContactExtEvent method, the system will wait 5 minutes and try to add the External Event again. The system will be making attempts to add the Event for 1 hour. If after 1 hour the Contact still does not exist in SALESmanago, the External Event will not be added.

Field Max. length Description
owner* 255 Contact’s owner (SALESmanago user account email)
email* 254[?] Email of Contact to whom the External Event is added
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.
date* timestamp UNIX timestamp [ms]
contactExtEventType* enum External Event type, e.g. PURCHASE, CART
products 512 A comma-separated list of product IDs.
Important: The product IDs sent in the Event should match the product IDs from the Product Catalog / XML Product Feed
value float (19.2) Value of the Event (e.g., purchase total)
E-shop ID (location) 36 Store identifier that matches the location field provided when creating the Product Catalog / XML Product Feed. It allows you to link an External Event with products from a specific store (or from a specific language version of a store).

The location field can contain a maximum of 36 characters (only letters a-z, A-Z, numbers 0-9, and _ character). The value must not start with a number.

Tip: You can use the domain name without the dot, such as examplecom (or examplecom_ES for a specific language version of the store).
externalId 255 Additional External Event identifier, e.g. order ID from the eCommerce platform
detail1 20x255 External Event details that you can use in Automation Processes, in the content of emails or when exporting data via API.

Examples of use: number of products purchased, value or category of the most expensive product, payment method, shipping method, packaging method
detail2
detail…
description 2048 A general-purpose field that can be used for order notes, order summary link, cart recovery link etc.

External Event types:

SALESmanago offers a number of External Event types. PURCHASE and CART Events are automatically taken into account in analytics. The other types of External Events are general-purpose types—you can use them to submit any action performed by a Contact.

List of available External Event types:

Result of request:

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

  "eventId": "0e8c-...-9ba2c",
  "contact": {
    "email": "name@example.com",
    "contactId": null,
    "emailOrContactId": "name@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

eventId – Unique identifier of the External Event. You can use it to update an External Event using the updateContactExtEvent method (e.g. when adding another product to the cart)
contact – object with basic Contact information (email address or contactId)

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://xxx.salesmanago.com/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

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://xxx.salesmanago.com/api/v2/contact/updateContactExtEvent

Available fields in the request updateContactExtEvent method:

Field Max. length Description
owner* 255 contact’s owner (SALESmanago user account email)
eventId* 255 event ID (returned by the add method)
date* timestamp event date (timestamp, i.e. time in milliseconds that passed from midnight 1 January 1970 UTC)
description 2048 event description
products 512 optional list of products separated with commas
E-shop ID (location)* 36 unique shop identifier – this identifier is used to connect information about the product sent in the external event with a particular product feed. Maximum number of characters without spaces is 36 (possible characters: letters a-z, numbers 1-9, /_-.). Unique shop identifier has to be exactly the same as the value in the LOCATION field in external events sent from a particular shop. IMPORTANT: If you have only one product feed, the system will connect an external event and the product feed that you have in the system automatically. When you use multistore option, remember about coherence in sending external events with a unique identifier.
value (19 2) optional event value e.g. the amount spent (max 19 digits + 2 after the decimal point)
contactExtEventType* 255 event type, allowed values: PURCHASE, CART, VISIT, PHONE_CALL, OTHER, RESERVATION, CANCELLED, ACTIVATION, MEETING, OFFER, DOWNLOAD, LOGIN, TRANSACTION
detail1-20 255/detal optional event details,
externalId 255 optional event ID, e.g. ID from a teller system, etc.
shopDomain - optional shop domain

Result of request:

{ 
  "eventId":"7284e317-3bb6-4505-afbe-55b9a101339a",
  "message" : [  ],
  "success" : true 
}

As a result of request we receive:

success – boolean value informing about the result of request (successful/not successful)
eventId – ID of added event
message – array of additional information enabling error identification

Removal of External Event

You can remove External Events using API method:
https://xxx.salesmanago.com/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://xxx.salesmanago.com/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:

success – boolean value informing about the result of request (successful/not successful)
message – array of additional information enabling error identification
result - result of method call is used/error depending on success or failure of given call

Adding coupon for contact

Sample request data structure:

{
  "clientId": "client-id",
  "apiKey": "api-key-123",
  "requestTime": 1481528920123,
  "sha": "abcd5460455c09ac6eb0c74cc333dc66867955a5",
  "name": "Coupon123",
  "email": "***@gmail.com",
  "length": 7,
  "valid": 1484207320124,
  "coupon": "couponVal"
}

You can add coupon via API method call:
https://xxx.salesmanago.com/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:

success – boolean value informing about the result of request (successful/not successful)
message – array of additional information enabling error identification
result - result of request
coupon - created coupon value

API - Funnels

Adding funnel

Sample structure of request data:

{
  "clientId": "clientId",
  "apiKey": "apiKey",
  "requestTime": 1234567896541,
  "sha": "4f69782e826841f794080cae87648e42",
  "owner": "owner@mail.com",
  "funnel": "funnel_name",
  "group": "funnel group",
  "potValue": 4,
  "stages" : [
    {"name": "stage name", "order": 1},
    {"name": "second stage name", "order": 2}
  ]
}

To add funnels, use the method:
https://xxx.salesmanago.com/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://xxx.salesmanago.com/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://xxx.salesmanago.com/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://xxx.salesmanago.com/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

Export of tag list

Sample structure of request data:

{ 
  "apiKey" : "your-api-key-123",
  "clientId" : "your-client-id-123",
  "showSystemTags" : true,
  "owner" : "admin@vendor.pl",
  "requestTime" : 1329128188409,
  "sha" : "02bfe70541d3907cf487f26dc2665b184b1221a7"
}

Tags are exported using the below method:
https://xxx.salesmanago.com/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 an email

Sample structure of request data:

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


  "user": "salesmanago.user@yourcompany.com",
  "emailId": "1a2b-...-3c4d",
  "date": 1659938888000,
  "contacts": [
    {
      "addresseeType": "EMAIL",
      "value": "name1@example.com, name2@example.com, name3@example.com",
      "properties": [
        {
          "name": "conference_name",
          "value": "Global Innovations Summit"
        },
        {
          "name": "start_time",
          "value": "11:00"
        }
      ]
    },
    {
      "addresseeType": "CONTACT_ID",
      "value": "1a2b-...-3c4d, 1a2b-...-3c4d, 2b3c-...-4d5e, 3c4d-...-5e6f",
      "properties": [
        {
          "name": "discount",
          "value": "20%"
        }
      ]
    },
    {
      "addresseeType": "TAG",
      "value": "UPSELL, CROSSELL",
      "properties": [
        {
          "name": "discount",
          "value": "20%"
        }
      ]
    },
    {
      "addresseeType": "FUNNEL",
      "value": "AIDA, Conversion",
      "properties": [
        {
          "name": "discount",
          "value": "20%"
        }
      ]
    },
    {
      "addresseeType": "STAGE",
      "value": "AIDA",
      "optValue": "Awareness, Interest"
    }
  ],
  "excludeContacts": [
    {
      "addresseeType": "EMAIL",
      "value": "name4@example.com, name5@example.com, name6@example.com"
    },
    {
      "addresseeType": "TAG",
      "value": "FREQUENT_BUYER"
    }
  ]
}

To send an email through API, use the following method:
https://xxx.salesmanago.com/api/email/sendEmail

Fields available in the sendEmail method:

Field Max. length Description
user* 255 SALESmanago user account email address
emailId* 255 Email ID from SALESmanago system
date* UNIX timestamp (ms) Scheduled sending date
contacts* - Array of Contacts to whom the email should be sent
addresseeType* 255 Addressee type (EMAIL, CONTACT_ID, TAG, FUNNEL, STAGE)

IMPORTANT: If the selected addressee type is EMAIL and a provided email address does not exist in the SALESmanago database, this email address will be added as a new Contact with opt-in status for Email Marketing.
value* 255 Depending on addresseeType:
  • Contact’s email address,
  • Contact ID,
  • tag
  • funnel name
optValue 255 Field only for addresseeType: STAGE.

Provide the stage(s) of the funnel (specified in the value field) from which Contacts are to be selected. Separate stage names with commas.
properties 255 Additional email personalization.

Include a placeholder having the following format: $cst.parameterName$ in the email content in SALESmanago. In API, in the properties field, specify the name and value of the attribute with which the placeholder will be replaced.

Only a-zA-Z0-9 and _ characters are recommended in attribute names.
excludeContacts - Array of Contacts that will be excluded from the recipient list

Sample request:

{
  "success": true,
  "message": [
    "Emails are scheduling to send."
  ],
  "conversationId": "f1e2-...-d3c4"
}

A response to a successful request contains the following fields:

success – boolean value indicating the result of the request (successful/not successful)
message – array of additional information, including error messages
conversationId - mailing identifier

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 ➔ Email Marketing ➔ Settings ➔ Sender 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 subscription confirmation

Sample request using email language parameter:

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

  "owner": "salesmanago.user@yourcompany.com",
  "email": "name@example.com",
  "tag": "CSV_IMPORT",
  "doubleOptInLanguage": "ES"
}

Sample request using email ID parameter:

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

  "owner": "salesmanago.user@yourcompany.com",
  "email": "name@example.com",
  "tag": "CSV_IMPORT",
  "doubleOptInEmailId": "6d5c-...-0102"
}

Sample response:

{
  "success": true,
  "message": ["Contact exists - confirmation email sent"],

  "contactExists": true,
  "contactId": "1a2b-...-3c4d"
}

This method lets you send a subscription confirmation email, also known as double opt-in, to existing Contacts with opt-out status. You can also specify an additional parameter tag to target only those Contacts marked with that tag.

Endpoint:
https://xxx.salesmanago.com/api/email/sendConfirmation

Available fields in the request sendConfirmation method:

Field Max. length Description
email* 254[?] Contact’s email address
owner* 255 Contact’s owner (SALESmanago user account email)
tag 255 Optional parameter defining a tag that a Contact must be marked with in order for a subscription confirmation email to be sent to them
doubleOptInLanguage 255 Subscription confirmation email, indicated using one of the following options:
- language, as mapped in SALESmanago ➔ Email Marketing ➔ Settings ➔ Subscription confirmation languages,
- email ID, included in the URL when editing the subscription confirmation email
doubleOptInEmailId 255

As a result of request we receive:

success – boolean value informing about the result of request (successful/not successful)
message – array of additional information containing error messages
contactExists – boolean value informing whether a particular Contact exists in SALESmanago
contactId – Contact ID that you can use to identify a Contact later on

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",
  "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,
  "immediate": false,
  "rule": false
}

In order to send an email through API the below method should be used:
https://xxx.salesmanago.com/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
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:

success – boolean value informing about the result of request (successful/not successful)
message – array of additional information enabling error identification
conversationId – email conversation identifier

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://xxx.salesmanago.com/api/email/massConversationList

Available fields in the request massConversationList method:

Field Max. length Description
from* Timestamp beginning range of conversations creation dates
to* Timestamp ending range of conversations creation dates

Result of request:

{
  "success": true,
  "message": [],
  "conversationList": [
    "86dfe8bd-f21d-4f5e-9f53-19c929877d3c",
    "5c27d476-282d-4235-9393-300d359b2d51"
  ]
}

As a result of request we receive:

success – boolean value informing about the result of request (successful/not successful)
message – array of additional information enabling error identification
conversationList - mass email conversations identifiers list

Statistics of sent emails

Sample request with conversationId:

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


  "user": "salesmanago.user@yourcompany.com",
  "conversationId": "a254-...-5ed9"
}

Sample request with time range:

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


  "user": "salesmanago.user@yourcompany.com",
  "from": "1649938888000",
  "to": "1659938888000",
  "requestType": "MAILING",
  "exportType": "FULL"
}

You can get statistics of sent emails using the below method:
https://xxx.salesmanago.com/api/email/conversationStatistics

Fields available in conversationStatistics method:

Field Max. length Description
user* 255 SALESmanago user’s email address. Statistics will be downloaded only for emails whose author is the specified user.
conversationId 255 Conversation ID, visible in the URL of email’s analytics.
Note: When this field is present, fields from, to and conversationType are ignored.
from timestamp(ms) Starting date of the export range—date in UNIX timestamp format [ms].
Note: This field is required if conversationIdis not specified.
to timestamp(ms) Ending date of the export range—date in UNIX timestamp format [ms].
Note: This field is required if conversationId is not specified.
conversationType 255 Type of emails:
  • MAILING
  • CYCLIC
  • TEST_AB
  • FINAL_TEST_AB
  • BIRTHDAY
If this field is not present, all email types are returned.
exportType 255 Export scope:
  • BASIC
  • SHORT
  • FULL
The default value is FULL.

Result of request:

{
  "success": true,
  "message": [],
  "requestId": 123456
}

Method used to get file URL:
/api/job/status
See docs >>

Sample file structure for BASIC exportType and conversationId specified:

{
  "conversationId": "a254-...-5ed9",
  "name": "Sample conversation name",
  "subject": "Sample conversation subject",
  "dateSent": 1609938888000,
  "sentBy": "salesmanago.user@yourcompany.com",
  "sentMessage": 1000,
  "openedMessage": 800,
  "uniqueOpens": 500,
  "clickedMessage": 300,
  "uniqueClicks": 200,
  "errorMessage": 0,
  "softBounce": 10,
  "hardBounce": 20,
  "resigned": 0,
  "testAB": false,
  "message": []
}


Sample file structure for SHORT exportType and conversationId specified:

{
  "conversationId": "a254b80b-fac2-4401-b0a1-6eda1bf45ed9",
  "name": "Your conversation name",
  "subject": "Your conversation subject",
  "dateSent": 1668755462468,
  "sentBy": "name@example.com",
  "sentMessage": 100,
  "openedMessage": 120,
  "uniqueOpens": 50,
  "clickedMessage": 30,
  "uniqueClicks": 20,
  "errorMessage": 0,
  "softBounce": 10,
  "hardBounce": 10,
  "resigned": 0,
  "testAB": false,
  "contacts": [
    "contact1@example.com",
    "contact2@example.com"
  ]
}

Sample file structure for FULL exportType and conversationId specified:

{
  "conversationId": "a254-...-5ed9",
  "name": "Sample conversation name",
  "subject": "Sample conversation subject",
  "dateSent": 1609938888000,
  "sentBy": "salesmanago.user@yourcompany.com",
  "sentMessage": 1000,
  "openedMessage": 800,
  "uniqueOpens": 500,
  "clickedMessage": 300,
  "uniqueClicks": 200,
  "errorMessage": 0,
  "softBounce": 10,
  "hardBounce": 20,
  "resigned": 0,
  "testAB": false,
  "openedBy": [
    {
      "email": "name1@example.com",
      "contactId": "f35c-...-684e",
      "dateOpened": 1659938888000,
      "dateClicked": 1659938899000,
      "optedOut": false
    }
  ],
  "clickedBy": [
    {
      "email": "name1@example.com",
      "contactId": "f35c-...-684e",
      "dateOpened": 1659938888000,
      "dateClicked": 1659938899000,
      "optedOut": false
    }
  ],
  "softBouncedBy": [
    "nam2@example.com"
  ],
  "hardBouncedBy": [
    "nam3@example.com"
  ],
  "resignedBy": [
    {
      "email": "name4@example.com",
      "contactId": "a123-...-54bc",
      "dateOpened": 1659937777000,
      "dateClicked": 1659937788000,
      "optedOut": true
    }
  ]
}

Sample file structure for BASIC exportType and time range specified:


  [
    {
        "conversationId": "a254-...-5ed9",
        "name": "Sample conversation name",
        "subject": "Sample conversation subject",
        "dateSent": 1609938888000,
        "sentBy": "salesmanago.user@yourcompany.com",
        "sentMessage": 1000,
        "openedMessage": 800,
        "uniqueOpens": 500,
        "clickedMessage": 300,
        "uniqueClicks": 200,
        "errorMessage": 0,
        "softBounce": 10,
        "hardBounce": 20,
        "resigned": 0,
        "testAB": false
    },
    {
        "conversationId": "a254-...-5ed9",
        "name": "Another conversation name",
        "subject": "Another conversation subject",
        "dateSent": 1619938888000,
        "sentBy": "salesmanago.user@yourcompany.com",
        "sentMessage": 2000,
        "openedMessage": 1600,
        "uniqueOpens": 1000,
        "clickedMessage": 600,
        "uniqueClicks": 400,
        "errorMessage": 0,
        "softBounce": 20,
        "hardBounce": 40,
        "resigned": 0,
        "testAB": false
    }
  ]

The exported file contains:

message—array of additional information containing error messages

Fields present for BASIC export type:
conversationId—conversation identifier
name—email name
subject—email subject
dateSent—UNIX timestamp [ms]
sentBy—sender account
sentMessage—number of sent emails
openedMessage—number of times the email has been opened
uniqueOpens—number of Contacts who opened the email
clickedMessage—number of times the email has been clicked
uniqueClicks—number of Contacts who clicked the email
errorMessage—number of failed emails
softBounce—number of soft bounces
hardBounce—number of hard bounces
resigned—number of Contacts who opted out by clicking the link in a given email
testAB—boolean value; true for emails that were a part of A/B test

Additional fields for SHORT export type:
contacts—array of recipients’ email addresses

Additional fields for FULL export type:
openedBy—array of Contacts who opened the email
clickedBy—array of Contacts who clicked the email
softBouncedBy—array of Contacts who were marked as soft bounce
hardBouncedBy—array of Contacts who were marked as hard bounce
resignedBy—array of Contacts who opted out by clicking the link in a given email

Data structure for the above arrays (FULL export type):
email—Contact’s email address
contactId—Contact identifier
externalId—External Contact identifier
dateOpened—UNIX timestamp [ms]
dateClicked—UNIX timestamp [ms]
optedOut—boolean value; true for Contacts who opted out by clicking the link in the given email

IMPORTANT: Array contacts is not present in FULL export type

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://xxx.salesmanago.com/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://xxx.salesmanago.com/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://xxx.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:

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

Send messages

Sample request:

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

  "templateName": "abcd-...-1234",
  "user": "salesmanago.user@example.com",
  "contacts": [
    {
      "addresseeType": "EMAIL",
      "value": "name1@example.com, name2@example.com"
    }
  ],
  "name": "Sample conversation name",
  "sender": "Example sender",
  "textContent": "Visit example.com and get up to 50% off",
  "shortenLinks": false,
  "messagingChannelIntegration": [
    {
      "channel": "SMS",
      "provider": "APIFONICA"
    },
    {
      "channel": "VIBER",
      "provider": "OCTAPUSH"
    }
  ],
  "allowDiacritics": true
}

In order to send messages, the below method should be used:
https://xxx.salesmanago.com/api/messaging/send

Fields available in send method:

Field Max. length Description
sender 255 Sender name/ID
name* 255 Message name to easily identify it in the system
templateName 255 You can specify only one of these fields: Either the name of the template or text content of the message.
textContent
messagingChannelIntegration 255 List of integrated messaging channels. Consists of pairs of type key-value, where:
  • channel—type of channel (SMS, WHATS_APP, VIBER)
  • provider—name of the gateway provider
contacts* Array of contact objects with fields specified below:
  • value
  • optValue
  • addresseeType (enum): EMAIL, CONTACT_ID, TAG, FUNNEL, STAGE, ID, OPTED_OUT, OPTED_IN, PHONE_OPTED_OUT, PHONE_OPTED_IN, INVALID, MONITORED, NOT_MONITORED
user* 254 User’s email
shortenLinks Boolean value which defines whether links should be shortened. Default false.
time Time of sending in milliseconds. The earliest allowed value is one day before now, effectively setting the time to now. The latest allowed value is 1 year from now. The default value is now.
allowDiacritics Boolean value which defines whether diacritical characters are allowed. Default false.

Result of request:

{
  "success": true,
  "message": ["Scheduled sending"],
  "conversationId": 1
}

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 enabling error identification

conversationId - Conversation’s identifier

List of mass conversations

Sample request:

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

  "from": "1649938888000",
  "to": "1649938889000",
  "source": "MASS"
}

In order to get a list of mass Mobile Marketing conversations in a given time period, the below method should be used:

https://xxx.salesmanago.com/api/messaging/conversationList

Fields available in conversationList method:

Field Max. length Description
from* 255 UNIX timestamps in ms.
The maximum time range for sources RULE and WORKFLOW is 7 days.
The maximum time range for other sources is 30 days.
to* 255
source ENUM Enum value; allows you to filter the list by messaging source type.
Allowed values:
  • BIRTHDAY
  • MASS
  • RULE
  • WORKFLOW
  • TEST
  • ALERT
  • RFM
  • ALL
Default value: MASS

Result of request:

{
  "success": true,
  "message": [],
  "conversationIds": [123456,234567,3456789]
}

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 enabling error identification

conversationIds – List of conversations identifiers

Get conversation data

Sample request:

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

  "conversationId": 12345
}

In order to get conversation data the below method should be used:

https://xxx.salesmanago.com/api/messaging/mass/conversation/data

Fields available in conversation/data method:

Field Max. length Description
conversationId* int Conversation identifier

Result of request:

{
  "success": true,
  "message": [],
  "messagingContentList": [
    {
      "name": "Spring Campaign",
      "date": 1649938888000,
      "textContent": "Visit example.com and get up to 50% off",
      "phone": "+15554443322",
      "contactId" : "1a2b-...-3c4d",
      "externalId": null,
      "channel" : "SMS"
    },
    {
      "name": "Spring Campaign",
      "date": 1659938888000,
      "textContent": "Visit example.com and get up to 50% off",
      "phone": "+15554443333",
      "contactId" : "1a2b-...-3c4d",
      "externalId": null,
      "channel" : "SMS"
    },
    {
      "name": "Spring Campaign",
      "date": 1669938888000,
      "textContent": "Example Visit example.com and get up to 50% off",
      "phone": "+15554443344",
      "contactId" : "1a2b-...-3c4d",
      "externalId": null,
      "channel" : "SMS"
    }
  ]
}

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 enabling error identification

messagingContentList – List of conversation data objects

Messaging statistics

Sample request:

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

  "conversationId": 123456,
  "channel": "SMS",
  "source": "MASS"
}

In order to get Mobile Marketing messages stats the below method should be used:
https://xxx.salesmanago.com/api/messaging/conversationStats

Fields available in conversationStats method:

Field Max. length Description
conversationId* 36 Messaging conversation ID as returned by the send method. You can also find the conversation ID in the URL in the sent message analytics.
channel 100 Enum value allowing you to filter statistics by channel type. Allowed values:
  • SMS
  • VIBER
  • WHATS_APP
  • ALL
The ALL value is the default one.
source 255 Enum value allowing you to filter statistics by messaging source type. Allowed values:
  • BIRTHDAY
  • MASS
  • RULE
  • WORKFLOW
  • TEST
  • ALERT
  • RFM
  • ALL
The ALL value is the default one.

Result of request:

{
  "success": true,
  "message": [],
  "conversationTemplateId": 9876543,
  "sentDate": 1659938888000,
  "user": "salesmanago.user@example.com",
  "name": "Spring Campaign",
  "statistics": {
    "SMS": {
      "cancelled": false,
      "sent": 1200,
      "delivered": 1150,
      "undelivered": 50,
      "clicked": 800
    },
    "VIBER": {
      "cancelled": false,
      "sent": 1200,
      "delivered": 1150,
      "undelivered": 50,
      "clicked": 800
    }
  }
}

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 enabling error identification

conversationTemplateId – ID of the used message template
sentDate – Date the message was sent on as UNIX timestamp [ms]
user – SALESmanago user to whom the conversation is assigned
name – name of the message visible in SALESmanago
SMS/WHATS_APP/VIBER – object containing statistics from a given channel
cancelled – logical value informing whether the messaging was canceled in a given channel
sent – number of sent messages in a given channel
delivered – number of delivered messages in a given channel
undelivered – number of undelivered messages in a channel
clicked – number of clicked messages in a channel

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://xxx.salesmanago.com/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://xxx.salesmanago.com/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://xxx.salesmanago.com/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://xxx.salesmanago.com/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

Get URL of file with exported data

Sample request:

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

  "owner": "salesmanago.user@yourcompany.com",
  "requestId": 1234567
}

You can get the URL of the file containing exported data using the API method:
https://xxx.salesmanago.com/api/job/status

Asynchronous exports

A number of API methods allows you to asynchronously export data to a JSON file. This allows the HTTP connection to be closed, while the export is being processed in the background. Depending on the export scope, it may take up to several minutes which greatly exceeds the maximum connection time, and thus would not be possible with synchronous requests. The typical export consists of:
   1. Export request that returns the requestId
   2. Periodic job/status request that given a requestId returns JSON file URL
   3. GET request to download the JSON file
The recommended interval for requesting a JSON file with job/status is 60 seconds.

Response before the exported is completed:

{
  "success": true,
  "message": [
    "Job not start yet"
  ]
}

Available fields in job/status method:

Field Max. length Description
owner 255 Contacts’ owner (SALESmanago user account email)
requestId int Unique request identifier as received from the export method

Sample response after the exported is completed:

{
  "success": true,
  "message": [],
  "fileUrl": "https://storage.googleapis.com/sm-file/a1b2-...-c3d4/1234-...-5678/abcd-...-efgh.json?GoogleAccessId=..."
}

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
fileUrl – URL of the file with export data, valid for a few minutes after it has been generated. Important: This field is returned only when the export is completed.

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://xxx.salesmanago.com/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://xxx.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://xxx.salesmanago.com/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 PushSent 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://xxx.salesmanago.com/api/web/push/ids

Available fields of the request web/push/ids:

Field Max. length Description
from* Timestamp the beginning of the date range of sent web push notifications
to* Timestamp the end of the range date of sent web push notifications

As a result of request we receive:

{
    "success": true,
    "message": [],
    "webPushIds": [
        1,2,3
    ]
}

As a result of request we receive:

success – boolean value informing about the result of the request (successful/not successful)
message – array of additional information enabling error identification
webPushIds - the list of sent web push notifications’ id

Web Push notification ID list

Sample structure of request data:

{
  "apiKey": "test123test",
  "clientId" : "ye4vodnswfo6zp75",
  "sha" : "dsadsadasdsadsadsadsadsadsadb",
  "requestTime" :1626774053,
  "from":1595238047,
  "to":1626774053
}

Use the following method to get a list of Web Push Notification IDs:
https://xxx.salesmanago.com/api/notification/conversation/ids

Complete the available fields in the request to authorise the method:

Field Max. length Description
apiKey* - API key
clientId* - user id
sha* - generated sha
requestTime* - time the request was made (ms)
from* - modification date (ms), from which contacts will be searched
to* - modification date (ms), to which contacts will be searched

Result of request:

{
  "success": true,
  "message": [
    "Conversation list"
  ],
  "pushConversationIds": [
    16,
    17,
    18,
    19
  ]
}

As a result of the request you will get:

success – boolean value informing about the result of request (successful/not successful)
message – array of additional information enabling error identification
pushConversationIds – array of web push id

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://xxx.salesmanago.com/api/notification/consent/form/stats

Complete the available fields in the request to authorise the method:

Field Max. length Description
apiKey* - API key
clientId* - user id
sha* - generated sha
requestTime* - time the request was made (ms)
user* 255 user email
intId* form id

Result of request:

{
  "success": true,
  "message": [
    "Export added to execute."
  ],
  "requestId": 2660
}

As a result of the request you will get:

success – boolean value informing about the result of request (successful/not successful)
message – array of additional information enabling error identification
requestId – number value of request

In response, you will receive “requestId”, which is the export id.

To check the process status, you need to send a POST request to: https://xxx.salesmanago.com/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://xxx.salesmanago.com/api/notification/push/stats

Complete the available fields in the request to authorise the method:

Field Max. length Description
apiKey* - API key
clientId* - user id
sha* - generated sha
user* 255 user email
itemId* user email
webPushSourceType* webpush type

Result of request:

{
  "success": true,
  "message": [
    "Export added to execute."
  ],
  "requestId": 2659
}

As a result of the request you will get:

success – boolean value informing about the result of request (successful/not successful)
message – array of additional information enabling error identification
requestId – number value of request

In response, you will receive “requestId”, which is the export id.

To check the process status, you need to send a POST request to: https://xxx.salesmanago.com/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://xxx.salesmanago.com/api/notification/consent/form/data

Using this method, when you request with a specific Client’s ID, you’ll get the information about the ID and the name of the form the contact is subscribed to.

Complete the available fields in the request to authorise the method:

Field Max. length Description
apiKey* - API key
clientId* - user id
sha* - generated sha
requestTime* - time the request was made (ms)

Result of request:

{
  "success": true,
  "message": [],
  "consentFormList": [
    {
      "intId": 101045,
      "name": "Nowy formularz zgody 2021-06-22 14:49"
    },
    {
      "intId": 101044,
      "name": "Nowy formularz zgody 2021-06-02 12:05"
    }
  ]
}

As a result of the request you will get:

success – boolean value informing about the result of request (successful/not successful)
message – array of additional information enabling error identification
consentFormList – array of object with intId and form name
intId – number value of form id
name – string value of form name

API - Loyalty Program

Adding contact to Loyalty Program

Sample structure of request data:

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

We’re adding contact to Loyalty Program by using the below method:
https://xxx.salesmanago.com/api/loyalty/program/v1/addContact

Available fields in the request addContact method:

Field Max. length Description
owner* 255 contact’s owner (SALESmanago user account email)
contacts* 255 array of contacts to adding.
loyaltyProgram* 255 name of loyalty program

Result of request:

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

As a result of request we receive:

success – boolean value informing about the result of request (successful/not successful)
message – array of additional information enabling error identification
points – number of points

Removing contact from Loyalty Program

Sample structure of request data:

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

We’re removing contact from Loyalty Program by using the below method:
https://xxx.salesmanago.com/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://xxx.salesmanago.com/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://xxx.salesmanago.com/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:

success – Boolean value informing about the result of request (successful/not successful)
message – Array of additional information enabling error identification
points – Number of points collected by a contact in a selected loyalty program

API - Product recommendation

Last viewed products

Sample request:

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

  "contactUuid": "1a2b-...-3c4d",
  "shopName": "Example Store"
}

In order to get the list of last viewed products, use the below method:
https://xxx.salesmanago.com/api/recommendation/lastViewed

Fields available in lastViewed method:

Field Max. length Description
contactUuid* UUID Contact ID from SALESmanago; you will receive it in response to each request when adding or modifying a Contact.
shopName* 64 Name of the Product Catalog / XML Product Feed. Not to be confused with the location field.

Result of request:

{
  "message": [],
  "success": true,
  "productIds": [
    "5678",
    "9876"
  ]
}

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
productIds – array of product IDs

Most purchased products

Sample structure of request data:

{
  "clientId": "your-client-id-123",
  "apiKey": "salesmanago",
  "requestTime": 1481543324302,
  "sha": "02bfe70541d3907cf487f26dc2665b184b1221a7",
  "shopName": "dataSource"
}

In order to get most purchased products we use the below method:
https://xxx.salesmanago.com/api/recommendation/mostPurchased

Available fields in the request mostPurchased:

Field Max. length Description
shopName* 255 data source name

Result of request:

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

As a result of request we receive:

success – boolean value informing about the result of request (successful/not successful)
message – array of additional information enabling error identification
productIds – array of product ids

Products purchased by contact (only for monitored contacts)

Sample structure of request data:

{
  "clientId": "your-client-id-123",
  "apiKey": "salesmanago",
  "requestTime": 1481543324302,
  "sha": "02bfe70541d3907cf487f26dc2665b184b1221a7",
  "smClient": "fecfca38-1f97-437d-91c4-2f30a67e31fa",
  "shopName": "dataSource"
}

In order to get products purchased by contact we use the below method:
https://xxx.salesmanago.com/api/recommendation/purchasedByContact

Available fields in the request purchasedByContact:

Field Max. length Description
shopName* 255 data source name
smClient* 255 smclient cookie value

Result of request:

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

As a result of request we receive:

success – boolean value informing about the result of request (successful/not successful)
message – array of additional information enabling error identification
productIds – array of product ids

Products purchased with the product being viewed

Sample structure of request data:

{
  "clientId": "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://xxx.salesmanago.com/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:

success – boolean value informing about the result of request (successful/not successful)
message – array of additional information enabling error identification
productIds – array of product ids

API - Cinderella AI

Getting product recommendations based on image recognition

Sample structure of request data:

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

  "imageUrl": "https://example.com/temp/uploads/a1b2c3d4e5.jpg",
  "location": "examplecom"
}

Description:

You can get a list of IDs of products which are visually similar to a photo uploaded by a contact. To get a list, use this API method:

Endpoint

https://xxx.salesmanago.com/api/vision

Fields available in vision method:

Field Max. length Description
imageUrl* 2048 URL of a photo uploaded by a contact accessible by SALESmanago servers
location* 64 Location field defined when creating an XML Product Feed / Product Catalog. You can check the value of the field in SALESmanago → Integration Center → Product Catalogs.

Result of request:

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

  "vision": {
    "status": "ok",
    "photo": "https://example.com/temp/uploads/a1b2c3d4e5.jpg",
    "result": [
      {
        "id": "p0123",
        "score": 0.9589041829109192
      },
      {
        "id": "p3456",
        "score": 0.94405747056007385
      },
      {
        "id": "p5678",
        "score": 0.9198060393333435
      }
    ],
    "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 containing error messages
status – status of the image-based search
photo – URL of the uploaded image
result – array of objects containing search results
id – product ID
score – decimal value within 0-1 range indicating the visual similarity of the product to the photo uploaded by a contact
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://xxx.salesmanago.com/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://xxx.salesmanago.com/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.