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.
Concepts
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.
Sample Flow
Here's a two-sided (both back-end and front-end) sample work flow that utilizes the various capabilities of the engine:
-
Front-end:
-
When the user starts a new session with your application, first you Authenticate with the personalizer.io. Since this is a front-end usecase, you'll need to get a User Context ID for this purpose. This is very easy via the Authentication Process which is described below.
curl -X POST \
-H "content-type: application/json" \
-d '{"ApiKey": "${API_KEY}", "UserIdentifier": "Jon"}' \
https://personalizer.io/v1/userAuthentication
Response:
HTTP/1.1 200 OK
{
"ContextID":"The Context ID token"
}
-
Now that you have the Context ID, whatever the user does in your application (e.g. Viewing an item, spending time on an item, liking an item, etc.) can be logged the activity via the ActivityLogs endpoint.
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
Response:
HTTP/1.1 204 No Content
-
With the user activity logging in place, you should be able to get various types of recommendations from the Items endpoints and show them to the user on different pages.
curl -X GET \
-H "X-Personalizer-Context-ID: ${USER_CONTEXT_ID}" \
https://personalizer.io/v1/topPicks
Response:
[
{"Identifier":"392925679"},{"Identifier":"392927127"},
{"Identifier":"392926395"},{"Identifier":"392925907"},
{"Identifier":"392926395"},{"Identifier":"392925907"},
{"Identifier":"392927027"},{"Identifier":"392926355"},
]
-
If you have more information about the user, whether it is demographic information (e.g. Age, Gender, Location, Home Town, Bio) or information about their interests (e.g. Music or Movies they love, Sports they play), you can familiarize the engine with the user via the Users endpoint to help deliver much more relevant results.
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
Response:
HTTP/1.1 204 No Content
-
Back-end:
-
Before being able to work with the back-end endpoints, you first need to Authenticate again. For this purpose, you'll need to get an Administrative Context ID. Simply follow the Authentication Process document below, and you're all set.
curl -X POST \
-H "content-type: application/json" \
-d '{
"ApiKey": "${API_KEY}",
"AdministratorEmail":"admin@example.com",
"AdministratorPassword":"Examp!eSecurePassw0rd"
}' \
https://personalizer.io/v1/administratorAuthentication
Response:
HTTP/1.1 200 OK
{"AccessToken":"The administrative Context ID"}
-
With the administrative Context ID you can submit your item details to the Items endpoint. It will digest and store them to deliver recommendations that are based both on items' extracted attributes and user behaviors.
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
Response:
HTTP/1.1 200 OK
[
"{"Identifier":"sample string 1"}",
"{"Identifier":"sample string 2"}"
]
-
One optional step further would be to categorize your items within Collections. Collections are virtual containers for items of the same attributes. Each item can be a member of multiple collections and vice versa. Having items categorized within collections will make the engine even smarter so it can deliver better recommendations. To assign collections to your items, you can include a list of collections on each piece of item you are submitting to the system.
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
Response:
HTTP/1.1 200 OK
[
"{"Identifier":"sample string 1"}",
"{"Identifier":"sample string 2"}"
]
-
You can submit more details about collections to the Collections endpoint. This will further enhance the engine so it can deliver better results.
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
Response:
HTTP/1.1 200 OK
[
"{"Identifier":"sample string 1"}",
"{"Identifier":"sample string 2"}"
]
Authentication Process
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:
Making API Calls
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.
Success Status Codes
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. |
Error Status Codes
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 |
- Wrong or missing API key or invalid login info (administrator email/password) when accessing authentication APIs;
- Wrong or missing X-Personalizer-Context-ID header when accessing all other APIs; or
- Expired Context ID provided when accessing all other APIs.
|
- If you are calling authentication APIs, specify a valid API key and login info, otherwise if you are accessing all other APIs;
- Specify a valid X-Personalizer-Context-ID header; or
- Reauthenticate to get a new Context ID, replacing the expired Context ID.
|
| 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. |
Feed data into LimeSpot engine to make it smarter
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:
To post item and collection data you should use
administrative Context ID +
identifier and to post user data you should use
end user Context ID.
