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 Idenfitier. 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:
  1. 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 Access Token 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
{
    "AccessToken":"The user access token"
}
     
  2. Now that you have the access token, 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-Access-Token: ${USER_ACCESS_TOKEN}" \
-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
  3. 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-Access-Token: ${USER_ACCESS_TOKEN}" \
https://personalizer.io/v1/topPicks
     
     Response:
     [
     

     {"Identifier":"392925679"},{"Identifier":"392927127"},
{"Identifier":"392926395"},{"Identifier":"392925907"},
{"Identifier":"392926395"},{"Identifier":"392925907"},
{"Identifier":"392927027"},{"Identifier":"392926355"},
     

     ]
     
  4. 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-Access-Token: ${USER_ACCESS_TOKEN}" \
-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:
  1. 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 Access Token. 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 access token"}
     
  2. With the administrative access token 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-Access-Token: ${ADMINISTRATIVE_ACCESS_TOKEN}" \
-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"}"

     ]
  3. 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-Access-Token: ${ADMINISTRATIVE_ACCESS_TOKEN}" \
-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"}"

     ]
  4. 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-Access-Token: ${ADMINISTRATIVE_ACCESS_TOKEN}" \
-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 access token. After getting an access token, API calls can be easily made by setting the X-Personalizer-Access-Token HTTP header on all requests. There are two types of access token: Administrative and User.

In order to get the access token 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 access token, and to work with front-end endpoints a user access token should be requested.
For more info about authentication endpoints and request/response formats please refer to these links:

• Get administrative access token
• Get user access token

Making API Calls

Now that you have the access token, you can easily make API calls. In order to make an API call, you have to send the X-Personalizer-Access-Token custom header with the actual access token with each request. In the case of a missing or invalid X-Personalizer-Access-Token, you will get 401-Unauthorized response.

Request Header

Response Header

Success Status Codes

Here are the most common http success codes and their meanings:

Error Status Codes

You might get errors when making API calls. Here are the most common http error codes and their meanings:

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:

• Post item's data to the Items endpoint
• Post collection's data to the Collections endpoint
• Post user's data to the Users endpoint