Overview
personalizer.io uses a RESTful architecture and enables coding in the language of your choice. All connections require authentication and are secured by TLS encryption.
personalizer.io uses a RESTful architecture and enables coding in the language of your choice. All connections require authentication and are secured by TLS encryption.
Before diving deeper, there are a few concepts we would like to familiarize you with.
How it works? To add personalization to your applications, there are two sides to the API implementation: Back-end and Front-end. We designed the APIs in a way that they are instantly applicable to your front-end use-cases, meaning that you don't necessarily need to implement the back-end integration to be able to use this service. Simply log user activities, and this alone will let you recieve behavior-based recommendations (i.e. Top Picks, Recent Views, Trending, Popular, Related).
However, the behavior-based recommendations are only accurate when you process huge amounts of user behavior data, which is not available in many cases. If you are just launching a new website or app that doesn't have many users and/or traffic this effect may be particularly pronounced. You don't need to worry, though, if you don't have a big user-behavior base.
Feeding the engine with details about your items (e.g. Products, Articles, etc.) and users profiles (i.e. Demographics, Interests) trains it to understand them better, and makes it smarter. This is where the magic of personalizer.io comes into play! It can deliver highly effective and targeted personalization to you, simply by learnig details about your items and users.
What is Identifier? In various methods when you are submitting or retrieving data (e.g. Items, Collections, Users) from endpoints, you will encounter a field called Identifier. This is basically the unique identifier in your system for that particular record. For example when you are submitting an ItemView activity to AcvitityLogs, the referenceIdentifier is the unique identifier of that item within your system. Then when you retrieve recommendations (e.g. Trending) from the Trending endpoint, it will return to you a list of Identifiers that should match with your own system's IDs.
Here's a two-sided (both back-end and front-end) sample work flow that utilizes the various capabilities of the engine:
curl -X POST \
-H "content-type: application/json" \
-d '{"ApiKey": "${API_KEY}", "UserIdentifier": "Jon"}' \
https://personalizer.io/v1/userAuthentication
HTTP/1.1 200 OK
{
"ContextID":"The Context ID token"
}
curl -X POST \
-H "content-type: application/json" \
-H "X-Personalizer-Context-ID: ${USER_CONTEXT_ID}" \
-d '{
"Source": "StandardNavigation",
"Event": "CollectionTimeSpend",
"ReferenceIdentifier": "31030215",
"IntData": 30607,
"UserAgent": "Mozilla/5.0 (Windows NT 6.1; WOW64; rv:37.0) Gecko/20100101 Firefox/37.0",
"ScreenResolution": "1280 x 1024"
}' \
https://personalizer.io/v1/activityLogs
HTTP/1.1 204 No Content
curl -X GET \
-H "X-Personalizer-Context-ID: ${USER_CONTEXT_ID}" \
https://personalizer.io/v1/topPicks
[
{"Identifier":"392925679"},{"Identifier":"392927127"},
{"Identifier":"392926395"},{"Identifier":"392925907"},
{"Identifier":"392926395"},{"Identifier":"392925907"},
{"Identifier":"392927027"},{"Identifier":"392926355"},
]
curl -X POST \
-H "X-Personalizer-Context-ID: ${USER_CONTEXT_ID}" \
-H "content-type: application/json" \
-d '{
"Age": 20,
"Gender": "Male",
"RelationshipStatus": "Single",
"HomeTown": "Winterfell",
"Location": "Castle Black",
"FreeText": "Jon Snow is a major character in the first, second, third, fourth and fifth seasons. / Lord Snow,Stark,Night\u0027s Watch",
"InterestCategories": ["Fight", "Sports"],
"InterestKeywords": ["Night\u0027s Watch", "Castle Black", "Sword"],
"FullName": "Jon Snow",
"FacebookUsername": "JonSnow",
"TwitterHandle": "@JonSnow",
"EmailAddress": "jonsnow@castleblack.com",
"CellPhone": "2005667669"
}' \
https://personalizer.io/v1/users
HTTP/1.1 204 No Content
curl -X POST \
-H "content-type: application/json" \
-d '{
"ApiKey": "${API_KEY}",
"AdministratorEmail":"admin@example.com",
"AdministratorPassword":"Examp!eSecurePassw0rd"
}' \
https://personalizer.io/v1/administratorAuthentication
HTTP/1.1 200 OK
{ "ContextID":"The administrative Context ID" }
curl -X POST \
-H "content-type: application/json" \
-H "X-Personalizer-Context-ID: ${ADMINISTRATIVE_CONTEXT_ID}" \
-d '[
{
"Identifier": "sample string 1",
"Title": "T-Shirt",
"Description": "Sample T-Shirt",
"Prevalence": 0,
"PopularityIndex": 2,
"Tags": "Tee,Shirt,T-Shirt",
"Active": true,
"Deleted": false
},
{
"Identifier": "sample string 2",
"Title": "Shoe",
"Description": "Sample Shoe",
"Prevalence": 0,
"PopularityIndex": 1,
"Tags": "Tee,Shirt,T-Shirt",
"Active": true,
"Deleted": false
}
]' \
https://personalizer.io/v1/items
HTTP/1.1 200 OK
[
"{"Identifier":"sample string 1"}",
"{"Identifier":"sample string 2"}"
]
curl -X POST \
-H "content-type: application/json" \
-H "X-Personalizer-Context-ID: ${ADMINISTRATIVE_CONTEXT_ID}" \
-d '[
{
"Identifier": "sample string 1",
"Title": "T-Shirt",
"Description": "Sample T-Shirt",
"Prevalence": 0,
"PopularityIndex": 2,
"Tags": "Tee,Shirt,T-Shirt",
"Active": true,
"Deleted": false,
"Collections": ["Apparel", "Tees"]
},
{
"Identifier": "sample string 2",
"Title": "Shoe",
"Description": "Sample Shoe",
"Prevalence": 0,
"PopularityIndex": 1,
"Tags": "Footwear,Shoe",
"Active": true,
"Deleted": false,
"Collections": ["Apparel", "Shoes"]
}
]' \
https://personalizer.io/v1/items
HTTP/1.1 200 OK
[
"{"Identifier":"sample string 1"}",
"{"Identifier":"sample string 2"}"
]
curl -X POST \
-H "content-type: application/json" \
-H "X-Personalizer-Context-ID: ${ADMINISTRATIVE_CONTEXT_ID}" \
-d '[
{
"Identifier": "Sample string 1",
"Title": "Apparels",
"Active": true,
"Published": true,
"Prevalence": 0
},
{
"Identifier": "Sample string 2",
"Title": "Toys",
"Active": true,
"Published": true,
"Prevalence": 0
}
]' \
https://personalizer.io/v1/collections
HTTP/1.1 200 OK
[
"{"Identifier":"sample string 1"}",
"{"Identifier":"sample string 2"}"
]
Authentication is fairly simple. Upon signing up with the engine, you will receive a unique API Key that is required for exchange with an Context ID. After getting a Context ID, API calls can be easily made by setting the X-Personalizer-Context-ID HTTP header on all requests. There are two types of Context ID: Administrative and User.
In order to get the Context ID you should send a POST request to the appropriate authentication endpoint. To get deal with back-end APIs, you'll need to get an administrative Context ID, and to work with front-end endpoints a user Context ID should be requested.
For more info about authentication endpoints and request/response formats please refer to these links:
Now that you have the Context ID, you can easily make API calls. In order to make an API call, you have to send the X-Personalizer-Context-ID custom header with the actual Context ID with each request. In the case of a missing or invalid X-Personalizer-Context-ID, you will get 401-Unauthorized response.
Header | Valid Values | Description |
---|---|---|
Accept | application/json text/json |
Response body's format. Currently we only support JSON. |
Content-Type | application/json text/json |
Reqest body's format. Currently we only support JSON. Required for POST/PUT requests. |
X-Personalizer-Context-ID | Context ID | A valid administrative or user Context ID. Requied for all requests except authentication. |
Header | Possible Values | Description |
---|---|---|
Date | An RFC 2822 date | The Response Date |
Content-Type | application/json text/json |
Your response format. Currently we only support JSON. |
WWW-Authenticate | In case of 401 Unauthorized response, it points to the authentication documentation page. |
Here are the most common http success codes and their meanings:
Http Status Code | Meaning | Description |
---|---|---|
200 | OK | In case of successful POST/GET request with non-empty response. |
204 | No Content | In case of successful POST/GET request with empty response. |
You might get errors when making API calls. Here are the most common http error codes and their meanings:
Http Status Code | Meaning | Description | How to Resolve |
---|---|---|---|
400 | Bad Request | Your request parameters or body is malformed or invalid. | Correct your request and send it again. |
401 | Unauthorized |
|
|
403 | Forbidden | You don't have access to requested resource. | Access the resource with an Context ID with has adequate permissions to access the resource. |
404 | Not Found | Underlying resource not found or does not exist. | Correct the request url or required search values. |
422 | Unprocessable Entity | The request was well-formed but was unable to be followed due to semantic errors. | Correct the entity specified in the error details and try again. |
500 | Internal Server Error | An abnormal error occurred. | Contact support. |
By integrating into personalizer.io APIs you'll get real-time personalized item with every new activity that is logged into your website, without the need for initializing and integrating your entities (users, items and collections data) into the LimeSpot engine. However, if you would like to have enriched and more powerful personalization and recommendations where you can make recommendations based on your entities' profiles, you should provide the personalizer.io engine with more information.
To feed more data into personalizer.io engine, you should:
See below for documentation of specific components of the personalizer.io API.
API | Description |
---|---|
POST v1/ImpersonateAuthentication |
Get an impersonation Context ID. |
POST marketing/v1/ImpersonateAuthentication |
Get an impersonation Context ID. |
API | Description |
---|---|
POST v1/Products?attribution={attribution}&itemID={itemID} |
No documentation available. |
POST v1/Products?subscriberID={subscriberID} |
No documentation available. |
PUT v1/Products |
Sets targeting info (detail params) of a batch of products, each product has its individual detail params. |
POST marketing/v1/Products?attribution={attribution}&itemID={itemID} |
No documentation available. |
POST marketing/v1/Products?subscriberID={subscriberID} |
No documentation available. |
PUT marketing/v1/Products |
Sets targeting info (detail params) of a batch of products, each product has its individual detail params. |
API | Description |
---|---|
POST v1/ContainerItems?published={published}&containerGuid={containerGuid} |
Pubilsh or Unpublish Items within a Container. |
POST marketing/v1/ContainerItems?published={published}&containerGuid={containerGuid} |
Pubilsh or Unpublish Items within a Container. |
API | Description |
---|---|
POST v1/Onboarding?step={step} |
No documentation available. |
GET v1/Onboarding?step={step} |
No documentation available. |
POST marketing/v1/Onboarding?step={step} |
No documentation available. |
GET marketing/v1/Onboarding?step={step} |
No documentation available. |
API | Description |
---|---|
GET v1/Campaigns?activeCriteria={activeCriteria} |
No documentation available. |
GET marketing/v1/Campaigns?activeCriteria={activeCriteria} |
No documentation available. |
API | Description |
---|---|
POST v1/AdministratorAuthentication |
Get administrative Context ID. |
POST v1/AdministratorAuthentication?subscriberID={subscriberID} |
No documentation available. |
POST marketing/v1/AdministratorAuthentication |
Get administrative Context ID. |
POST marketing/v1/AdministratorAuthentication?subscriberID={subscriberID} |
No documentation available. |
API | Description |
---|---|
POST v1/UserAuthentication |
Get user Context ID. |
PUT v1/UserAuthentication |
Keep-alive current Context ID |
POST marketing/v1/UserAuthentication |
Get user Context ID. |
PUT marketing/v1/UserAuthentication |
Keep-alive current Context ID |
API | Description |
---|---|
POST v1/ActivityLogs |
Log user's activity. |
POST v1/ActivityLogs?subscriberID={subscriberID} |
No documentation available. |
POST marketing/v1/ActivityLogs |
Log user's activity. |
POST marketing/v1/ActivityLogs?subscriberID={subscriberID} |
No documentation available. |
API | Description |
---|---|
GET v1/Items/{id}?includeTargetingInfo={includeTargetingInfo} |
Loads an item by its id. |
POST v1/Items |
Batch store (insert/update) items. |
DELETE v1/Items |
Batch delete items. |
POST v1/Items?getDetails={getDetails}&fields={fields} |
No documentation available. |
GET v1/Items?sizes={sizes} |
No documentation available. |
GET v1/Items?colors={colors} |
No documentation available. |
GET marketing/v1/Items/{id}?includeTargetingInfo={includeTargetingInfo} |
Loads an item by its id. |
POST marketing/v1/Items |
Batch store (insert/update) items. |
DELETE marketing/v1/Items |
Batch delete items. |
POST marketing/v1/Items?getDetails={getDetails}&fields={fields} |
No documentation available. |
GET marketing/v1/Items?sizes={sizes} |
No documentation available. |
GET marketing/v1/Items?colors={colors} |
No documentation available. |
API | Description |
---|---|
GET v1/Users |
Loads the user profile information. |
POST v1/Users |
Sets/updates the user profile information. The fields with NULL values will be ignored in case of update. |
POST v1/Users?cartIdentifier={cartIdentifier} |
No documentation available. |
PUT v1/Users?encConnectingUserID={encConnectingUserID} |
No documentation available. |
PUT v1/Users?connectingUserID={connectingUserID} |
No documentation available. |
PUT v1/Users?userID1={userID1}&userID2={userID2} |
No documentation available. |
PUT v1/Users?connect={connect} |
No documentation available. |
GET marketing/v1/Users |
Loads the user profile information. |
POST marketing/v1/Users |
Sets/updates the user profile information. The fields with NULL values will be ignored in case of update. |
POST marketing/v1/Users?cartIdentifier={cartIdentifier} |
No documentation available. |
PUT marketing/v1/Users?encConnectingUserID={encConnectingUserID} |
No documentation available. |
PUT marketing/v1/Users?connectingUserID={connectingUserID} |
No documentation available. |
PUT marketing/v1/Users?userID1={userID1}&userID2={userID2} |
No documentation available. |
PUT marketing/v1/Users?connect={connect} |
No documentation available. |
API | Description |
---|---|
POST v1/Collections |
Batch store (insert/update) collections. |
POST v1/Collections/{id}?subscriberID={subscriberID}&versionCheck={versionCheck} |
No documentation available. |
POST marketing/v1/Collections |
Batch store (insert/update) collections. |
POST marketing/v1/Collections/{id}?subscriberID={subscriberID}&versionCheck={versionCheck} |
No documentation available. |
API | Description |
---|---|
GET v1/RecentViews?excludedItemIdentifiers={excludedItemIdentifiers}&limit={limit}&fields={fields} |
Returns the Recently Viewed Items |
GET marketing/v1/RecentViews?excludedItemIdentifiers={excludedItemIdentifiers}&limit={limit}&fields={fields} |
Returns the Recently Viewed Items |
API | Description |
---|---|
GET v1/Upsell?identifiers={identifiers}&limit={limit}&fields={fields} |
Returns the Upsell Items for a particular item. |
GET marketing/v1/Upsell?identifiers={identifiers}&limit={limit}&fields={fields} |
Returns the Upsell Items for a particular item. |
API | Description |
---|---|
GET v1/CrossSell?identifiers={identifiers}&limit={limit}&fields={fields} |
Returns the Cross-sell Items for a particular item. |
GET marketing/v1/CrossSell?identifiers={identifiers}&limit={limit}&fields={fields} |
Returns the Cross-sell Items for a particular item. |
API | Description |
---|---|
GET v1/Related?identifiers={identifiers}&limit={limit}&fields={fields} |
Returns the Related Items for a particular item. |
GET marketing/v1/Related?identifiers={identifiers}&limit={limit}&fields={fields} |
Returns the Related Items for a particular item. |
API | Description |
---|---|
GET v1/BoughtTogether?identifiers={identifiers}&limit={limit}&fields={fields} |
Returns the Frequently Bought Together Items |
GET marketing/v1/BoughtTogether?identifiers={identifiers}&limit={limit}&fields={fields} |
Returns the Frequently Bought Together Items |