NAV
API v2 API v3 Frontend SDK
json

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:

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",
  "catalogId": "21c2-...-3266", 
  "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
questionmark
only a-zA-Z0-9_ cannot start with a digit
Legacy field for assigning products to External Events.

Sample response:

{
  "requestId": "381d-...-12e7",
  "catalogId": "21c2-...-3266"
}

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

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
questionmark
You can transfer up to 100 products in one request.
Array of product objects with fields specified below
productId* 255 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
questionmark
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
questionmark
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
questionmark
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)
questionmark
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)
questionmark
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
questionmark
(-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.

Sample response:

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

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:

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.
productIds 100*255 Array ofdeleting 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
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.