# Smart Sorting & Reranking
> Current Froomle documentation · [View canonical page](https://docs.froomle.com/froomle-doc-main/v2/guide/topics/smart-sorting-reranking.html)
Instead of relying solely on Froomle’s algorithms to generate recommendations from scratch, you can supply your own candidate items and let Froomle rank them using its personalization engine. This is useful when you already have a set of items (e.g. a curated editorial list or search results) and want to present them in the most relevant order for each user.
> **IMPORTANT:**
>
> For full field specifications and examples, see the [Recommendations API Reference](https://docs.froomle.com/froomle-doc-main/v2/api_reference/recommendations/index.html).
## How it works
Smart sorting uses the `list_content` field within one recommendation request list. The exact behavior depends on whether the items in `list_content` have a fixed `rank`.
| Shape | `list_content` | What Froomle can return | Use when |
| --- | --- | --- | --- |
| Smart sorting request | Candidate items without `rank`. | The supplied candidates, sorted by predicted relevance. Froomle does not fill missing positions with unrelated items. | You already have the candidate set, for example search results or an editorial list, and only want Froomle to reorder it. |
| Request with fixed-rank items | Pinned items where every supplied item has `rank`. | The pinned items at their requested positions, plus normal Froomle recommendations for the remaining positions up to the requested list size. | You need to guarantee specific sponsored/editorial items while letting Froomle fill the rest. |
| Combined request | A mix of pinned items with `rank` and free candidates without `rank` in the same list. | Pinned items stay fixed. Free candidates are reranked into the open positions. Because free candidates are present, do not rely on unrelated items to fill gaps. | You need both constraints: a few guaranteed positions and a customer-owned candidate set for the remaining positions. |
> **IMPORTANT:**
>
> "Combined request" here means combined inside one recommendation list: ranked and unranked `list_content` entries together. It is not the same as sending multiple independent lists in one API request. You may batch multiple lists under `lists`, but each list keeps its own behavior.
## Request format
Each item in the `list_content` array accepts the following fields:
- `id` (required, string): the client item ID.
- `item_type` (required, string): the item type, if not the default.
Smart sorting request
```json
{
"page_type": "home",
"channel": "www",
"device_id": "device-123",
"user_id": "user-123",
"lists": [
{
"list_name": "reranked",
"list_size": 10,
"list_content": [
{"id": "item-1", "item_type": "article"},
{"id": "item-2", "item_type": "article"},
{"id": "item-3", "item_type": "article"},
{"id": "item-4", "item_type": "article"}
]
}
]
}
```
The response follows the standard recommendation response format. Items are returned in order of predicted relevance. If fewer supplied candidates are eligible than the requested `list_size` or `limit`, the response can be shorter; plain smart sorting does not backfill with unrelated recommendations.
## Fixed-rank placement
You can also pin specific items to fixed positions by providing a `rank` field (1-indexed). When all supplied `list_content` items are fixed-rank items, the remaining positions are filled with other recommendations from the engine rather than from your candidate list.
- `rank` (optional, integer): the position at which the item must appear.
Request with fixed-rank items
```json
{
"page_type": "home",
"channel": "www",
"device_id": "device-123",
"lists": [
{
"list_name": "curated_feed",
"list_size": 6,
"list_content": [
{"id": "promo-article", "item_type": "article", "rank": 1},
{"id": "sponsored-item", "item_type": "article", "rank": 4}
]
}
]
}
```
In this example, `promo-article` is locked at position 1 and `sponsored-item` at position 4. Positions 2, 3, 5, and 6 are filled by the recommendation engine.
> **TIP:**
>
> Use fixed-rank placement to guarantee visibility for sponsored or editorial content while still personalizing the rest of the list.
## Combining both modes
You can mix free and fixed-rank items in the same list. Items with a `rank` are pinned; items without a `rank` are reranked by the engine among the remaining positions. This is still one list, not two separate recommendation placements.
Combined request
```json
{
"page_type": "article_detail",
"channel": "www",
"device_id": "device-123",
"context_item": "article_789",
"context_item_type": "article",
"lists": [
{
"list_name": "related",
"list_size": 8,
"list_content": [
{"id": "item-1", "item_type": "article", "rank": 1},
{"id": "item-2", "item_type": "article"},
{"id": "item-3", "item_type": "article"},
{"id": "item-4", "item_type": "article"}
]
}
]
}
```
In this example, `item-1` is fixed at position 1. `item-2`, `item-3`, and `item-4` are the free candidate pool for the remaining positions. If those free candidates are not enough to fill `list_size: 8`, do not treat the empty positions as an error unless your integration expected more candidates to be eligible.
## Tracking, Benchmarking, and Exclusions
Treat a displayed smart-sorted list as a recommendation placement. The candidate set is customer-owned, but Froomle influenced the final order, so the shown and clicked items need normal recommendation attribution.
Tracking rules:
- Send `impression` when a smart-sorted item is shown.
- Send `click_on_recommendation` when a smart-sorted item is clicked.
- Include `action_item`, `action_item_type`, `list_name`, `request_id`, and `channel`. Include `user_group` only for an externally assigned customer/control branch.
- Deduplicate impressions per item/list/request so rerenders do not overcount exposure.
- Do not send Froomle recommendation events for fallback or unmatched customer items unless they have valid smart-sort request attribution.
Benchmarking compares ranking ownership, not item ownership:
| Branch | Candidate source | Ranking owner | Attribution |
| --- | --- | --- | --- |
| Froomle/treatment | Customer candidate set | Froomle order | Track displayed matched items with the Froomle smart-sort `request_id` and treatment group. |
| Customer/control | Customer candidate set | Customer/original order | Keep the customer order, but still track matched items with the benchmark `request_id` and control `user_group` when available. |
Exclusions and deduplication are request constraints for smart sorting. They limit which candidates Froomle may rank and attribute. For fixed-rank items, only explicit exclusions should remove the pinned item; automatic page exclusions should avoid excluding the current smart-sort placement itself.
For browser implementations, this means smart sorting has the same operational responsibilities as recommendation rendering: decide which branch owns the order, send exclusions with the recommendation request, and keep enough attribution metadata to track the items that were actually displayed.
## Implement smart sorting
| Method | Implementation guide |
| --- | --- |
| Frontend SDK | [Smart Sorting and Reranking with the SDK](https://docs.froomle.com/froomle-doc-main/v2/js_lib/smart-sorting-reranking.html) |
| Manual / custom integration | Use the request contract on this page together with [Manual Recommendation Integration](https://docs.froomle.com/froomle-doc-main/v2/guide/manual-integration/recommendations.html). |
## Related topics
- [Recommendation request model](https://docs.froomle.com/froomle-doc-main/v2/guide/topics/recommendation-requests.html)
- [Filters and constraints](https://docs.froomle.com/froomle-doc-main/v2/guide/topics/filters-and-constraints.html)
- [Batch/newsletter recommendations](https://docs.froomle.com/froomle-doc-main/v2/guide/topics/batch-requests.html)