Prerequisites
- An active Sequen account. If you don’t have one, request an audit, or speak with your account representative to get started.
- Your Sequen API Key (found in your Sequen dashboard, or provided by our development team). You’ll use this in the
Authorizationheader for your API requests (e.g.,Authorization: Bearer YOUR_SEQUEN_API_KEY). - A tool for making HTTP requests, like
curlor Postman. The examples below usecurl.
Integration Steps
1
Step 1: Upload Your Item Catalog
2
To provide recommendations, Sequen needs to know about the items in your catalog. You can upload or update items in your catalog using the
/catalog/item endpoint.3
Here’s an example of how to create or update an item:
4
curl -X PUT 'https://api.sequen.com/v1/catalog/item' \
-H 'Authorization: Bearer YOUR_SEQUEN_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"item_id": "ST678VG",
"title": "Itelios workshop desk - Premium",
"status": "active",
"description": "Solid wood workshop desk with reinforced frame for heavy tools.",
"price": "1099.99",
"price_currency": "USD",
"metadata": [
{ "key": "material", "value": "solid oak", "type": "text" },
{ "key": "dimensions", "value": "120x80x75cm", "type": "text" },
{ "key": "weight", "value": "50", "type": "number" },
{ "key": "load_capacity", "value": "150", "type": "number" }
]
}'
5
Refer to the Update Item API Reference for more details on the request and response structure. It’s recommended to upload your entire catalog initially and then send updates as items change.
6
Step 2: Send User Engagement Events
7
Sequen learns from user interactions (engagement events) to personalize recommendations and improve model performance. Send events using the
/cds/engagement endpoint.8
Events should include relevant context like user identifiers, session identifiers, and details about the item or page being interacted with. The endpoint accepts both single events and batches of events for bulk uploads.
9
Here’s an example of sending a single
add_to_cart event:10
curl -X POST 'https://api.sequen.com/v1/cds/engagement' \
-H 'Authorization: Bearer YOUR_SEQUEN_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"type": "add_to_cart",
"userId": "user_f9b3d",
"sessionId": "session_k2p0a",
"timestamp": "2024-07-27T10:30:00Z",
"properties": {
"item_id": "SKU-12345-BLK-L",
"page_type": "product_detail",
"quantity": 1,
"price": 59.99,
"currency": "USD",
"category_path": "Apparel > Tops > T-Shirts",
"color": "Black",
"size": "L"
}
}'
11
Common event types include
view, click, purchase, add_to_cart, and search. Refer to the CDS Engagement Events API Reference for detailed information on sending single or multiple events.12
Step 3: Query Recommendations
13
Once you have uploaded items and are sending engagement data, you can retrieve personalized recommendations using the
/recommend endpoint.14
You can request recommendations based on a
user_id, session_id, item_id (for similar items), a list of item_ids, or recent events.15
Here’s an example request for recommendations for a user, based on items they’ve interacted with and some recent events:
16
curl -X POST 'https://api.sequen.com/v1/recommend' \
-H 'Authorization: Bearer YOUR_SEQUEN_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"user_id": "2f396d29fb98",
"item_ids": ["ST678VG", "QW1234"],
"events": [
{
"timestamp": "2024-06-14T10:00:00Z",
"type": "browse",
"item_id": "ST678VG",
"description": "Viewed workshop desk details page"
}
],
"limit": 10,
"model_name": "furniture_v2"
}'
17
The response will contain a list of recommended item IDs, optionally with scores. See the Recommendations API Reference for all available parameters.
18
Step 4: Explore Further
19
You’ve now seen the basics of interacting with the Sequen API!
20