JSON API — Content Recommendations

Content recommendations delivered as raw JSON instead of a rendered widget, so you can render them in your own layout. Ideal for a custom-designed carousel, a single-page app, a native app, an email template, or a “you may also like” block that has to match your own design system exactly. You fetch them with one GET request.

In the panel: New campaign › App / API › JSON API — Content Recs.

The steps

Seven steps: Catalog, Interactions, Recommendation, Data in Response, Code, Automation and Performance. There is no Target step: the picks are for whoever your request names.

1. Catalog

Your content catalog of articles, guides and videos lives in Settings → Recommendation setup → Article Catalog. Each item needs an internal ID, a title and a URL, plus an image if your layout uses one. Categories and tags are worth filling in properly, because they let recommendations follow a topic rather than just overall popularity.

2. Interactions

The engine learns from what people read, like, comment on and complete. Reads on your own website are tracked as usual, from Settings → Recommendation setup → Article Tracking. What happens inside your own layout is different, because Personyze did not draw it:

Clicks: send readers through the click_url that comes back with every article. It opens the article and records the click.
Anything off your website, such as an article read inside your app, has to be reported by you through the REST API.

Skipping this is the usual reason a JSON content recommendation returns the same generic list to everyone: it has no reading history to personalize against.

3. Recommendation

Choose the algorithm. The picker is the same one on-site widgets use, grouped into Personalized & Popular; Co-Reads & Related; Visitor History; Catalog Events; and Custom. A request does not come from a page of your site, so the Page row offers what the reader did instead. Use General for picks with no particular article behind them, and Items they viewed to follow what they read.

Many algorithms have settings of their own, shown on the card:

Period: Recently, Today, In last 2 days, In last 4 days, In last week or In all time.
Taken from: which part of the catalog. For example, any category, the categories they read, or their reported interests.
Sort by: for example, most viewed or recently added to the catalog.

Some that suit a JSON feed are Content Recommended for You, Content Recommended for You — Published Since Last Visit, Visitors Who Read This Also Read, Trending Now and Recently Published. The Output card sets how many articles come back (up to 12), Fallback algorithms for when the main one returns too few, and Fill empty cells. Filters narrow the pool further: skip what the reader already engaged with, restrict to chosen categories, or write custom rules on any field of your feed.

See Recommendation Algorithms: content recommendations for the algorithms in detail.

4. Data in Response

Personyze answers with a JSON array of objects, one per article, carrying the fields you select. You are defining your own response contract here, so choose exactly what your renderer needs.

For each row, pick the Field on Personyze from your catalog and give it the Name in JSON result you want in the output. Every article also comes back with a click_url, whether or not you list it. It opens the article’s URL and records the click. A typical content selection:

[
  {
    "internal_id": "nw-a001",
    "title": "How to layer for winter hiking",
    "category": "Skills",
    "image_1": "https://example.test/img/layering.jpg",
    "url": "https://example.test/journal/how-to-layer-for-winter-hiking",
    "click_url": "https://pic.personyze.com/href/k=…"
  },
  ...
]

5. Code

The Code step, titled Request URL, gives you ready-made URLs once the campaign is saved. Make a GET request to one and the recommendations come back as JSON:

URL ends in	Recommends for
`/email={INSERT EMAIL HERE}`	The reader with that email address. An address Personyze has not seen creates a profile.
`/internal_id={INSERT INTERNAL ID HERE}`	The reader with your own ID for them, held on their profile as Internal ID.
`/u={INSERT PERSONYZE USER ID HERE}`	Personyze’s numeric user ID, as the tracker exposes it on your site.
`/item_internal_id={INSERT ITEM INTERNAL ID HERE}`	No reader: articles related to that article. These are articles read together with it, or the most popular in its section.

A fifth URL, ending in /get[]=…, returns your chosen fields for the articles you name (up to 50) and recommends nothing. The request is the same from a backend, an app or an email template. For an app that already uses the mobile SDK, a Content Recs for Apps campaign delivers the picks there.

6. Automation

This step is optional. Add rules that alert you, or act, when this campaign’s numbers cross a line. See Automation.

7. Performance

The Performance step shows JSON API statistics. Viewed counts the recommendations served to your application. Engaged counts readers who went through a returned click_url and landed on your site, as a % of Viewed. Converted counts those who went on to reach your content goal in the same session. It can only count what reaches Personyze: clicks that skip the click_url are missing, so the figures understate what the recommendation did. What each figure means: Content recommendations.

Note: there is no QA step

JSON API campaigns have no QA step, because there is no rendered content to preview. Validate by requesting a URL and checking the answer yourself: the right number of items, the fields you selected present, and values populated rather than empty. A request that cannot be answered returns {"error": "…"}, for example No recommendations for this user.

Recommendations Outside Your Site — Where to Start
JSON API — Product Recommendations
Content Recommendations Wizard: the rendered-widget version.
Articles object in the REST API.