And now your Prepr journey begins!
This is reference documentation for the Prepr REST API.
The API provides programmatic access to all of the key parts of Prepr. To get started with the API, you'll need to created an lifetime access token first.
Making a request to our API is as simple as issuing an HTTP GET request. You can make these requests using the mechanism of your choosing. For debugging and developing our team uses Postman.
GET /publications?access_token={{access_token}} HTTP/1.0
More about the basis in our guide Basics explained and some advanced functions Overview and Best Practices .
A great way to learn our API is to issue requests and inspect the responses. You can easily use our Postman collections to do just that.
If a Postman collection is available you find a Run in Postman button in the Get Started section of the reference category.
All API endpoints will return a HTTP status code that matches the state of your request. The status codes are explained in the Response Codes guide.
/publications
created_on,
-created_on,
changed_on,
-changed_on,
publish_on,
-publish_on
{
"sort" : "created_on"
}
Sorting on publish_on
Because the publish_on param of a Publication is localized, if no locale param is present the API will sort on the default Environment locale.
Here you will find everything you need to learn how the query Prepr.
The eq operator checks that the field matches the described value exactly. It takes a single value for filtering.
{
"{field}" : [
{
"eq" : "To do",
"param" : "{param}" // Optional
}
]
}The all operator filters all publications matching a specific set of values.
{
"{field}" : [
{
"all" : [
"42314cdb-5705-4f6c-b190-74ca06fb83f1",
"0e45b74b-e6b7-b346-7b64-a8e446232d76"
],
"param" : "{param}" // Optional
}
]
}The in operator filters a field by multiple values. The publication must match at least one of them.
{
"{field}" : [
{
"in" : [
"42314cdb-5705-4f6c-b190-74ca06fb83f1",
"0e45b74b-e6b7-b346-7b64-a8e446232d76"
],
"param" : "{param}" // Optional
}
]
}The has operator filters a field by checking the existence. The publication must have at least one field.
{
"{field}" : [
{
"has" : true
}
]
}The sw operator filters a field by checking the start of a string value.
{
"{field}" : [
{
"sw" : "news/trump-in-the"
}
]
}Filter publications on the Publication Model.
{
"model" : {
"id" : "One"
}
}Supported operators: eq, in.
{
"status" : [
{
"eq" : "To do",
"in" : [
"Done", "To do"
]
}
]
}Querying eq status 'Done' is optimized and will respond faster than a multi-status request if a locale is specified.
Supported operators: eq, in.
{
"locales" : [
{
"eq" : "en-EN",
"in" : [
"en-EN", "en-US"
]
}
]
}Please note that an Publication only gets a locale link when at least one field is filled for that locale.
Supported operators: eq, in.
{
"created_by" : [
{
"eq" : "bcc9eea7-7307-f45b-5aaf-27eca7d329f9",
"in" : [
"222b7528-9e3a-294f-21bf-7ec623d1ac74",
"bcc9eea7-7307-f45b-5aaf-27eca7d329f9"
]
}
]
}Supported operators: eq, in.
{
"assigned_to" : [
{
"eq" : "bcc9eea7-7307-f45b-5aaf-27eca7d329f9",
"in" : [
"222b7528-9e3a-294f-21bf-7ec623d1ac74",
"bcc9eea7-7307-f45b-5aaf-27eca7d329f9"
]
}
]
}Supported operators: eq, in.
Supported params: Id (default), Slug, Body.
{
"channels" : [
{
"eq" : "bcc9eea7-7307-f45b-5aaf-27eca7d329f9",
"in" : [
"222b7528-9e3a-294f-21bf-7ec623d1ac74",
"bcc9eea7-7307-f45b-5aaf-27eca7d329f9"
],
"param" : "Id"
}
]
}The tags filters on all the tags associated with the publication.
Supported operators: eq, all, in, has.
Supported params: id (default), slug, body.
{
"tags" : [
{
"eq" : "bcc9eea7-7307-f45b-5aaf-27eca7d329f9",
"all" : [
"222b7528-9e3a-294f-21bf-7ec623d1ac74",
"bcc9eea7-7307-f45b-5aaf-27eca7d329f9"
],
"in" : [
"222b7528-9e3a-294f-21bf-7ec623d1ac74",
"bcc9eea7-7307-f45b-5aaf-27eca7d329f9"
],
"has" : true,
"param" : "Id"
}
]
}Supported operators: eq, in.
{
"conainers" : [
{
"eq" : "bcc9eea7-7307-f45b-5aaf-27eca7d329f9",
"in" : [
"222b7528-9e3a-294f-21bf-7ec623d1ac74",
"bcc9eea7-7307-f45b-5aaf-27eca7d329f9"
]
}
]
}Supported operators: eq, sw.
Requires locale, requires model for a unique result.
{
"slug" : [
{
"eq" : "nieuws/388107-beelden-paaseiland-wandelden-over-het-eiland.html"
},
{
"sw" : "nieuws/388107-be"
}
]
}Filter publications by searching in all text fields with fuzzy search.
Supported operators: fz.
{
"q" : [
{
"fz" : "Our character is what we do when we think no one is looking"
}
]
}Filter publications by searching in the title field with fuzzy search.
Supported operators: fz.
{
"title" : [
{
"fz" : "Our character is what we do when we think no one is looking"
}
]
}The date filter can be used with the operators eq, lt, gt and accepts UTC timestamps.
{
"created_on" : [
{
"eq" : 1546304461, // Optimized
"lt" : 1546304461, // Optimized (if used with gt)
"gt" : 1546304461,
}
],
"changed_on" : [
{
"eq" : 1546304461, // Optimized
"lt" : 1546304461, // Optimized (if used with gt)
"gt" : 1546304461,
}
],
"publish_on" : [
{
"eq" : 1546304461, // Optimized
"lt" : 1546304461, // Optimized (if used with gt)
"gt" : 1546304461,
}
],
"expire_on" : [
{
"eq" : 1546304461, // Comming Soon
"lt" : 1546304461, // Comming Soon
"gt" : 1546304461, // Comming Soon
}
]
}
When querying publish_on without a locale specified the results will be accurate in a one hour window.
Querying created_on/publish_on eq or gt with lt is optimized and will respond much faster than other range requests.
Publications can be filtered on the content of a data field. When filtering on a field setting the model is required.
The date filter can be used with the operators lt, lte, gt, gte and accepts UTC timestamps.
{
"model" : {
"id" : "50a315ea-2f-4c0c-837a2c8b2c1e89c"
},
"items" : {
"de-DE" : {
"date" : [
{
"gte" : 1577239200,
"lte" : 1677239200
}
]
}
}
}In this example the DateTimeRange field is called date.
Coming soon!
You can use a proximity search on publications with a location field to find results in a specified geographical area.
Queries that include exact coordinates can't take advantage of caching. In many use cases it should be enough to round the coordinates to 3 decimal places (an accuracy of about 300m), 2 decimal places (an accuracy of about 1km) or more to improve your cache hit rates.
All fields that are available on /publications can be found in the /publications/{id} reference.
Scopes: publications.
/publications
{
"model" : {
"id" : "8ca916d8-ba5c-4c6b-a91a-4c4fb2213879"
},
"publish_on" : {
"en-EN" : "1546956658", // UTC TIMESTAMP
"nl-NL" : "1546351870"
},
"expire_on" : {
"en-EN" : "1546956658",
"nl-NL" : "1546351870"
},
"status" : {
"en-EN" : {
"body" : "To do"
},
"nl-NL" : {
"body" : "Done"
}
},
"channels" : [
{
"id" : "ddc429a1-2bf1-cf99-5bbe-76ad8f3b6334"
}
],
"containers" : [
{
"id" : "5776f710-5d3d-3c8e-c9c6-e4a56579218c"
}
],
"assigned_to" : {
"en-EN" : {
"id" : "52475775"
},
"nl-NL" : {
"id" : "392185ba-d803-41ab-8a35-88018123aa5c"
}
},
"locales" : [
"en-EN",
"nl-NL"
],
"items" : {
"en-EN" : {
"title" : {
"body" : "This is the title",
"format" : "H6",
"label" : "Text"
},
"summary" : {
"body" : "En dit is de summary text.",
"label" : "Text"
},
"boolean" : {
"value" : true
},
"integer" : {
"value" : 3742343
},
"float" : {
"value" : 94.23423
},
"bnnvara" : {
"id" : "384727"
},
"quote" : {
"author" : "Albert Einstein",
"body" : "If we knew what it was we were doing, it would not be called research, would it?"
},
"number" : {
"title" : "Viering van de liefde in Amsterdam",
"number" : 349,
"body" : "mensen",
"description" : "nemen op 'Viering van de Liefde' afstand van Nashville-verklaring"
},
"location" : {
"latitude" : 21.3137,
"longitude" : -157.806
},
"tags" : {
"items" : [
{
"name" : "airplane"
}
]
},
"hours" : [
{
"open_day" : 6,
"open_time" : "12:00",
"close_day" : 6,
"close_time" : "17:00"
}
],
"publication" : {
"id" : "1852380d-50b1-486e-b8c3-c5b8f45f9ac1"
},
"publications" : {
"items" : [
{
"id" : "1852380d-50b1-486e-b8c3-c5b8f45f9ac1"
},
{
"id" : "220e1e38-3e01-40f9-800e-19ec9ebb43d1"
}
]
}
},
"nl-NL" : {
"title" : {
"body" : "Dit is de titel",
"format" : "H6",
"label" : "Text"
},
"summary" : {
"body" : "If we knew what it was we were doing, it would not be called research, would it?",
"label" : "Text"
}
}
}
}Scopes: publications, publications_publish.
Events: publication.created.
/publications/{id}
Fields: items, title, published, model, locales, status, environment, created_by, updated_by, assigned_to, insights, channels, containers, internal_comments.
Scopes: publications.
/publications/{id}
This endpoint is identical to POST, with the exception that label is not required.
Scopes: publications, publications_publish.
Events: publication.changed.
/publications/{id}
Scopes: publications, publications_delete.
Events: publication.deleted.
Items explained
The Publication items array contains the content of the Publication. For every locale there is a array containing the fields specified by the Publication Model.
"items" : {
"en-EN" : {
"{{api_id}}" : {
"body" : "This is the title",
"format" : "H6"
// For a specification of the fields check the type model below.
}
}
}Text
Here below you will find a table with all possible text format options.
H1
heading input field
body without html and format specified
H2
heading input field
body without html and format specified
H3
heading input field
body without html and format specified
H4
heading input field
body without html and format specified
H5
heading input field
body without html and format specified
H6
heading input field
body without html and format specified
CODE
raw html input field
body contains html and format specified (this will be used for the UI editor)
null
basic wysiwyg editor input field. (bold, italic, list, list with numbers, link/url)
body contains html and no format specified
"{{api_id}}" : {
"body" : "This is the title",
"label" : "Text", // Required inside the Drag-and-drop editor
"format" : "H6" // Optional
}"{{api_id}}": {
"id": "4b950836-f274-4ef2-a91b-efd064b55ae4",
"created_on": "2019-01-09T20:29:28+00:00",
"changed_on": null,
"label": "Text",
"body": "This is the title",
"format": "H6"
},Color
"{{api_id}}" : {
"body" : "#003366",
"label" : "Color", // Required inside the Drag-and-drop editor
}"{{api_id}}": {
"id": "411c7ddb-58d4-487b-9bd4-9bb43eec279d",
"created_on": "2019-01-09T20:39:50+00:00",
"changed_on": null,
"label": "Color",
"body": "#003366",
"format": "Color"
}DateTime
"{{api_id}}" : {
"body" : "2020-01-01",
"label" : "DateTime", // Required inside the Drag-and-drop editor
"format" : "Y-m-d" // Required inside the Drag-and-drop editor
}DateTimeRange
"{{api_id}}" : {
"from" : "2020-01-01 13:05:09",
"until" : "2020-09-01 13:05:09",
"label" : "DateTimeRange",
"format" : "Y-m-d H:m:s"
}Boolean
"{{api_id}}" : {
"value" : true,
"label" : "Boolean" // Required inside the Drag-and-drop editor
}"{{api_id}}": {
"id": "38b6d11b-eaa8-4c3f-bbda-232b4de54501",
"created_on": "2019-01-09T20:45:51+00:00",
"changed_on": null,
"label": "Boolean",
"value": true
}ElementBox
"{{api_id}}": {
"items": [
{
// element 1
},
{
// element 2
}
],
"label" : "ElementBox"
}"{{api_id}}": {
"items": [
{
// element 1
},
{
// element 2
}
],
"label" : "ElementBox"
}Integer
"{{api_id}}" : {
"value" : 5472653,
"label" : "Integer" // Required inside the Drag-and-drop editor
}"{{api_id}}": {
"id": "ca1bded4-edaa-45a1-b7b6-f7fac96a7afd",
"created_on": "2019-01-09T20:45:51+00:00",
"changed_on": null,
"label": "Integer",
"value": 3742343
}Float
"{{api_id}}" : {
"value" : 54.72653,
"label" : "Float" // Required inside the Drag-and-drop editor
}"{{api_id}}": {
"id": "e09b4321-3811-4b6f-9440-26f1290ee402",
"created_on": "2019-01-09T21:04:48+00:00",
"changed_on": null,
"label": "Float",
"value": 94.23423
},Coordinates
"{{api_id}}" : {
"latitude": "21.3137",
"longitude": "-157.806",
"label" : "Coordinates" // Required inside the Drag-and-drop editor
}"{{api_id}}": {
"id": "56c9ddb0-1c91-49db-a322-736c5d343280",
"created_on": "2019-01-07T16:05:08+00:00",
"changed_on": null,
"label": "Coordinates",
"latitude": 21.3137,
"longitude": -157.806
}Quote
"{{api_id}}" : {
"author" : "Albert Einstein",
"body" : "If we knew what it was we were doing, it would not be called research, would it?",
"label" : "Quote" // Required inside the Drag-and-drop editor
}"{{api_id}}": {
"id": "8faf8d54-6b85-44dd-b707-28b058fd939f",
"created_on": "2019-01-09T20:52:49+00:00",
"changed_on": null,
"label": "Quote",
"body": "If we knew what it was we were doing, it would not be called research, would it?",
"author": "Albert Einstein"
},Number
"{{api_id}}" : {
"title" : "Viering van de liefde in Amsterdam",
"number" : 349,
"description" : "nemen op 'Viering van de Liefde' afstand van Nashville-verklaring",
"body" : "mensen",
"label" : "Number"
}"{{api_id}}": {
"id": "13ff1609-1987-427c-924e-ebf31c4079fe",
"created_on": "2019-01-09T20:57:44+00:00",
"changed_on": null,
"label": "Number",
"body": "mensen",
"number": 349,
"description": "nemen op 'Viering van de Liefde' afstand van Nashville-verklaring",
"title": "Viering van de liefde in Amsterdam"
},Resource/Link
"{{api_id}}" : {
"url" : "https://nos.nl/artikel/2266773-honderden-nemen-op-viering-van-de-liefde-afstand-van-nashville-verklaring.html",
"type" : "Webpage", // Webpage, Audio, Video, Document, Other
"label" : "Resource"
}CardItem
"{{api_id}}" : {
"body" : "The world's tallest unoccupied building",
"sub_title" : "Ryugyong Hotel: The story of North Korea's 'Hotel of Doom'",
"description" : "In 1987, ground was broken on a grand new hotel in North Korea's capital, Pyongyang.",
"url" : "https://edition.cnn.com/style/article/ryugyong-hotel-architecture-origins/index.html",
"url_label" : "Read More..."
}TwitterPost
"{{api_id}}" : {
"url" : "https://twitter.com/realDonaldTrump/status/1083022011574747137",
"label" : "TwitterPost" // Required inside the Drag-and-drop editor
}InstagramPost
"{{api_id}}" : {
"url" : "https://www.instagram.com/p/BrSs_aglLEb",
"label" : "InstagramPost" // Required inside the Drag-and-drop editor
}YouTubePost
"{{api_id}}" : {
"url" : "https://www.youtube.com/watch?v=4xgx4k83zzc",
"label" : "YouTubePost" // Required inside the Drag-and-drop editor
}FacebookPost
"{{api_id}}" : {
"url" : "https://www.facebook.com/openbac/photos/a.560688977339484/2364254840316213",
"label" : "FacebookPost" // Required inside the Drag-and-drop editor
}VimeoPost
"{{api_id}}" : {
"url" : "https://vimeo.com/190247248",
"label" : "VimeoPost" // Required inside the Drag-and-drop editor
}SoundCloudPost
"{{api_id}}" : {
"url" : "https://soundcloud.com/summersaltband/driving-to-hawaii",
"label" : "SoundCloudPost" // Required inside the Drag-and-drop editor
}SpotifyPlaylist
"{{api_id}}" : {
"url" : "https://open.spotify.com/user/11158963147/playlist/6AfkmB7MBUuYJ7oFAvp81G?si=txHmkuucRPuFemHtVx17BQ",
"label" : "SpotifyPlaylist" // Required inside the Drag-and-drop editor
}QualifioPost
"{{api_id}}" : {
"id" : "87654321",
"label" : "QualifioPost" // Required inside the Drag-and-drop editor
}"{{api_id}}": {
"id": "a734jad-32478623-sdafw4f4jgfj4",
"created_on": "2019-01-09T20:29:28+00:00",
"changed_on": null,
"label": "QualifioPost"
},BusinessHours
"{{api_id}}" : [
{
"open_day" : 2,
"open_time" : "08:00",
"close_day" : 2,
"close_time" : "19:00"
}
]
}Publications (reference)
Publication references can be created as a one to many relationship.
"{{api_id}}" : {
"items" : [
{
"id" : "1852380d-50b1-486e-b8c3-c5b8f45f9ac1"
},
{
"id" : "220e1e38-3e01-40f9-800e-19ec9ebb43d1"
}
]
}"{{api_id}}": {
"label": "Publication",
"items": {
"0": {
"id": "1852380d-50b1-486e-b8c3-c5b8f45f9ac1",
"created_on": "2019-01-07T19:59:26+00:00",
"changed_on": null,
"label": "Publication"
},
"1": {
"id": "220e1e38-3e01-40f9-800e-19ec9ebb43d1",
"created_on": "2019-01-07T20:41:03+00:00",
"changed_on": null,
"label": "Publication"
}
}
}Assets (reference)
Asset references can be created as a one to many relationship For uploading assets check out the /assets endpoint (Assets).
Images API
We recommend that you also read about our images api. For further explanation about Cloud Front, nested fields, resizing, source file and cdn file.
"{{api_id}}" : {
"items" : [
{
"id" : "1852380d-50b1-486e-b8c3-c5b8f45f9ac1"
},
{
"id" : "220e1e38-3e01-40f9-800e-19ec9ebb43d1"
}
]
}"{{api_id}}": {
"label": "Asset",
"items": {
"0": {
"id": "1852380d-50b1-486e-b8c3-c5b8f45f9ac1",
"created_on": "2019-01-07T19:59:26+00:00",
"changed_on": null,
"label": "Asset"
},
"1": {
"id": "220e1e38-3e01-40f9-800e-19ec9ebb43d1",
"created_on": "2019-01-07T20:41:03+00:00",
"changed_on": null,
"label": "Asset"
}
}
}Persons (reference)
Person (audience) references can be created as a one to many relationship.
"{{api_id}}" : {
"items" : [
{
"id" : "1852380d-50b1-486e-b8c3-c5b8f45f9ac1"
},
{
"id" : "220e1e38-3e01-40f9-800e-19ec9ebb43d1"
}
]
}"{{api_id}}": {
"label": "Person",
"items": {
"0": {
"id": "1852380d-50b1-486e-b8c3-c5b8f45f9ac1",
"created_on": "2019-01-07T19:59:26+00:00",
"changed_on": null,
"label": "Person"
},
"1": {
"id": "220e1e38-3e01-40f9-800e-19ec9ebb43d1",
"created_on": "2019-01-07T20:41:03+00:00",
"changed_on": null,
"label": "Person"
}
}
}Getting Started
Recommendations draws on that experience to deliver (personalized) recommendations that suit each users tastes and preferences across all your touchpoints.
When you start using recommendations, you work with our staff to determine the best recommendation recipe and customizations to use for your site. The models and customizations you use depend on your business KPI's, and where you plan to display the resulting recommendations.
You can use the recommendations in a variety of scenarios, such as giving users recommendations based on their behavior, likes, bookmarks and subscribes.
Prepr offers the following recommendation recipes:
The Personalized-Sims-Metadata recipe generates personalized ranking. A personalized ranking is a list of recommended publications that are re-ranked for a specific user. This recipe has the following properties:
Interaction label set the interaction label where the recommendation is based on available options: bookmark, subscribed.
Similar Tag Factor set the weight factor for the recommendations based on similar tags.
Popularity Factor Affects the balance between popularity and meta-data similarity. A value of 1 makes the most popular publication appear as recommendations regardless of their correlation. A value of 0 makes most publications that have co-interactions (shared meta-data) with the specific publication appear as recommendations regardless of their popularity. For most cases, a value around 0.3 works best.
Requires: person.id.
The (SIMS) Item-to-item similarities recipe is based on the concept of collaborative filtering. A SIMS model leverages user-item interaction data to recommend publications similar to a given publication. In the absence of sufficient user interaction data for an publication, this recipe recommends popular publications that share the similar tags. This recipe has the following properties:
Similar Tag Factor set the weight factor for the recommendations based on similar tags.
Popularity Factor Affects the balance between popularity and meta-data similarity. A value of 1 makes the most popular publication appear as recommendations regardless of their correlation. A value of 0 makes most publications that have co-interactions (shared meta-data) with the user interacted publications appear as recommendations regardless of their popularity. For most cases, a value around 0.3 works best.
Requires: publication.id.
The (SIMS-metadata) Item-to-item similarities recipe is based on the concept of content based filtering. A SIMS-metadata model leverages the publications metadata to recommend publications similar to a given publication. Automatic tagging (topics) can be used as an extra factor next to similar tags. This recipe has the following properties:
Similar Tag Factor set the weight factor for the recommendations based on similar tags.
Topic Factor set the weight factor for the recommendations based on similar topics (auto tagging).
Similar tags or topics can also be used separately.
Requires: publication.id.
Popularity-count returns the top popular publications. A popular publication is defined by the number of times has been viewed. Popularity-count is a good starting point to compare against other recipes. This recipe has the following properties:
Random factor an optional weight that can be set in the absence of sufficient user interaction data.
Popularity-count-location returns the top popular publications nearby. A popular publication is defined by the number of times has been viewed. Publications that are popular by visitors viewing the scoped publication are boosted. This recipe has the following properties:
25 percentile factor set a boost factor for publications closer the the 25 percentile distance to the scoped publication.
70 percentile factor set a boost factor for publications closer the the 70 percentile distance to the scoped publication.
distance sets the max. radius of the distance to the scoped publication.
Requires: publication.id.
Randomized trials returns randomly selected publications. The Randomized trials recipe is often used as a starting point to compare against other recipes.
Check out the /recommendations/{id}/predict endpoint to see how to get the recommendations.
/recommendations/{id}/predict
All fields and most filters supported on the Publications endpoint are available.
Scopes: recommendations.
About Models
Prepr organizes content into environments, that allows you to group all the related data for a project together, this includes publications, assets, and settings for localizing content into different languages.
Each environment has their own models that represents the data structure for a publication.
/channels
With Prepr you can publish to all your digital channels. Publish to your website, app, live blog, social wall, social media and on location screens. All those different front ends are defined as an Channel. This description is all about the web channels.
created_on,
-created_on,
changed_on,
-changed_on,
name,
-name
{
"sort" : "created_on"
}
Here you will find everything you need to learn how the query Prepr.
Filter channels by name with equal or fuzzy search.
Supported operators: eq, fz.
{
"name" : [
{
"eq" : "International",
"fz" : "interna"
}
]
}Filter channels by slug, since a slug is unique this filter will always return one result.
Supported operators: eq.
{
"slug" : [
{
"eq" : "international"
}
]
}Scopes: channels.
/channels
{
"name": "Floortje naar het einde van de wereld",
"slug": "floortje-naar-het-einde-van-de-wereld"
}Scopes: channels, channels_publish.
Events: channel.created.
/channels/{id}
This endpoint is identical to POST, with the exception that name is not required.
Scopes: channels, channels_publish.
Events: channel.changed.
Uploading Audios
To upload audios send a request to post /assets endpoint and set label to Audio and add source (multipart/form-data).
{
"label": "Audio",
"source": // File Upload.
}You can include the fields param in this request (How to use fields).
The endpoint will return a http status 201 OK with the asset response.
{
"id": "16012a23-3130-43e2-96df-4438ed4097fc",
"created_on": "2019-10-02T13:00:00+00:00",
"changed_on": "2019-10-02T13:00:00+00:00",
"label": "Audio",
"name": "Hello World",
"body": null,
"author": null,
"reference_id": null
}Scopes: assets, assets_publish.
Events: asset.created.
Uploading Photos
To upload photos send a request to post /assets endpoint and set label to Photo and add source (multipart/form-data).
{
"label": "Photo",
"source": // File Upload.
}You can include the fields param in this request (How to use fields).
The endpoint will return a http status 201 OK with the asset response.
{
"id": "16012a23-3130-43e2-96df-4438ed4097fc",
"created_on": "2019-10-02T13:00:00+00:00",
"changed_on": "2019-10-02T13:00:00+00:00",
"label": "Photo",
"name": "IMG_1234",
"body": null,
"author": null,
"reference_id": null
}Scopes: assets, assets_publish.
Events: asset.created.
Uploading Videos
Upload videos as chunks, handle errors, and resume the upload of any remaining chunks. There are three different upload phases:
Start a resumable upload by initializing a new asset object. To make a start request and create a video upload session, send a request to post /assets (Assets) endpoint, set the upload_phase field to start, and specify file_size, in bytes.
{
"label": "Video",
"upload_phase": "start",
"file_size": "8308859"
}Once you have chunks ready to upload with the right start_offset and end_offset you can make a transfer request to upload the chunk, and get the offset for the next chunk.
Split the video with the UNIX command split -b{X}m {filename}. This command splits your file into multiple parts of X MB each.
To upload the first video chunk, send a request to the post /assets/{id}/multipart endpoint and set the upload_phase field to transfer and add video_file_chunk (multipart/form-data).
The default chunk size is 52428800 bytes.
{
"upload_phase": "transfer",
"original_name": "1c5b89d9-b6cc-4962-90c8-766769a478aa_1080.mp4",
"video_file_chunk": // File Upload Chunk.
}Repeat this step for every chunk. As a final step, you need to post this video and close the upload session.
Once you upload all chunks, make a finish request to complete the upload, post the video, and queue it for asynchronous video-encoding.
Make a request to post /assets/{id}/multipart endpoint with the param upload_phase set to finish.
You can include the fields param in this request (How to use fields).
{
"upload_phase": "finish"
}The endpoint will return a http status 200 OK with the asset response.
{
"id": "69cbd289-0f0c-4a15-80a-c60d376db5f8",
"created_on": "2019-09-09T13:54:03+00:00",
"changed_on": "2019-09-09T13:54:03+00:00",
"label": "Video",
"name": "1c5b89d9-b6cc-4962-90c8-766769a478aa_1080",
"body": null,
"author": null
}Scopes: assets, assets_publish.
Events: asset.created.
/assets
Assets uploaded earlier will not upload again. Instead the earlier version will be returned. New added metadata like name, body, author will not be overwritten.
Fields: cdn_files, storage_file, tags.
Scopes: assets_publish.
Getting Started
Explore the Audience API in Postman.
Postman Environment variables: url, access_token, person_id, domain, password, personal_access_token.
/persons
Here you will find everything you need to learn how the query Prepr.
Supported operators: eq, neq, in.
{
"gender" : [
{
"eq" : "male",
"neq" : "female",
"in" : ["male", "female"]
}
]
}Supported operators: eq, lt, gt.
{
"age" : [
{
"eq" : "18",
"lt" : "19",
"lte" : "18",
"gt" : "21",
"gte" : "20"
}
]
}Supported operators: eq, in, has.
{
"interactions" : [
{
"eq" : "120c2b8a-73f4-b43c-1b3c-b7513288f740",
"in" : [
"120c2b8a-73f4-b43c-1b3c-b7513288f740",
"16d388e4-c8b9-e870-d446-d3f0fd4b3cdf"
],
"has" : true, // false
"type" : "Purchased"
}
]
}The date filter can be used with the operators eq, lt, gt, li and accepts UTC timestamps.
{
"created_on" : [
{
"eq" : "2019-01-08T14:10:58+00:00",
"lt" : "2019-01-08T14:10:58+00:00",
"lte" : "2019-01-08T14:10:58+00:00",
"gt" : "2019-01-08T14:10:58+00:00",
"gte" : "2019-01-08T14:10:58+00:00",
"il" : "2019-01-08T14:10:58+00:00"
}
],
"last_seen" : [
{
"eq" : "2019-01-08T14:10:58+00:00",
"lt" : "2019-01-08T14:10:58+00:00",
"lte" : "2019-01-08T14:10:58+00:00",
"gt" : "2019-01-08T14:10:58+00:00",
"gte" : "2019-01-08T14:10:58+00:00",
"il" : "2019-01-08T14:10:58+00:00"
}
]
}Filter to fetch all persons created in the last week, older than or 18 and purchased product X.
{
"created_on" : [
{
"il" : 604800
}
],
"age" : [
{
"gte" : 18
}
],
"interactions" : [
{
"eq" : "4237f1d9-ad15-2a8a-1951-d8625c8d67c0",
"type" : "Purchased"
}
],
}Scopes: persons.
/persons
While Prepr offers a full suite of solutions designed to help clients comply with applicable data privacy laws, it is the clients' responsibility to comply with its obligations under such data privacy laws. Please consult with your legal team regarding such data privacy laws prior to implementation of Prepr.
Scopes: persons, persons_publish.
Events: person.created.
/persons/{id}
Fields: gender, date_of_birth, age, profile_photo, emails, phones, bank_accounts, addresses, tags, countries, cities, zip_codes, password, segments, terms, facebook_accounts, google_accounts, stripe_customers, stripe_plans.
Scopes: persons.
/persons/{id}/oauth/access_token
This endpoint will return an Personal Access Token like if a person signs in.
Scopes: persons..
/persons/{id}/anonymize
Scopes: persons, persons_delete.
Not revertible
If this endpoint is triggered no confirmation will be asked. And this endpoint will remove all personal data that's covered by GDPR and the id will be replaced with a newly generated ID.
/persons/{id}
Scopes: persons, persons_delete.
Events: person.deleted.
Not revertible
If this endpoint is triggered no confirmation will be asked. And this endpoint will fully remove all personal data that's covered by GDPR (including interactions).
Returns all Email items attached to the Person.
{
"id": "586a4ce-404e-4d6c-aca4-8782c8d7b5",
"created_on": "2019-12-21T16:12:39+00:00",
"changed_on": null,
"label": "Email",
"email": "[email protected]"
}Field: emails.
Phone
Returns all Phone items attached to the Person.
{
"id": "6ee11ad9-cb52-4a6a-8f8a-a2cd83",
"created_on": "2019-12-21T16:12:39+00:00",
"changed_on": null,
"label": "Phone",
"phone": "+398373737305"
}Field: phones.
StripeCustomer
Returns all StripeCustomer items attached to the Person.
{
"id": "cus_GOv5Q3Vp3Gkm",
"created_on": "2019-12-21T12:46:16+00:00",
"changed_on": "2019-12-21T12:46:16+00:00",
"label": "StripeCustomer"
}Connecting your Stripe Account is required for using this field.
Field: stripe_customers.
StripePlan
Returns all StripePlan items the StripeCustomer is subscribed to. The quantity is a sum of all subscriptions for the attached plan.
{
"quantity": 1,
"plan": {
"id": "plan_GJkJ8EVQ",
"created_on": "2019-12-21T13:02:48+00:00",
"changed_on": "2019-12-21T13:02:48+00:00",
"label": "StripePlan",
"body": "Monthly"
}
}Connecting your Stripe Account is required for using this field.
Field: stripe_plans.
Getting Started
Explore the Audience Sign-in API in Postman.
Postman Environment variables: url, access_token, domain, password, magic_link_email_template_id, personal_access_token, emailed_access_token.
/persons/sign_in
Email + password sign-in
The Personal Access Token will receive the user-scopes added to the App requesting the log-in. Contact Prepr Support before use.
Scopes: persons_sign_in.
/persons/request_sign_in
Magic Link sign-in (step 1)
This endpoint can also be used to implement a password recovery flow.
Scopes: persons_sign_in.
/persons/sign_in_with_magic
Magic Link sign-in (step 2)
The Personal Access Token will receive the user-scopes added to the App requesting the log-in. Contact Prepr Support before use.
Requires a Personal Sign-in Access Token received from the Request Magic Sign-in endpoint or Prepr Social Sign-in.
Scopes: persons_sign_in.
/persons/me
This endpoint is available as GET, PUT and DELETE. There references to the /person/{id} endpoints for the logged-in Person when using a Personal Access Token.
Requires a Personal Access Token.
Scopes: persons_me.
Quickstart Facebook
This is a Quickstart guide setting up a Facebook App to work with Prepr Social Sign-in.
Go to Facebook for Developers and create a developer account if you haven't already done so.
Login to the Facebook Developers Dashboard .
Create a Facebook app.
By default your new app will come with the default and email scope.
If your app requires more scopes, request a Login Review with Facebook. For more information on Facebook scopes, see Login Permissions.
On the Dashboard page, expand Settings on the left and then click Basic.
Save the
App IDandApp Secretvalues you need those when setting up the Facebook App in Prepr.
Go to Settings -> Integrations in the Prepr Console.
Click Activate on the Facebook App tile.
Enter the
App IDandApp Secretyou obtained from the Facebook Developers Dashboard and give the Facebook App a name.If your app requires additional scopes, check the scopes that Prepr should request on sign-in.
On the Facebook App Dashboard page, click the + next to Products and click Set Up on the Facebook Login title.
Select Web on the Quickstart page.
Add the
login domainyou obtained from the Prepr Console in the Site Url box and click Save, then Continue.Click Settings below Facebook Login on the left side of the page.
Add the
redirect urlyou obtained from the Prepr Console to the list of Valid OAuth Redirect URIs and click Save.
Create a link that the person clicks to sign-in. The HREF for that link is the authorize URL that you obtained from the Prepr Console after creating the integration.
<a href="https://example.prepr.io/sign_in/facebook/37648gjhgsd23648763
2?redirect_url=https%3A%2F%2Fexample.com%2F&state=sjhdkash3272jh&nonce=shJHh321s1dad">Continue with Facebook</a>After the user clicks the link, they are prompted to sign in with Facebook. After a successful sign in, the user is returned to the specified redirect_url.
The AccessToken added to the url can be exchanged for a Personal Access Token using the /persons/sign_in_with_magic endpoint.
Scopes: persons_sign_in.
Getting Started
Explore the Audience Interactions API in Postman.
Postman Environment variables: url, access_token , personal_access_token, publication_id.
Prepr's Recommendation Engine uses real- time user interactions to generate recommendations. Recording as many types of user interactions as possible increases the recommendation quality. For Likes, Views and Subscribes we have created some dedicated endpoints (see below).
There are several user interaction types that you can record as users browse your site.
View
Views publication detail page
Like
Likes publication
Subscribe
Subscribes to publication
Bookmark
Bookmarks publications
Share
Shares publication on site or socials
Purchase
Completes checkout for publication
Opened
Opens email (newsletters) publication
Commented
Commented on a publication
Search
Searches publication(s)
GET request to /interactions/labels will also return this list.
When you record a user interaction, be sure to include an accurate timestamp of when the interaction occurred as the created_on param. Accurate timestamps ensure that model stores interactions in the correct order.
Tracking with a Pixel
To start collecting basic interaction data from a website you can use the Prepr Open Pixel to record a event stream.
Sign in to your Prepr account:
- Go to login.prepr.io
- Sign in with your Prepr account credentials and navigate to the Environment you want to record events for.
Create an Access token
- Go to Settings -> Access tokens and click
Add access token. - Enter
Tracking Pixel {{URL}}and replace {{url}} by the domain (e.g., example.com, not www.example.com/) you are going to use the tracking pixel on. - Click
save - Copy the generated access token, you need this later.
- Go to Settings -> Access tokens and click
Add the code snippet to your website
This is the Prepr Open Pixel (openpixel.js) tracking code. Copy and paste this code as the first item into the <HEAD> of every web page that you want to track. Replace {{ACCESS_TOKEN}} with the access token created in Step 2.
<!-- Start Prepr Open Pixel -->
<script>
!function (e, t, n, p, o, a, i, s, c) {
e[o] || ((i = e[o] = function () {
i.process ? i.process.apply(i, arguments) : i.queue.push(arguments)
}).queue = [], i.t = 1 * new Date, (s = t.createElement(n)).async = 1, s.src = "https://cdn.tracking.prepr.io/js/openpixel.min.js?t=" + 864e5 * Math.ceil(new Date / 864e5), (c = t.getElementsByTagName(n)[0]).parentNode.insertBefore(s, c))
}(window, document, "script", 0, "opix"),
opix("init", "{{ACCESS_TOKEN}}");
</script>
<!-- End Prepr Open Pixel -->After you implemented the Prepr Open Pixel to your website we can start recording events on the page. Events are person interactions with content that can be measured independently from a web page or a screen load.
Event hits can be sent using the event command and specifying a Interaction Label for event. The event command has the following signature:
opix('event', '{{INTERACTION_LABEL}}', {"publication":"{{PUBLICATION_ID}}"});A list of available interaction labels can be found /interactions/labels here.
The following table summarizes the event fields that can be added to the request.
publication (required)
Unique id for a Prepr Publication
person
Person id references a user in Prepr
If a person is not supplied a unique id will be generated.
/publications/{id}/interactions
*The default value is subject to change.
Asynchronous response
The interaction is created asynchronous. The endpoint will return a status code 202 Accepted.
If a person.reference_id is posted a new Person will be created if the reference_id doesn't exists.
This is typically used when an external Identity Management System like Gigya is used.
{
"label" : "View",
"value" : 0.02,
"person" : {
"id" : "f9ac8172-b53b-4f39-b0e8-c29dd624a78c",
"reference_id" : "9bbd76f9-6fcb-865a-5e2d-67539b7b8a04", // Optional
}
}Scopes: interactions_publish.
Events: person.created (if a person is created).
Likes, Subscribes & Views
Prepr's Recommendation Engine uses real- time user interactions to generate recommendations. Recording as many types of user interactions as possible increases the recommendation quality. For Likes, Subscribes and Views we have created some dedicated endpoints.
You can find examples of how to subscribe or like a publication below. For other interaction types, see Users Interactions above.
/persons/{id}/subscriptions
This endpoint lists all publications the person is subscribed to (or has liked).
This endpoint is also available for likes. Use likes instead of subscriptions.
All fields supported on the Publications endpoint are available.
Scopes: persons.
/publications/{id}/subscribe
This endpoint is also available for likes and views. Use view or like instead of subscribe.
Events: person.subscribed, person.liked.
Scopes: publications, persons_me.
/publications/{id}/subscribe
This endpoint is also available for likes. Use like instead of subscribe.
Events: person.unsubscribed, person.unliked.
Scopes: publications, persons_me.
/health
Returns 200 OK when all services are up.
Returns 503 Service Unavailable when down or has degraded performance.
/publications/bulk/webhooks
Uses the same filters as GET /publications (list/index)
You can use the same filters as GET /publications (list/index) here above. All publications that matches your criteria, get a webhook trigger with your defined event.
Delay
Remember that the trigger webhooks are in the queue. And that the number of webhooks can increase rapidly, due to the number of webhooks that have been set up and the number of publications that meet your criteria.
Example calculation:
- 3 webhooks that are listening to the event
publication.published - 1,000 publications that meet with the criteria.
Will result in (3 webhooks x 1,000 publications) = 3,000 webhooks triggered.
Be patient ❤️
Scopes: publications.
/publications/bulk/put
No rollback!
Note that this bulk endpoint doesn't any backup, so make sure what you are doing.
Uses the same filters as GET /publications (list/index)
You can use the same filters as GET /publications (list/index) here above. All publications that matches your criteria, will be updated.
Uses the same params and validators as PUT /publications
Bulk endpoint uses the same endpoint as PUT /publications. the params and validators of that endpoint may apply.
Scopes: publications, publications_publish, publications_bulk.
/publications/bulk/delete
No rollback!
Note that this bulk endpoint doesn't any backup, so make sure what you are doing.
Uses the same filters as GET /publications (list/index)
You can use the same filters as GET /publications (list/index) here above. All publications that matches your criteria, will be updated.
Scopes: publications, publications_delete, publications_bulk.