General information

Authentication

SALESmanago API v3 uses a new and simpler authentication mechanism. The only authentication field required is a Header API-KEY containing your API key. You can create a new API key in SALESmanago ➔ Integration Center ➔ API ➔ API v3.

Example:

<?php
    curl_setopt($ch, CURLOPT_HTTPHEADER, array(
        'API-KEY: S7LOELpItzOXVAZzMa…VEMbIJL6EH4Z45TTgK'
        )
    );
?>

Note: You can specify when your API key expires, as well as revoke an already created API key. If you have trouble with authentication, start by verifying that your API key is valid. The key status can be checked in the same place where you create new keys.

Header name: API-KEY
Header value: API key from SALESmanago

Validations

To make sure the data transferred to SALESmanago is well-structured, ordered, and easily accessible we use validations for some specific fields. The most important validations include:

Data type	Standard	External resources
Email	RFC882	RFC882 at ietf.org
URL	Apache URL validator	UrlValidator at apache.org
Currency	ISO 4217	ISO 4217 at SIX
Language	ISO 639-1	ISO 639-1 at loc.gov
Language and region	BCP 47	BCP 47 codes at Microsoft

Methods and Content-Types

SALESmanago API v3 uses two HTTP methods:

POST – used for inserting, updating, and deleting data. It is also used when asynchronously downloading data from SALESmanago
GET – used when synchronously downloading data from SALESmanago

All POST requests must be encapsulated in JSON format. Most libraries automatically add Content-Type: application/json header when sending data encapsulated in JSON.

General errors and warnings

It’s only those who do nothing that make no mistakes. – Joseph Conrad

SALESmanago API is designed to gracefully accept all data that meet the requirements and reject only those requests that cannot be processed. Below you can find a list of general errors and warnings with Reason codes assigned to them.

Error/warning	Reason code	HTTP
Authentication error `Error message`	10	400
Field exceeds limit `fieldName\|min:0\|max:256\|Error message`	11	400
Data trimmed warning `fieldName\|max:256\|Warning message`	12	200
Missing required field `fieldName\|Error message`	13	400
Wrong field type `fieldName:type\|Error message`	14	400
Using non-unique value `fieldName\|Error message`	15	400
Trying to access resource with identifier not present in SALESmanago `fieldName\|Error message`	16	400
Trying to set a required value as null `fieldName\|Error message`	17	400
Value not matching a required structure (RegEx) `fieldName\|Error message`	18	400
Trying to add a resource above available limit `resourceName\|limit:3\|Error message`	19	400

Emails

List emails

Sample request:

{
    "type": "STANDARD",
    "dateFrom": 1559938888,
    "dateTo": 1659938888
}

You can list emails created in SALESmanago to display them in an external system. This could be useful when creating an integration that allows you to send emails directly from an eCommerce platform or to list emails available for subscription confirmation.

Endpoint:

https://api.salesmanago.com/v3/email/list

Method:

GET

Body (JSON):

Field	Limits	Description
type	enum	Specify the types of emails you want to list or export: STANDARD SUBSCRIPTION_CONFIRMATION The default value is STANDARD
dateFrom*	UNIX timestamp in s	Starting date of export. The modified on date is used.
dateTo*	UNIX timestamp in s	Ending date of export. The modified on date is used.

Response:

The response will contain a maximum of 100 emails. If your export contains more than 100 emails you can use the modifiedOn date of the last email from the array as dateFrom parameter for your next export.

Field	Description
emails	Array of emails created in SALESmanago
emailId	Internal SALESmanago email identifier
sender	Object containing information about sending account
accountId	Internal SALESmanago sender identifier
emailAddress	Sender email address
displayName	Sender display name. Most email clients use this field when displaying the email sender in a form: Display Name < email.address@example.com >.
modifiedOn	Last modification date of email
name	Email name as specified in SALESmanago
subject	Email subject
designedIn	Field specifying how the email was created. The enum can be: HTML DND ZIP FREEMARKER URL
group	Email group as specified in SALESmanago
author	SALESmanago user who has created the email

Sample response:

{
    "emails": [
        {
            "emailId": "1234-...-5678",
            "sender": {
                "accountId": "abcd-...-dcba",
                "emailAddress": "sender@example.com",
                "displayName": "Example Sender"
            },
            "modifiedOn": 1559938888,
            "name": "My example email",
            "subject": "Just a subject example",
            "designedIn": "DND",
            "group": "Example group",
            "author": "salesmanago.user@example.com"
        },
        {
            "emailId": "8765-...-4321",
            "sender": {
                "accountId": "abcd-...-dcba",
                "emailAddress": "sender@example.com",
                "displayName": "Example Sender"
            },
            "modifiedOn": 1659938888,
            "type": "STANDARD",
            "name": "Another example email",
            "subject": "Simple subject example",
            "designedIn": "HTML",
            "group": "Example group",
            "author": "salesmanago.user@example.com"
        }
    ]
}

Product management

Creating a Product Catalog

Sample request:

{
  "catalogName": "Example.com Product Catalog",
  "setAsDefault": false,
  "currency": "USD",
  "location": "examplecom"
}

This method lets you create a Product Catalog – an entity representing your online store. Product Catalogs are crucial for many functionalities in SALESmanago, including Recommendation Frames, emails with product blocks, dynamic WebPushes, and more.

To maintain backwards compatibility with XML Product Feeds, you need to specify a location field when creating a new Product Catalog. This field is used when assigning external events (such as CART or PURCHASE) to a proper Product Catalog.

Some properties of Product Catalogs can be updated, including catalog name, currency, or location. To identify a Product Catalog, use the catalogId value. You can always check the catalogId value in SALESmanago ➔ Integration Center ➔ Product Catalogs.

Endpoint:

https://api.salesmanago.com/v3/product/catalogUpsert

Method:

POST

Body (JSON):

Field	Limits	Description
catalogName*	64	Internal name of the Product Catalog to help you identify it in SALESmanago. Allowed characters: `a‑zA‑Z0‑9 and _`
catalogId	36	Catalog identifier that is used to update an existing catalog. Do not specify when creating a new one.
setAsDefault	bool	Flag used to determine if Product Catalog should be available for Recommendation Frames
currency*	ISO 4217	ISO currency code, e.g. USD, EUR, etc.
location*	255 only a-zA-Z0-9_ cannot start with a digit	Legacy field for assigning products to External Events.

Sample response:

{
  "catalogId": "21c2-...-3266",
  "message":[]
}

Listing Product Catalogs

This method lets you get a list of all Product Catalogs created in SALESmanago as well as the maximum number of Product Catalogs that can be created on your account.

Endpoint:

https://api.salesmanago.com/v3/product/catalogList

Method:

GET

Request parameters:

This GET method expects no additional parameters.

Response:

Field	Description
problems	Array of additional information, including error messages
catalogId	Unique identifier of the Product Catalog, required when adding products to Catalog
setAsDefault	Flag specifying if the Product catalog can be used in recommendations (true) or analytics only (false)
currency	Currency as specified during Catalog creation
location	Location field used to match the External Event with Product Catalog
max	Total maximum number of Product Catalogs that can be created on your account.

Sample response:

{
  "catalogs": [
    {
      "catalogId": "21c2-...-3266",
      "name": "Example.com Product Catalog",
      "setAsDefault": false,
      "currency": "USD",
      "location": "examplecom"
    },
    {
      "catalogId": "a2d4-...-f0e3",
      "name": "Online Store Catalog",
      "setAsDefault": true,
      "currency": "EUR",
      "location": "myonlinestore"
    }
  ],
  "limits": {
    "max": 3
  }
}

Adding or updating a product

Sample request:

{
  "catalogId": "21c2-...-3266",
  "products": [
    {
      "productId": "1234",
      "name": "Turtleneck sweater",
      "mainCategory": "sweaters",
      "categoryExternalId": "8642",
      "description": "Classic sweater with...",
      "productUrl": "https://example.com/shop/sweaters/turtleneck-sweater",
      "mainImageUrl": "https://example.com/media/turtleneck-sweater-cover.jpg",
      "available": true,
      "price": 79.99,
      "systemDetails": {
        "manufacturer": "My Brand",
        "gender": 0,
        "color": "black"
      }
    },
    {
      "productId": "1235",
      "name": "White t-shirt",
      "mainCategory": "t-shirts",
      "categoryExternalId": "1050",
      "categories": [
        "Winter collection",
        "Linen products"
      ],
      "description": "Classic t-shirt with...",
      "productUrl": "https://example.com/shop/t-shirts/white-t-shirt",
      "mainImageUrl": "https://example.com/media/white-t-shirt-cover.jpg",
      "imageUrls": [
        "https://example.com/media/white-t-shirt1.jpg",
        "https://example.com/media/white-t-shirt2.jpg",
        "https://example.com/media/white-t-shirt3.jpg"
      ],
      "available": true,
      "active": true,
      "quantity": 90,
      "price": 29.99,
      "discountPrice": 19.99,
      "unitPrice": 19.99,
      "systemDetails": {
        "brand": "My Brand",
        "manufacturer": "My Brand",
        "popularity": 40,
        "gender": 0,
        "season": "summer",
        "color": "white",
        "bestseller": true,
        "newProduct": false
      },
      "customDetails": {
        "detail1": "linen",
        "detail2": "short"
      },
      "setAsNull": [
        "datail4",
        "bestseller"
      ]
    }
  ]
}

This method lets you add or update products in a Product Catalog. In SALESmanago products are identified by the field productId. This can be the product ID from your eCommerce platform, the SKU or EAN code. This field is unique per product.

You can upload product variants if they meet both of the following conditions: 1. Product variant has its own productId. 2. Product variant has its own URL.

Endpoint:

https://api.salesmanago.com/v3/product/upsert

Method:

POST

Body (JSON):

Field	Limits	Description
catalogId*	36	Catalog identifier that is used to identify the Product Catalog for the upserted product
products*	100 You can transfer up to 100 products in one request.	Array of product objects with fields specified below
productId*	32	Product identifier from your eCommerce platform
name*	255	Product name. You can use diacritics and special characters.
mainCategory*	255	Category name that can be used in emails and when displaying Recommendation Frames
categoryExternalId	255	Category ID used for AI processing and calculating recommendations. If you don’t specify this field, the category ID will be assigned based on the mainCategory field.
categories	5*255	Other categories (array)
description	16384 Most functionalities can use the first 1024 characters only	Product description used in emails and custom Recommendation Frames. Most functionalities can use the first 1024 characters only.
productUrl*	2048 Most functionalities can use the first 512 characters only	Product URL that is used to match visits with products. Most functionalities can use the first 512 characters only.
mainImageUrl	2048 Most functionalities can use the first 512 characters only	Image URL to be used in Recommendation Frames and emails. Most functionalities can use the first 512 characters only.
imageUrls	5*2048	Additional product images that will be used in upcoming features
available*	bool	Marks products as temporarily unavailable. This allows you to prevent them from showing up in Recommendation Frames.
active	bool	Marks products as no longer present in your store. This will effectively turn off a given product.
quantity	int	Available quantity to be used in custom Recommendation Frames
price*	float (19.2) This value can contain up to 19 digits before the decimal point and 2 digits after the decimal point	Standard product price
discountPrice	float (19.2) This value can contain up to 19 digits before the decimal point and 2 digits after the decimal point	Discount product price. You can use this value to display product promo price next to a crossed out standard product price in emails and Recommendation Frames.
systemDetails	n/a	Set of details that can be used in various mechanisms in SALESmanago
brand	text(255)	Standard product details
manufacturer	varchar(100)	Standard product details
season	varchar(40)	Standard product details
color	varchar(40)	Standard product details
popularity	int(max 100)	Integer value to mark how popular the upserted product is, for example, using a range 1-100.
bestseller	bool	Flags that you can use in emails and custom Recommendation Frames
newProduct	bool	Flags that you can use in emails and custom Recommendation Frames
gender (systemDetails object)	enum (-1, 0, 1, 2, 3, 4)	Enum to identify the gender the product is designed for: -1 – undefined, 0 – female, 1 – male, 2 – other, 4 – unisex
customDetails (object)	5*255	List of additional details as key-value pairs. Note: You can use custom key names (instead of detailX), however, some functionalities will still refer to those values using a key detailX.
setAsNull	Array	Array of product parameters, system details, and/or custom details to be set as null (meaning their values will be cleared). If, for a single request, you specify a value and set this value as null at the same time, the value will be set as null.

Sample response:

{
  "requestId": "381d-...-12e7",
  "productIds": ["1234", "1235"]
}

Updating product price

You can update the price and discount price for products previously added to a Product Catalog.

Sample request:

{
  "catalogId": "21c2-...-3266",
  "products": [
    {
      "productId": "1234",
      "price": 199.99,
      "discountPrice": 149.99
    }
  ]
}

Endpoint:

https://api.salesmanago.com/v3/product/updatePrice

Method:

POST

Body (JSON):

Field	Limits	Description
catalogId	UUID	UUID of a Product Catalog. You can find it in SALESmanago ➔ Integration Center ➔ Product Catalogs. The UUID is also returned when a Product Catalog is created using the product/catalogUpsert method.
productId	255	Product identifier from your eCommerce platform
price	float (19.2) This value can contain up to 19 digits before the decimal point and 2 digits after the decimal point	Standard product price
discountPrice	float (19.2) This value can contain up to 19 digits before the decimal point and 2 digits after the decimal point	Discount product price. You can use this value to display product promo price next to a crossed out standard product price in emails and Recommendation Frames.

Response:

Field	Description
success	Boolean value informing about the result of the request (successful/not successful)
problems	Array of additional information, including error messages

Sample response:

{
  "success": true
}

Updating product stock

You can update the stock (quantity) for products previously added to a Product Catalog.

Sample request:

{
  "catalogId": "21c2-...-3266",
  "products": [
    {
      "productId": "1234",
      "quantity": 300
    }
  ]
}

Endpoint:

https://api.salesmanago.com/v3/product/updateQuantity

Method:

POST

Body (JSON):

Field	Limits	Description
catalogId	UUID	UUID of a Product Catalog. You can find it in SALESmanago ➔ Integration Center ➔ Product Catalogs. The UUID is also returned when a Product Catalog is created using the product/catalogUpsert method.
productId	255	Product identifier from your eCommerce platform
quantity	int	Available quantity to be used in custom Recommendation Frames

Response:

Field	Description
success	Boolean value informing about the result of the request (successful/not successful)
problems	Array of additional information, including error messages

Sample response:

{
  "success": true
}

Product Collections

What are Product Collections?

Product Collections allow you to store information about products associated with individual Contacts. This data can later be used to target Contacts who have a specific product in a Collection or to synchronize Collection contents between different devices via API.

The most representative example is a Wishlist—when a Contact adds a product to their Wishlist, you can add it to the Wishlist Product Collection and later use the selector: Product Collection contains item(s) to select Contacts who took a liking to a specific product.
Another example could be Interested in—a Product Collection for storing items a Contact has expressed interest in, for example, by hovering their cursor over a product or scrolling its description to a certain depth.

Product Collection types

There is no fixed list of Product Collection types. You can create a Product Collection with any name you want. Some examples:

Wishlist: A collection of products that a Contact has expressed interest in purchasing, and added them to a wishlist
Interested in: A collection of products that a Contact has shown interest in, but have not added to their wishlist nor purchased
Purchased: A collection of products that a Contact has actually bought or ordered
Viewed: A collection of products that a Contact has viewed on an e-commerce platform or website
Favorites: A collection of products that a Contact has marked as their favorite for easy access
Recommended: A collection of products that are recommended to a Contact based on their previous interactions, purchase history, or browsing behavior
Reviewed: A collection of products that a Contact has reviewed or given feedback on

Creating a Product Collection

Sample request:

{
  "name": "Wishlist",
  "catalogId": "21c2-...-3266"
}

You can create a new Product Collection with a name of your choice and associate it with a selected Product Catalog.

Endpoint:

https://api.salesmanago.com/v3/product/collection/add

Method:

POST

Body (JSON):

Field	Limits	Description
name	255	Product Collection name, used to identify the Collection in SALESmanago.
catalogId	UUID	UUID of a Product Catalog. You can find it in SALESmanago ➔ Integration Center ➔ Product Catalogs. The UUID is also returned when a Product Catalog is created using the product/catalogUpsert method.

Response:

Field	Description
success	Boolean value informing about the result of the request (successful/not successful)
problems	Array of additional information, including error messages
collectionsUUID	Unique identifier of the Product Collection, required when adding, deleting, or listing products in the Collection

Sample response:

{
  "collectionUUID": "0a1b-...-2c3d",
  "success": true
}

Adding products to a Product Collection

Sample request:

{
  "collectionUUID": "0a1b-...-2c3d",
  "data": [
    {
      "contactId": "1a2b-...-3c4d",
      "productIds": [
        "P0123",
        "P1234",
        "P2345"
        ]
    },
    {
      "contactId": "2a3b-...-4c5d",
      "productIds": [
        "P0123",
        "P3456"
      ]
    }
  ]
}

You can add new products to a Product Collection in response to specific actions of individual Contacts.
You can also use this method when synchronizing external product lists for multiple products and multiple Contacts.

Endpoint:

https://api.salesmanago.com/v3/product/collection/products/add

Method:

POST

Body (JSON):

Field	Limits	Description
collectionUUID	UUID	UUID of a Product Collection. You can find it in SALESmanago ➔ Integration Center ➔ Product Catalogs. The UUID is also returned when a Product Collection is created using the product/collection/add method.
data	1000	Array of Contact➔product(s) assignments.
contactId	UUID	Contact ID as returned when the contact/upsert method is called. You can also use the value of the smclient cookie.
productIds	100*255	Array of product IDs. All specified product IDs must match the IDs in the associated Product Catalog.

Response:

Field	Description
success	Boolean value informing about the result of the request (successful/not successful)
message	Array of additional information, including error messages

Sample response:

{
  "success": true,
  "message": "Products scheduled to be added for 1 out of 2 Contacts"
}

Removing products from a Product Collection

Sample request:

{
  "collectionUUID": "0a1b-...-2c3d",
  "data": [
    {
      "contactId": "1a2b-...-3c4d",
      "productIds": [
        "P0123",
        "P1234",
        "P2345"
      ]
    },
    {
      "contactId": "2a3b-...-4c5d",
      "productIds": [
        "P0123",
        "P3456"
      ]
    }
  ]
}

You can remove products from a Product Collection in response to specific actions of individual Contacts.
You can also use this method when synchronizing external product lists for multiple products and multiple Contacts.

Endpoint:

https://api.salesmanago.com/v3/product/collection/products/delete

Method:

POST

Body (JSON):

Field	Limits	Description
collectionUUID	UUID	UUID of a Product Collection. You can find it in SALESmanago ➔ Integration Center ➔ Product Catalogs. The UUID is also returned when a Product Collection is created using the product/collection/add method.
data	1000	Array of Contact➔product(s) assignments.
contactId	UUID	Contact ID as returned when the contact/upsert method is called. You can also use the value of the smclient cookie.
productIds	100*255	Array of product IDs. All specified product IDs must match the IDs in the associated Product Catalog.

Response:

Field	Description
success	Boolean value informing about the result of the request (successful/not successful)
message	Array of additional information, including error messages

Sample response:

{
  "success": true,
  "message": "Products scheduled for removal for 1 out of 2 Contacts"
}

Listing products in Product Collection

Sample request:

{
  "collectionUUID": "0a1b-...-2c3d",
  "contactId" : "1a2b-...-3c4d"
}

You can retrieve a list of products contained in a Product Collection of a specific Contact.

Endpoint:

https://api.salesmanago.com/v3/product/collection/contact/products

Method:

POST

Body (JSON):

Field	Limits	Description
collectionUUID	UUID	UUID of a Product Collection. You can find it in SALESmanago ➔ Integration Center ➔ Product Catalogs. The UUID is also returned when a Product Collection is created using the product/collection/add method.
contactId	UUID	Contact ID as returned when the contact/upsert method is called. You can also use the value of the smclient cookie.

Response:

Field	Description
success	Boolean value informing about the result of the request (successful/not successful)
message	Array of additional information, including error messages
products	Array of product IDs the Contact has in the specified Product Collection

Sample response:

{
  "success": true,
  "products": [
    "P0123",
    "P1234",
    "P2345"
  ]
}

Deleting a Product Collection

Sample request:

{
  "collectionUUID": "0a1b-...-2c3d"
}

You can delete a Product Collection from the SALESmanago system, along with all Collection data associated with individual Contacts.

IMPORTANT: This action is irreversible and might cause a data loss.

Endpoint:

https://api.salesmanago.com/v3/product/collection/delete

Method:

POST

Body (JSON):

Field	Limits	Description
collectionUUID	UUID	UUID of a Product Collection. You can find it in SALESmanago ➔ Integration Center ➔ Product Catalogs. The UUID is also returned when a Product Collection is created using the product/collection/add method.

Response:

Field	Description
success	Boolean value informing about the result of the request (successful/not successful)
problems	Array of additional information, including error messages

Sample response:

{
  "success": true
}

Customer Preference Center

Upsert a Key Information

Sample request:

{
  "owner": "salesmanago.user@yourcompany.com",
  "email": "name@example.com",
  "keyInformation": {
    "numeric": [
      {
        "name": "Shoe size",
        "value": 13
      }
    ],
    "text": [
      {
        "name": "Preferred color",
        "value": "black"
      },
      {
        "name": "Preferred price",
        "value": "$50 - $99"
      }
    ]
  },
  "setAsNull": [
    "Favorite brand",
    "Number of shoes"
  ]


}

Key Information is a data type used to store zero- and first-party data in SALESmanago. Zero-party data is the most powerful data type in Marketing Automation because it is directly collected from the Contact, rather than being inferred or collected from third parties. Use Key Information upsert to add or update data gathered on your website. Important: Do not use this method to transfer information directly from Contact’s browser. Use backend integration when sending requests with API-KEY.

Endpoint:

https://api.salesmanago.com/v3/keyInformation/upsert

Method:

POST

Body (JSON):

Field	Max. length	Description
email*	RFC882	Contact identifier—either their email address or Contact ID
contactid*	UUID	Contact identifier—either their email address or Contact ID
keyInformation*	n/a	Object wrapping numeric and text arrays
numeric	n/a	Array of Key Information of a numeric type
text	n/a	Array of Key Information of a text type
name	255	Key Information name
value	255/BigDecimal	Key Information value
setAsNull	20x255	Array with Key Information names that should be nulled

Sample response:

{
  "requestId": "a1b2-...-c3d4"
}

Get Key Information

Sample request to retrieve a single value:
https://api.salesmanago.com/v3/keyInformation/get?contactId=1234-…-cdef&name=Shoe+size

Sample response:

{
  "contactId": "1234-...-cdef",
  "keyInformation": [
    {
      "name": "Shoe size",
      "value": 13
    }
  ]
}

You can get zero- and first-party data stored in SALESmanago to personalize the Contact’s online experience. For example, if a Contact has indicated that they are interested in vegan products, you could display vegan-specific content and products on your app and website.

Endpoint:

https://api.salesmanago.com/v3/keyInformation/get

Method:

GET

Sample request to retrieve a single value:
https://api.salesmanago.com/v3/keyInformation/get?contactId=1234-…-cdef

Sample response:

{
  "contactId": "1234-...-cdef",
  "keyInformation": [
    {
      "name": "Shoe size",
      "value": 13
    },
    {
      "name": "Preferred color",
      "value": "black"
    },
    {
      "name": "Preferred price",
      "value": "$50 - $99"
    }
  ]
}

Request params:

Param Name	Limits	Description
email*	RFC882	Contact identifier—either their email address or Contact ID. For the email address, use the URL-encoding function.
contactid*	UUID
name	255	You can specify a Key Information name to retrieve a single value. If no key information name is specified all stored values will be returned. The value must be URL-encoded.