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 |
---|---|---|
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 errorError message |
10 | 400 |
Field exceeds limitfieldName|min:0|max:256|Error message |
11 | 400 |
Data trimmed warningfieldName|max:256|Warning message |
12 | 200 |
Missing required fieldfieldName|Error message |
13 | 400 |
Wrong field typefieldName:type|Error message |
14 | 400 |
Using non-unique valuefieldName|Error message |
15 | 400 |
Trying to access resource with identifier not present in SALESmanagofieldName|Error message |
16 | 400 |
Trying to set a required value as nullfieldName|Error message |
17 | 400 |
Value not matching a required structure (RegEx)fieldName|Error message |
18 | 400 |
Trying to add a resource above available limitresourceName|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:
|
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:
|
group | Email group as specified in SALESmanago |
author | SALESmanago user who has created the email |
Sample response:
{
"emails": [
{
"emailId": "1234-...-5678",
"sender": {
"emailId": "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": {
"emailId": "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 | |
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+sizeSample 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-…-cdefSample 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. |