We are currently updating our developer documentation. Please refer to this help article for a summary of our API.

Our integration API provides a way to programmatically interact with Fresh Relevance through a REST interface.

This is not to be confused with our JavaScript or Mobile APIs, which provide different functionalities that may be more applicable to your desired use case.

Live data

Below is a list of the methods exposed using the Integration API. To test live data using your account, you need to replace the website_ID and API_token in the request line with your own.

Website ID
To get your website ID from your Fresh Relevance account, expand the User menu and copy the Account ID.
API token
To get your API token from your Fresh Relevance account, expand the User menu and go to Settings > Other Integrations > Fresh Relevance Access Tokens and copy the relevant token Key from the table. Learn more in Create and edit API access tokens.

Summary of API Methods

API	Path	API Parameters	Allowed Methods
People Search Searches and returns people.	/api/[website_id]/people/?format=json&limit=25&page=1&api_token=[API_token]	id	GET, PUT, DELETE
People Search - Email Searches and returns people by email address. To test live data using your account, you need to replace `[email_address]`.	/api/[website_id]/people/search/email/[email_address]/?format=json&api_token=[API_token]	None	GET
People Search - Device ID Searches and returns people by device ID (did). To test live data using your account, you need to replace `[device_id]`.	/api/[website_id]/people/search/did/[device_id]/?format=json&api_token=[API_token]	None	GET
Client Info Returns key information about system configuration like base currency and website name.	/api/[website_id]/client_info/?api_token=[API_token]	id	GET, PUT
Admin Users Returns key information about users allowed to access the admin area.	/api/[website_id]/admin_users/?api_token=[API_token]	None	GET
Triggers Returns a list of trigger programs.	/api/[website_id]/triggers/?api_token=[API_token]	id	GET
Triggers - Trigger Program Returns information about specific trigger programs, also allows the trigger to be edited with a PUT request. To test live data using your account, you need to replace `[trigger_program_id]` with the ID of the trigger program in your account. The ID can be found in your trigger program's URL.	/api/[website_id]/triggers/[trigger_program_id]/?api_token=[API_token]	None	GET, PUT
Triggers - Trigger Program Actions Returns information about a trigger programs actions. To test live data using your account, you need to replace `[trigger_program_id]` with the ID of the trigger program in your account. The ID can be found in your trigger program's URL.	/api/[website_id]/triggers/[trigger_program_id]/actions/?api_token=[API_token]	id	GET
Trigger Rules - List Returns information about which triggers are run for each trigger type. Use POST to create a new trigger rule.	/api/[website_id]/trigger_rules/?api_token=[API_token]	include_live_flag, include_deleted	GET, POST
Trigger Rules - Detail Returns information about which triggers are run for a specific trigger type. Use POST to edit a trigger rule.	/api/[website_id]/trigger_rules/[trigger_type]/?api_token=[API_token]	include_live_flag	GET, POST, DELETE
Slots Returns a list of Slots. To be certain of returning all slots, even those with complex rule types, you should specify `include_empty_slots=True`	/api/[website_id]/slots/?api_token=[API_token]	limit, tags, slot_type, search_string, include_deleted, load_smartblock_list, include_empty_slots, include_live_flag	GET
SmartBlocks Returns a list of SmartBlocks.	/api/[website_id]/smartblocks/?api_token=[API_token]	None	GET
Slot GET, PUT or DELETE details of a Slot.	/api/[website_id]/slots/slug//?api_token=[API_token]	None	GET, PUT, DELETE
SmartBlock GET, PUT or DELETE details of a SmartBlock.	/api/[website_id]/smartblocks/slug//?api_token=[API_token]	None	GET, PUT, DELETE
Channels Returns a list of configured channels.	/api/[website_id]/channels/?api_token=[API_token]	None	GET
Channels GET or PUT details of a channel. To test live data using your account, you need to replace `[channel_key]` with the channel's key in your account. To get this: Expand the User menu and go to Settings > Triggers and Messaging Interactions > Messaging Provider(s). Find the messaging provider and select Settings.	/api/[website_id]/channels/%3Cchannel_key%3E//?api_token=[API_token]	None	GET, PUT
Reports - Campaigns Next Day Attribution	/api/[website_id]/campaigns/?format=json&limit=25&page=1&date_start=&date_end=&api_token=[API_token]	date_start, date_end	GET
Reports - Campaigns Lastclick Attribution	/api/[website_id]/campaigns_details/?format=json&limit=25&page=1&date_start=&date_end=&api_token=[API_token]	date_start, date_end	GET
Reports - Conversions	/api/[website_id]/conversions/?format=json&limit=25&page=1&date_start=&date_end=&api_token=[API_token]	date_start, date_end	GET
Reports - Products	/api/[website_id]/products/?format=json&limit=25&page=1&api_token=[API_token]	id,date_start,date_end	GET
Reports - Categories	/api/[website_id]/categories/?format=json&limit=25&page=1&api_token=[API_token]	id	GET
Reports - Message Sent	/api/[website_id]/messages_sent/?format=json&limit=25&page=1&date_start=&date_end=&api_token=[API_token]	date_start,date_end,id,email,tk,type	GET
Reports - Abandoned	/api/[website_id]/abandoned/?format=json&limit=25&page=1&date_start=&date_end=&api_token=[API_token]	date_start,date_end,id	GET
Reports - Recovered	/api/[website_id]/recovered/?format=json&limit=25&page=1&date_start=&date_end=&api_token=[API_token]	date_start,date_end,id,key,program_type,action_index,sbr	GET
Reports - Purchased	/api/[website_id]/purchased/?format=json&limit=25&page=1&date_start=&date_end=&api_token=[API_token]	date_start,date_end,id	GET
Reports - Carted	/api/[website_id]/carted/?format=json&limit=25&page=1&date_start=&date_end=&api_token=[API_token]	date_start,date_end,id	GET
Reports - Unsubscribe	/api/[website_id]/unsub/?format=json&limit=25&page=1&date_start=&date_end=&api_token=[API_token]	date_start,date_end,id,email	GET
Reports - Summary Top 3 Values	/api/[website_id]/reports_summary/?format=json&limit=25&page=1&date_start=&date_end=&api_token=[API_token]	None	GET
Reports - Outline Top Dozen Values	/api/[website_id]/reports_outline/?format=json&limit=25&page=1&date_start=&date_end=&api_token=[API_token]	None	GET
Product Analytics - Aggregated Over Supplied Time Window	/api/[website_id]/product_analytics_aggregated/?format=json&limit=25&page=1&api_token=[API_token]	date_start,date_end	GET
Product Analytics - Daily Buckets	/api/[website_id]/product_analytics/?format=json&limit=25&page=1&api_token=[API_token]	id,date_start,date_end	GET
Reports - Usage	/api/[website_id]/usage/?format=json&limit=25&page=1&date_start=&date_end=&api_token=[API_token]	date_start, date_end	GET
Reports Overview - SmartBlocks GET overview of SmartBlocks.	/api/[website_id]/reports/item/overview/smartblock/?api_token=[API_token]	limit, paginate, date_end, date_start	GET
Reports Overview - Slots GET overview of Slots.	/api/[website_id]/reports/item/overview/slot/?api_token=[API_token]	limit, paginate, date_end, date_start	GET
Reports Overview - Campaigns GET overview of Campaigns.	/api/[website_id]/reports/item/overview/campaign/?api_token=[API_token]	limit, paginate, date_end, date_start	GET
Reports Overview - Triggers GET overview of Triggers.	/api/[website_id]/reports/item/overview/trigger/?api_token=[API_token]	limit, paginate, date_end, date_start	GET
Reports Overview - Experiences GET overview of Experiences.	/api/[website_id]/reports/item/overview/experience/?api_token=[API_token]	limit, paginate, date_end, date_start	GET
Reports - Action Returns Action analytics.	/api/[website_id]/reports/item/action//?api_token=[API_token]	limit, paginate, date_end, date_start	GET
Reports - SmartBlock Returns SmartBlock analytics	/api/[website_id]/reports/item/smartblock/?api_token=[API_token]	limit, paginate, date_end, date_start	GET
Reports - Slot Returns Slot analytics	/api/[website_id]/reports/item/slot/?api_token=[API_token]	limit, paginate, date_end, date_start	GET
Reports - Campaign Returns Campaign analytics.	/api/[website_id]/reports/item/campaign/?api_token=[API_token]	limit, paginate, date_end, date_start	GET
Reports - Trigger Returns Trigger analytics.	/api/[website_id]/reports/item/trigger/?api_token=[API_token]	limit, paginate, date_end, date_start	GET
Reports - Compare Allows multiple items to be compared, for example , `/smartblock/<smartblock_id>/slot/<slot_id>` shows analytics for both SmartBlocks and Slots.	/api/[website_id]/reports/item/compare/?api_token=[API_token]	limit, paginate, date_end, date_start	GET
Product Meta - Languages GET a List of dictionaries for all languages (lang) used in this account.	/api/[website_id]/product_meta/lang/?api_token=[API_token]	None	GET
Product Meta - Site Brands GET a List of dictionaries for all Site Brands (sbr) used in this account.	/api/[website_id]/product_meta/sbr/?api_token=[API_token]	None	GET
Product Meta - Currencies GET a list of dictionaries of all currencies (curr) used in this account.	/api/[website_id]/product_meta/curr/?api_token=[API_token]	None	GET
(Deprecated) Product Meta - Languages GET a simple List of all languages (lang) used in this account.	/api/[website_id]/product_meta/languages/?api_token=[API_token]	None	GET
(Deprecated) Product Meta - Site Brands GET a simple list of all Site Brands (sbr) used in this account.	/api/[website_id]/product_meta/sitebrands/?api_token=[API_token]	None	GET
(Deprecated) Product Meta - Currencies GET a simple list of all currencies (curr) used in this account.	/api/[website_id]/product_meta/currencies/?api_token=[API_token]	None	GET
Jobs GET Returns a list of jobs, POST creates a new job	/api/[website_id]/jobs/?api_token=[API_token]	limit, page	GET, POST
Job Details Returns information about a specific job	/api/[website_id]/jobs/%3Cjob_id%3E/?api_token=[API_token]	None	GET
Product Import	/api/[website_id]/products/import/?api_token=[API_token]	None	POST

API Parameters

You can use these parameters on the query string to control the data returned by the API:

Querystring parameter name	Example	Description
limit	25	Get this number of records to return in results array (pagination).
page	1	Get data starting with 1-based page number where the total number of records exceeds the limit.
format	json	Get data in this format. Other formats are not currently consistently supported.
date_start	2014-07-12	Get data from this date, inclusive of 2014-07-12T00:00:00.00Z.
date_start	2011-12-20T19:41:17.28Z	Get data from this datetime, inclusive of the time specified.
date_end	2014-07-12	Get data before the end of this date i.e. up to and including 2014-07-12T23:59:59.99Z.
date_end	2014-07-12T19:41:17.28Z	Get data before this datetime, i.e. up to but not including 2014-07-12T19:41:17.28Z.
id__gt	545cb0d7ab3af1307fdbe4f3	Get data with primary key (id) after this value, exclusive.
id__sort	1	Sorts the result by ID. Set this parameter to '1' to sort the results in ascending order and '-1' for descending.
paginate	true	Boolean option allowing a toggle between paginating results or returning the entire result set at once. Un-paginated pages may take additional time to load)
tags	"Banner"	String option allowing to search through tags.
slot_type	w	Options are `w` (website), `e` (email), `te` (triggered emails). Filters by Slot type.
search_string	"product"	String option allowing to search through entire result set.
include_deleted	True	Boolean option allowing the inclusion of deleted Slots or not.
load_smartblock_list	True	Boolean option allowing the addition of SmartBlock lists to the results of the Slots.
load_experiences_list	True	Boolean option to enable the "experiences" field which includes a list of the Experiences each Slot is used in.
include_empty_slots	True	Boolean option allowing the inclusion of Slots which are currently empty.
include_live_flag	True	Boolean option allowing the addition of the `is_live` attribute to the results of the Slots.

Examples

GET examples

Most of the API calls can be used with GET. This example retrieves the most recent 25 recoveries from 2014-07-12 up to the end of 2015-01-07

/api/[website_id]/recovered/?format=json&limit=25&page=1&date_start=2014-07-12&date_end=2015-01-07

This example retrieves all recoveries after the record with id 545cb0d7ab3af1307fdbe4f3. You can use this to retrieve all events since the last time you called the API.

/api/[website_id]/recovered/?format=json&id__gt=545cb0d7ab3af1307fdbe4f3

This example retrieves information about all the products displayed within a month interval:

/api/[website_id]/product_analytics_aggregated/?format=json&limit=250&date_start=2018-03-01&date_end=2018-03-31&page=1

This example searches for an email address (name@example.com) and returns matching person_id's as an array. The person_ids can then be used to retrieve data about the person records.

/api/[website_id]/people/search/email/name%40example.com?format=json

This example is similar to the one above but searches for people using device ID (did).

/api/[website_id]/people/search/did/put_did_here/?format=json

PUT examples

At present, only a few API endpoints support being updated with a PUT request.

Set the catch-all address

This Python example updates the catch-all email address:

        url = '/api/[website_id]/client_info/?format=json&api_token=[API_token]'
        d_test_data = {"esp_catchall_address":"my new address"}
        self.client.put(url, follow=True, data=d_test_data )

Replace [API_token] with a valid API token from the API tokens page. To access this, expand the User menu and go to Settings > Other Integrations > Fresh Relevance Access Tokens.

The only other field currently updatable with this API call is esp_catchall_browse_address

Pause a trigger

Triggers can be updated by doing a PUT request to the API endpoint /api/[website_id]/triggers/[trigger_id]/ with the new values. Trigger fields that can be edited with the API include: 'name', 'paused', 'catchall_address', 'bcc_address' and 'refresh_product_data'.

This example shows how to pause a trigger with python:

        url = 'https://api.freshrelevance.com/api/[website_id]/triggers/[trigger_id]/?format=json&api_token=[API_token]'
        d_data = {"paused": True}
        requests.put(url, json=d_data)

To test [trigger_id] should be replaced with the id of the trigger to update and [API_token] should be replaced with a valid API token.

Update a person with the "people" API using CURL

Set a person to "Do Not Process":

curl -X PUT -d do_not_process=1 https://api.freshrelevance.com/api/[website_id]/people/put_person_id_here/?api_token=[API_token]&format=json

Permitted values for do_not_process= are 0 (to enable mailing) and 1 (to set "do not process" and prevent email sending / personalization).

The following fields may be updated using this API:

email - string
do_not_process - boolean
email_exclusion - boolean
explicitPermission - boolean or null
perm - boolean
eid - string
extend.[your fieldname] - string
content.[your fieldname] - string

Data definitions for data returned by API methods

JSON data returned by API calls

The default data returned by API calls is in JSON format. The outer object has the following attributes:

Attribute	Description
count	Total number of records. Earlier versions of the API used `total`, which is still available but is deprecated.
next	URL of the next page.
prev	URL of the previous page.
results	Array of records, each record is a dictionary.

The following are definitions of the data which is returned by the API methods.

These API methods are subject to change, so you should check the data being returned before relying on this documentation. Note that these are described in pseudo-code; any resemblance to actual programming languages is coincidental.

        public class Abandoned
        {
            // data returned by API call
            public ObjectId _id { get; set; } // Internal record id
            public string pid { get; set; } // person ID. Relates to the primary key of the person record
            public string dt { get; set; } // datetime of the last cart activity
            public Cart cart { get; set; } // document containing the cart abandoned
            public string email { get; set; } // email address of the shopper
            public double value { get; set; } // cart value
            public Q q { get; set; } // document containing the last-click tracking information from the querystring
            public string type { get; set; } // b=cart abandon, ba=browse abandon
        }
            public class Recovered
        {
            // data returned by API call
            public ObjectId _id { get; set; } // Internal record id
            public string pid { get; set; } // person ID. Relates to the primary key of the person record
            public string dt { get; set; } // datetime the record was created
            public Cart cart { get; set; } // document containing the cart recovered
            public double value { get; set; } // value of recovery
            public string email { get; set; } // email address of the shopper
            public BSignal b_signal { get; set; } // contains type:  b=cart abandon, ba=browse abandon
            public Q q { get; set; } // document containing the last-click tracking information from the querystring
            public object o_num { get; set; } // order number if supplied from the website.
            public string key { get; set; } // trigger key
            public string program_type { get; set; } // b=cart abandon, ba=browse abandon
            public int action_index { get; set; }
        }
        public class Purchased
        {
            // data returned by API call
            public ObjectId _id { get; set; } // Internal record id
            public string pid { get; set; } // person ID. Relates to the primary key of the person record
            public string dt { get; set; } // datetime the record was created
            public Cart cart { get; set; } // document containing the cartpurchased
            public double value { get; set; } // cart value
            public string email { get; set; } // email address of the shopper
            public Q q { get; set; } // document containing the last-click tracking information from the querystring
            public string o_num { get; set; } // order number if supplied from the website.
        }
        public class Product
        {
            // product structure - elements of the array in the cart structure
            public ObjectId _id { get; set; }
            public string sbr { get; set; } // site brand
            public string lang { get; set; } // language
            public string curr { get; set; } // currency
            public double uv { get; set; } // unit value in base currency
            public string up { get; set; } // original unit price captured from the website
            public string prid { get; set; } // product id
            public List cat { get; set; } // list of categories
            public Ex ex { get; set; } // client-definable extensible data
            public string n { get; set; } // name of the product
            public int qty { get; set; } // quantity of this line item
        }
        public class Ex
        {
            // Extension data, inside the product structure
            public string product_id { get; set; }
        }
        public class BSignal
        {
            // Cart abandon signal, structure inside the recovered structure
            public string dt { get; set; }
            public string type { get; set; }
            public string evdt { get; set; }
            public Cart cart { get; set; }
        }
        // for recovered records, b_signal now contains:
        // cart.cv - numeric cart value in base currency
        // cart.curr - currency code, e.g. "GBP"
        public class Cart
        {
            // cart contents and info, inside the data returned by various API calls
            public string sbr { get; set; } // site brand
            public string lang { get; set; } // language
            public string curr { get; set; } // currency
            public int qty { get; set; } // quantity of products
            public List p { get; set; } // array of products
            public string u { get; set; } // do not use
            public double cp_delta { get; set; } // do not use
            public string dt { get; set; }
            public string cp { get; set; } // original cart price captured from the website
            public double cv { get; set; } // cart value in base currency
        }
        public class Q
        {
            // query collection information, inside the data returned by various API calls
            public string tmcv { get; set; }
            public string tmcs { get; set; }
            public string tmty { get; set; }
            public string campaign_id { get; set; }
            public string link_id { get; set; }
            public string source { get; set; }
            public string tmti { get; set; }
            public string tmtk { get; set; }
        }
        public class ProductAnalyticsAggregate
        {
            // inside the data returned by product_analytics_aggregate and product_analytics calls
            public string _id { get; } // Product Object ID (unique reference)
                public string prid, name; // Product ID, Product Name
                public string bp, bq; // browsed total value (price), quantity
                public string pp, pq; // purchased total value (price), quantity
                public string cp, cq>; // carted total value (price), quantity
                public string ct; // Number of click-throughs
                public string sbr, curr, lang; // Site Brand (product set), currency, language
        }

Code Samples

Root API

The first sample is a request which lists the available API functions, plus the data that will be returned:

Request

https://api.freshrelevance.com/api/[website_id]/?api_token=[AIP_token]

Response

HTTP 200 OK
Vary: Accept
Content-Type: text/html
Allow: OPTIONS, GET
 
{
    "resources": {
        "carted": "https://api.freshrelevance.com/api/carted/[website_id]/",
        "abandoned": "https://api.freshrelevance.com/api/abandoned/[website_id]/",
        "people": "https://api.freshrelevance.com/api/people/[website_id]/",
        "messages sent": "https://api.freshrelevance.com/api/messages_sent/[website_id]/",
        "products": "https://api.freshrelevance.com/api/products/[website_id]/",
        "purchased": "https://api.freshrelevance.com/api/purchased/[website_id]/",
        "recovered": "https://api.freshrelevance.com/api/recovered/[website_id]/"
        "campaigns": "https://api.freshrelevance.com/api/campaigns/[website_id]/"
        "campaigns_details": "https://api.freshrelevance.com/api/campaigns_details/[website_id]/"
        "summary": "https://api.freshrelevance.com/api/summary/[website_id]/"
        "outline": "https://api.freshrelevance.com/api/outline/[website_id]/"
        "usage": "https://api.freshrelevance.com/api/usage/[website_id]/"
    }
}

Abandoned Carts API Method

Here's a sample which lists the abandoned carts for a particular client account, and some sample data that can be returned:

Request

https://api.freshrelevance.com/api/abandoned/[website_id]/?limit=20&page=1&api_token=[API_token]

Response

Abandoned
This lists the abandoned carts.
200 OK
Vary: Authenticate, Accept
Allow: GET, HEAD, OPTIONS

{
    "next": "/api/abandoned/[website_id]/?limit=20&api_token=[API_token]&page=2",
    "page": 1,
    "pages": 447,
    "per_page": 20,
    "previous": null,
    "results": {
        "data": [
            {
                "cart": {
                    "cp": "$78.96",
                    "dt": "2012-09-03 14:34:09",
                    "p": [
                        {
                            "n": "Sterling Silver Cross Pendant - Bible Gift Box",
                            "prid": "sterling-silver-cross-pendant-bible-gift-box",
                            "qty": 1,
                            "up": "$9.99"
                        },
                        {
                            "n": "Lichfield Self Inflating Mattress",
                            "prid": "lichfield-self-inflating-mattress",
                            "qty": 2,
                            "up": "$17.99"
                        },
                        {
                            "n": "9ct Gold Glitter Ball Pendant",
                            "prid": "9ct-gold-glitter-ball-pendant",
                            "qty": 1,
                            "up": "$32.99"
                        }
                    ]
                },
                "dt": "2012-09-03T14:34:09.053000Z",
                "email": "test.mailings+ce_19632559@example.com",
                "id": "5044c020532b3962ab7706bb",
                "pid": "5044bf731abc4c3e34004333",
                "value": 78.96
            },
            {
                "cart": {
                    "cp": "$2063.95",
                    "dt": "2012-09-03 14:28:18",
                    "p": [
                        {
                            "n": "Chrome Traditional Curved Towel Rail",
                            "prid": "chrome-traditional-curved-towel-rail",
                            "qty": 1,
                            "up": "$17.99"
                        },
                        {
                            "n": "Smeg Dishwasher Right Hand Adjuster Bracket",
                            "prid": "smeg-dishwasher-right-hand-adjuster-bracket",
                            "qty": 2,
                            "up": "$22.99"
                        },
                        {
                            "n": "Go Create Oxford Leather Large Sofa - Black",
                            "prid": "go-create-oxford-leather-large-sofa-black",
                            "qty": 3,
                            "up": "$666.66"
                        }
                    ]
                },
                "dt": "2012-09-03T14:28:18.856000Z",
                "email": "test.mailings+ce_52632598@example.com",
                "id": "5044bef4532b3962ab7705ea",
                "pid": "5044be521abc4c3e34004260",
                "value": 2063.95
            }
        ],
        "resources": [
            "/api/abandoned/[website_id]/5044c020532b3962ab7706bb/",
            "/api/abandoned/[website_id]/5044bef4532b3962ab7705ea/",
            "/api/abandoned/[website_id]/5044bd76532b3962ab7704f7/",
            "/api/abandoned/[website_id]/5044bc53532b3962ab770446/",
            "/api/abandoned/[website_id]/5044b9dc532b3962ab7702b2/",
            "/api/abandoned/[website_id]/5044b96a532b3962ab77025f/",
            "/api/abandoned/[website_id]/5044b8f5532b3962ab770201/",
            "/api/abandoned/[website_id]/5044b87b532b3962ab770196/",
            "/api/abandoned/[website_id]/5044b828532b3962ab77016f/",
            "/api/abandoned/[website_id]/5044b7b6532b3962ab770108/",
            "/api/abandoned/[website_id]/5044b757532b3962ab7700c3/",
            "/api/abandoned/[website_id]/5044b6c8532b3962ab77005c/",
            "/api/abandoned/[website_id]/5044b66a532b3962ab770020/",
            "/api/abandoned/[website_id]/5044b548532b3962ab76ff7d/",
            "/api/abandoned/[website_id]/5044b3fc532b3962ab76fe9e/",
            "/api/abandoned/[website_id]/5044af92532b3962ab76fb58/",
            "/api/abandoned/[website_id]/5044ae71532b3962ab76fab5/",
            "/api/abandoned/[website_id]/5044ac7f532b3962ab76f95b/",
            "/api/abandoned/[website_id]/5044abec532b3962ab76f902/",
            "/api/abandoned/[website_id]/5044ab7c532b3962ab76f8de/"
        ]
    },
    "total": 8925
}

Recovered Carts API

Here's a sample which lists the recovered carts for a particular client account, and some sample data that can be returned:

Request

https://api.freshrelevance.com/api/recovered/[website_id]/?limit=20&page=1&api_token=[API_token]

Response

Recovered
This lists the recovered carts.
200 OK
Vary: Authenticate, Accept
Allow: GET, HEAD, OPTIONS
{
    "next": "/api/recovered/[website_id]/?api_token=[API_token]&page=2&limit=1",
    "page": 1,
    "pages": 113,
    "per_page": 1,
    "previous": null,
    "results": {
        "data": [
            {
                "cart": {
                    "cp": "$92.93",
                    "dt": "2012-09-03 00:48:40",
                    "p": [
                        {
                            "n": "Sony MDRAS30G Active Series Neckband Headphones",
                            "prid": "sony-mdras30g-active-series-neckband-headphones",
                            "qty": 3,
                            "up": "$9.99"
                        },
                        {
                            "n": "9ct Gold Glitter Ball Pendant",
                            "prid": "9ct-gold-glitter-ball-pendant",
                            "qty": 1,
                            "up": "$32.99"
                        },
                        {
                            "n": "Sony MDRAS30G Active Series Neckband Headphones",
                            "This lists the recovered carts.
    200 OK
    Vary: Authenticate, Accept
    Allow: GET, HEAD, OPTIONS
    {
        "next": "/api/recovered/[website_id]/?api_token=[API_token]&page=2&limit=1",
        "page": 1,
        "pages": 113,
        "per_page": 1,
        "previous": null,
        "results": {
            "data": [
                {
                    "cart": {
                        "cp": "$92.93",
                        "dt": "2012-09-03 00:48:40",
                        "p": [
                            {
                                "n": "Sony MDRAS30G Active Series Neckband Headphones",
                                "prid": "sony-mdras30g-active-series-neckband-headphones",
                                "qty": 3,
                                "up": "$9.99"
                            },
                            {
                                "n": "9ct Gold Glitter Ball Pendant",
                                "prid": "9ct-gold-glitter-ball-pendant",
                                "qty": 1,
                                "up": "$32.99"
                            },
                            {
                                "n": "Sony MDRAS30G Active Series Neckband Headphones",
                                "prid": "sony-mdras30g-active-series-neckband-headphones",
                                "qty": 3,
                                "up": "$9.99"
                            }
                        ]
                    },
                    "dt": "2012-09-03T00:48:40.103000Z",
                    "email": "test.mailings+ce_51289843@example.com",
                    "id": "50440077532b3962ab768f3d",
                    "pid": "5043fe5e3004477462028623",
                    "value": 92.93
                }
            ],
            "resources": [
                "/api/recovered/[website_id]/50440077532b3962ab768f3d/"
            ]
        },
        "total": 113
    }

Jobs API

Here's a sample which lists the jobs for a particular client account, and some sample data that can be returned:

Request

https://api.freshrelevance.com/api/[website_id]/jobs/?limit=20&page=1&api_token=[API_token]

Response

This lists the jobs in the client account.
200 OK
Vary: Authenticate, Accept
Allow: GET, HEAD, OPTIONS
{
    "count": 1,
    "links": {
        "previous": null,
        "next": null
    },
    "results": [
        {
            "_id": "5ee78059fce4dad83fc11053",
            "job_type": "person_import",
            "filename": null,
            "name": "import segment qti2ennedrm8ak71lnip",
            "from_q_records_processed": 1300,
            "from_q_valid_records": 1300,
            "to_q_records_processed": 1300,
            "to_q_valid_records": 1300,
            "export_q_records_processed": 1300,
            "download_url": null,
            "status": "export complete",
            "error_code": null,
            "dt": "2020-06-15T14:06:17.863000"
        }
}

Here's a sample which gets the data for one job, and some sample data that can be returned:

Request

https://api.freshrelevance.com/api/[website_id]/jobs/5ee78059fce4dad83fc11053/?&api_token=[API_token]

Response

This lists the jobs in the client account.
200 OK
Vary: Authenticate, Accept
Allow: GET, HEAD, OPTIONS
{
    "_id": "5ee78059fce4dad83fc11053",
    "job_type": "person_import",
    "filename": null,
    "name": "import segment qti2ennedrm8ak71lnip",
    "from_q_records_processed": 1300,
    "from_q_valid_records": 1300,
    "to_q_records_processed": 1300,
    "to_q_valid_records": 1300,
    "export_q_records_processed": 1300,
    "download_url": null,
    "status": "export complete",
    "error_code": null,
    "dt": "2020-06-15T14:06:17.863000"
}

Create a Job

Several types of jobs can be created. The jobs require different sets of parameters to be supplied as follows:

Export Segment

"job_type"	"export_segment"
"segment_key"	"abcdefghi"
"generate_download_url"	0
"notify_email_address"	""
"upload_channel_id"	""

Build Segment

"job_type"	"build_segment"
"job_name"	"test job name"
"segment_key"	"20200716_k7nz7h"

Create a job with the jobs API using CURL

Create a job

curl -X POST -d "job_type=export_segment&segment_key=put_segment_key_here" https://api.freshrelevance.com/api/[website_id]/jobs/?api_token=[API_token]&format=json

If successful, returns the job_id of the created job, which be used subsequently to query the status of the job:

{"errors":[],"ok":true,"job_id":"5f103242e7cfc12ec10ce786"}

API Calls for GDPR

Some API calls are particularly relevant to GDPR:

Find a Person ID (PID) for an email address: /api/wid/people/search/name%40example.com/
Get Person data for a Person ID (PID): /api/wid/reports/visitor/PID/
Set Person data for a Person ID. For example, set to "Do Not Process": PUT /api/wid/people/PID/
Delete Person data for a Person ID. For example, delete a person: DELETE /api/wid/people/PID/

Integration API - content management

Content Management Integration API endpoints

The Content Management Integration API allows you to manage you content within Fresh Relevance. You can create, update, and delete a SmartBlock, Slot or Layout using the Integration API by calling the appropriate endpoint.

Summary of Content Management Endpoints

API	Request line	API Parameters	Allowed Methods
SmartBlock API	/api/[website_id]/smartblocks/?format=json&api_token=[API_token]	date_start, date_end	GET, POST, DELETE
Slot API	/api/[website_id]/slots/?format=json&api_token=[API_token]	date_start, date_end	GET, POST, DELETE
Layout API	/api/[website_id]/layouts/?format=json&api_token=[API_token]	date_start, date_end	GET, POST, DELETE

Some of these APIs have lots of different options and parameters and require further explanation.

List/Create SmartBlocks

https://api.freshrelevance.com/api/[website_id]/smartblocks/?api_token=[API_token]

Content Management API endpoints can return a list of existing items and create new items, the following sections outline the functionality of each endpoint and the POST data required by them.

For more information, contact Support.

SmartBlock Creation

POSTs to the /smartblocks/ API create new SmartBlocks. Each type of SmartBlock requires different parameters.

Product Recommendation SmartBlock

Parameter	Type	Required	Example
name	string	true	"New Product SmartBlock"
type	string	true	“product”
redirect_url	string	true	{{ product.u }}
data_sources	List	true	[ "/products/recommended/after/prids/history/", "/products/recommended/with/prids/", "/products/recommended/after/prids/", "/products/personalised/browsed/", "/products/personalised/carted/", "/products/personalised/abandoned/", "/products/personalised/purchased/", "/products/personalised/custom/", "/cart/current/", "/cart/purchased/", "/cart/abandoned/", "/wishList/", "/products/personalised/targeted/", "/products/trending/browsed/", "/products/trending/carted/", "/products/trending/abandoned/", "/products/trending/purchased/", "/products/impulse/", "/products/new/", "/products/all/", "/products/by_id/" ]
filters	List	true	[{ “field”: “curr”, “val”: “GBP”, }, { "field": "sbr", "val": ["DEMO", "DEMO2"], }]
layout_id	string	true	“product_52”
item_count	integer	true	1,2,3,4 etc.
tags	List	true	[ “people-like-you-buy” ]
personalised	bool	true	true, false
active	bool	true	true, false
crowd_source_window - The number of hours to consider for Crowd Source Datasources	integer	false	24 (One day) 168 (One week) 720 (30 days)

Countdown SmartBlock

Parameter	Type	Required	Example
name	string	true	"New Countdown SmartBlock"
type	string	true	“countdown”
tags	List	false	[ “people-like-you-buy” ]
steps	List	true	Steps list should have three objects which set up the Countdown SmartBlock, the first object contains settings for before the countdown starts. The second contains settings for during the promotion and the third contains settings for after the promotion ends. [ { "animated": true, "font": "", "fontColor": "#555555", "fontSize": 30, "secondsImage": "", "text": "Test Countdown", "url": "", "utm_campaign": "" }, { "animated": true, "font": "", "fontColor": "#555555", "fontSize": 30, "secondsImage": "", "text": "Test Countdown", "url": "", "utm_campaign": "", "start": "2018-05-21T10:29:39.630Z" }, { "animated": true, "font": "", "fontColor": "#555555", "fontSize": 30, "secondsImage": "", "text": "Test Countdown", "url": "", "utm_campaign": "", "start": "2018-05-21T10:29:39.630Z" } ]
allowed_merges	string	false	"example_1, example_2, example_3" (comma separated list)
Medium	string	false	Campaign tracking medium (utm_medium), added to the query collection of the URL, when your shopper clicks on this SmartBlock. (Supports personalization). Also appears in Reports > Campaigns.
Source	string	false	campaign tracking source (utm_source), added to the query collection of the URL, when your shopper clicks on this SmartBlock. (Supports personalization). Also appears in Reports > Campaigns.
layout	string	false	Specify a layout template if one is desired, not required as a default template is always applied.
personalised	bool	true	true, false
active	bool	true	true, false

Instagram SmartBlock

Parameter	Type	Required	Example
name	string	true	"New Instagram SmartBlock"
type	string	true	“instagram”
instagram_id	string	true	'natgeo', 'bbc'
redirect_url	string	true	`{{ item.link }}` Redirect to this URL when somebody clicks on the feed. (Supports personalization). `{{ item.link }}` will redirect to the Instagram post the picture is from. `https://www.instagram.com/{{ options.instagram_id }}/` will redirect to the profile page of the user whose posts you are displaying.
layout	string	true	'photo_grid_with_header', 'photo_strip', 'photo_grid'
tags	List	false	[ “people-like-you-buy” ]
allowed_merges	string	false	"example_1, example_2, example_3" (comma separated list)
hashtag	string	false	'freshrelevance' or '#freshrelevance'
number_of_columns	integer	false	Number of photo columns to display in the SmartBlock
shuffle	bool	false	Return a random selection of posts to display. The selection will be different each time the block is generated.
medium	string	false	Campaign tracking medium (utm_medium), added to the query collection of the URL, when your shopper clicks on this SmartBlock. (Supports personalization). Also appears in Reports > Campaigns.
source	string	false	Campaign tracking source (utm_source), added to the query collection of the URL, when your shopper clicks on this SmartBlock. (Supports personalization). Also appears in Reports > Campaigns.
campaign_code	string	false	Campaign code (utm_campaign), added to the query collection of the URL, when your shopper clicks on this SmartBlock. (Supports personalization). Also appears in Reports > Campaigns.
item_Count	integer	false	The number of posts to retrieve.
personalised	bool	true	true, false
active	bool	true	true, false

Twitter (X) SmartBlock

Parameter	Type	Required	Example
name	string	true	"New Twitter SmartBlock"
type	string	true	“twitter”
twitter_id	string	true	'natgeo', 'bbc'
max_tweets	integer	true	The maximum number of tweets to retrieve, defaults to five tweets.
redirect_url	string	true	Redirect to this URL when somebody clicks on the Twitter feed.
urls	string	true	How to display URLs in tweets, options are: 'none' - no URLs 'short' - short (t.co) URLs 'long' - original URLs
show_title	bool	false	Show the SmartBlock title
show_images	bool	false	Show images
retweets	bool	false	If true retweets are hidden.
title	string	false	Title for the feed: "My latest tweets!"
allowed_merges	string	false	"example_1, example_2, example_3" (comma separated list)
hashtag	string	false	'freshrelevance' or '#freshrelevance'
layout	string	false	"twitter_1", "twitter_2"
medium	string	false	Campaign tracking medium (utm_medium), added to the query collection of the URL, when your shopper clicks on this SmartBlock. (Supports personalization). Also appears in Reports > Campaigns.
source	string	false	Campaign tracking source (utm_source), added to the query collection of the URL, when your shopper clicks on this SmartBlock. (Supports personalization). Also appears in Reports > Campaigns.
campaign_code	string	false	Campaign code (utm_campaign), added to the query collection of the URL, when your shopper clicks on this SmartBlock. (Supports personalization). Also appears in Reports > Campaigns.
tags	List	true	[ “people-like-you-buy” ]
personalised	bool	true	true, false
active	bool	true	true, false

Banner SmartBlock

Parameter	Type	Required	Example
name	string	true	"New Banner SmartBlock"
type	string	true	“banner”
redirect_url	string	true	Redirect to this URL when somebody clicks on the Banner.
headline_text	string	true	"Flash Sale!"
message_text	string	true	"To celebrate our 10th anniversary, we are having a flash sale on a selected range of products."
background_image_url	string	true	"http://www.example.com/link_to_example_image.png"
background_image_url	string	true	"http://www.example.com/link_to_example_image.png"
action_button_content	string	true	"Buy now!"
headline_font	string	false	"Roboto"
headline_color	string	false	"#555555"
headline_size	string	false	"40px"
headline_align	string	false	"inherit", "left", "center", "right"
headline_horizontal_offset	string	false	"0"
headline_vertical_offset	string	false	"0"
message_align	string	false	"inherit", "left", "center", "right"
message_color	string	false	"#555555"
message_font	string	false	"Roboto"
message_horizontal_offset	string	false	"0"
message_vertical_offset	string	false	"0"
message_size	string	false	"40px"
background_repeat	bool	false	true, false
background_color	string	false	"#555555"
height	string	false	"400px"
width	string	false	"300px"
action_button_color	string	false	"#555555"
action_button_background_color	string	false	"#555555"
weather_day	string	false	"plus0days", "plus1days", "plus2days", "plus3days"
icon_colour	string	false	"#555555"
layout	string	false	"twitter_1", "twitter_2"
medium	string	false	Campaign tracking medium (utm_medium), added to the query collection of the URL, when your shopper clicks on this SmartBlock. (Supports personalization). Also appears in Reports > Campaigns.
source	string	false	Campaign tracking source (utm_source), added to the query collection of the URL, when your shopper clicks on this SmartBlock. (Supports personalization). Also appears in Reports > Campaigns.
campaign_code	string	false	Campaign code (utm_campaign), added to the query collection of the URL, when your shopper clicks on this SmartBlock. (Supports personalization). Also appears in Reports > Campaigns.
personalised	bool	true	true, false
active	bool	true	true, false

Coupon SmartBlock

Parameter	Type	Required	Example
name	string	true	"New Coupon SmartBlock"
type	string	true	“coupon”
redirect_url	string	true	Redirect to this URL when somebody clicks on the Coupon SmartBlock.
allowed_merges	string	false	"example_1, example_2, example_3" (comma separated list)
absolute_expiry_date	string	false	ISO String eg 2018-06-05T16:57:40+00:00
countdown_expiry	integer	false	1,2,3
border_color	string	false	hex code, eg #555555, #ffffff
campaign_expired_content	string	false	"Sorry, the offer has ended."
coupon_code_background_color	string	false	hex code, eg #555555, #ffffff
coupon_code_color	string	false	hex code, eg #555555, #ffffff
coupon_expired_content	string	false	"Sorry, the coupon has expired."
coupon_expiry_content	string	false	"Expires: "
coupon_message_color	string	false	hex code, eg #555555, #ffffff
coupon_message_content	string	false	"Save on your next purchase with the coupon code:"
coupon_out_of_stock_content	string	false	"Sorry, the coupon is not available any more."
primary_background_color	string	false	hex code, eg #555555, #ffffff
ribbon_color	string	false	hex code, eg #555555, #ffffff
ribbon_background_color	string	false	hex code, eg #555555, #ffffff
gradient_color_left	string	false	hex code, eg #555555, #ffffff
gradient_color_right	string	false	hex code, eg #555555, #ffffff
layout	string	false	"twitter_1", "twitter_2"
medium	string	false	Campaign tracking medium (utm_medium), added to the query collection of the URL, when your shopper clicks on this SmartBlock. (Supports personalization). Also appears in Reports > Campaigns.
source	string	false	Campaign tracking source (utm_source), added to the query collection of the URL, when your shopper clicks on this SmartBlock. (Supports personalization). Also appears in Reports > Campaigns.
campaign_code	string	false	Campaign code (utm_campaign), added to the query collection of the URL, when your shopper clicks on this SmartBlock. (Supports personalization). Also appears in Reports > Campaigns.
personalised	bool	true	true, false
active	bool	true	true, false

Pinterest SmartBlock

Parameter	Type	Required	Example
name	string	true	"New Pinterest SmartBlock"
type	string	true	“pinterest”
redirect_url	string	true	Redirect to this URL when somebody clicks on the Pinterest SmartBlock.
pinterest_board	string	true	"sports"
pinterest_id	string	true	"freshrelevance"
item_count	int	true	1,2,3,4,5 ect
allowed_merges	string	false	"example_1, example_2, example_3" (comma separated list)
caption_color	string	false	"#555555"
caption_font	string	false	"Roboto"
caption_size	string	false	'40'
caption_bg_color	string	false	'#555555'
message_background_color	string	false	'#555555'
message_color	string	false	'#555555'
message_content	string	false	'Look at my pins!'
message_font	string	false	'Roboto'
message_size	string	false	'40'
description_font	string	false	'Roboto'
number_of_columns	integer	false	1,2,3,4,5,6,7,8,9, ect
pin_bg_color	integer	false	"#555555"
image_border_radius	string	false	'3'
shuffle	bool	false	true, false
show_caption	bool	false	true, false
layout	string	false	"twitter_1", "twitter_2"
medium	string	false	Campaign tracking medium (utm_medium), added to the query collection of the URL, when your shopper clicks on this SmartBlock. (Supports personalization). Also appears in Reports > Campaigns.
source	string	false	Campaign tracking source (utm_source), added to the query collection of the URL, when your shopper clicks on this SmartBlock. (Supports personalization). Also appears in Reports > Campaigns.
campaign_code	string	false	Campaign code (utm_campaign), added to the query collection of the URL, when your shopper clicks on this SmartBlock. (Supports personalization). Also appears in Reports > Campaigns.
personalised	bool	true	true, false
active	bool	true	true, false

Webcrop SmartBlock

Parameter	Type	Required	Example
name	string	true	"New Webcrop SmartBlock"
type	string	true	“webcrop”
redirect_url	string	true	Redirect to this URL when somebody clicks on the SmartBlock.
url	string	true	"http://www.freshrelevance.com" (requires http:// or https:///)
webcrop_height	integer	false	1,2,3...,50, 100, 200 ect
webcrop_width	integer	false	1,2,3...,50, 100, 200 ect
image_format	string	false	'PNG', 'JPG'
top	integer	false	1,2,3...,50, 100, 200 ect
left	integer	false	1,2,3...,50, 100, 200 ect
selector	string	false	"test" (css selector)
viewport	integer	false	1920, 1280, 1024, 768, 800, 480, 320
allowed_merges	string	false	"example_1, example_2, example_3" (comma separated list)
medium	string	false	Campaign tracking medium (utm_medium), added to the query collection of the URL, when your shopper clicks on this SmartBlock. (Supports personalization). Also appears in Reports > Campaigns.
source	string	false	Campaign tracking source (utm_source), added to the query collection of the URL, when your shopper clicks on this SmartBlock. (Supports personalization). Also appears in Reports > Campaigns.
campaign_code	string	false	Campaign code (utm_campaign), added to the query collection of the URL, when your shopper clicks on this SmartBlock. (Supports personalization). Also appears in Reports > Campaigns.
personalised	bool	true	true, false
active	bool	true	true, false

Review SmartBlock

Parameter	Type	Required	Example
name	string	true	"New Review SmartBlock"
type	string	true	“reviews”
redirect_url	string	true	Redirect to this URL when somebody clicks on the SmartBlock.
data_sources	List	true	[ "/products/recommended/after/prids/history/", "/products/recommended/with/prids/", "/products/recommended/after/prids/", "/products/personalised/browsed/", "/products/personalised/carted/", "/products/personalised/abandoned/", "/products/personalised/purchased/", "/products/personalised/custom/", "/cart/current/", "/cart/purchased/", "/cart/abandoned/", "/wishList/", "/products/personalised/targeted/", "/products/trending/browsed/", "/products/trending/carted/", "/products/trending/abandoned/", "/products/trending/purchased/", "/products/impulse/", "/products/new/", "/products/all/", "/products/by_id/" ]
filters	List	true	[{ “field”: “curr”, “val”: “GBP”, }, { "field": "sbr", "val": ["DEMO", "DEMO2"], }]
layout	string	false	Specify a layout template if one is desired, not required as a default template is always applied.
item_count	integer	false	1,2,3,4 etc.
max_stars	integer	false	1,2,3,4 etc.
review_type	string	false	Type of review, options are: 'product' or 'service'
truncate_review	string	false	Maximum review length
individual_review_score_color	string	false	#444444
individual_review_score_font	string	false	Roboto
individual_review_score_size	integer	false	14
review_author_font_color	string	false	#444444
review_author_font_family	string	false	Roboto
review_author_font_size	integer	false	14
review_date_font_color	string	false	#444444
review_date_font_family	string	false	Roboto
review_date_font_size	integer	false	14
review_score_background_color	string	false	#444444
review_sub_score_font_color	string	false	#444444
review_sub_score_font_family	string	false	Roboto
post_sort_by	string	false	field to sort within the results
post_sort_order	string	false	asc or desc
sort_by	string	false	field to sort by
sort_order	string	false	asc or desc
shuffle	boolean	false	shuffle results
allowed_merges	string	false	"example_1, example_2, example_3" (comma separated list)
medium	string	false	Campaign tracking medium (utm_medium), added to the query collection of the URL, when your shopper clicks on this SmartBlock. (Supports personalization). Also appears in Reports > Campaigns.
source	string	false	Campaign tracking source (utm_source), added to the query collection of the URL, when your shopper clicks on this SmartBlock. (Supports personalization). Also appears in Reports > Campaigns.
campaign_code	string	false	Campaign code (utm_campaign), added to the query collection of the URL, when your shopper clicks on this SmartBlock. (Supports personalization). Also appears in Reports > Campaigns.
personalised	bool	true	true, false
active	bool	true	true, false

Create example

Create a recommendation SmartBlock

This Python example creates a Recommendation SmartBlock. The code to create other types of SmartBlocks is similar but uses different POST data:

        url = '/api/testwid/smartblocks/?api_token=[API_token]'
        data = {u'active': True,
             u'data_sources': [],
             u'filters': [],
             u'item_count': 3,
             u'layout_id': u't:product_60:product_52',
             u'name': u'TEST PRODUCT RECOMMENDATION SMARTBLOCK',
             u'personalised': True,
             u'redirect_url': u'{{ product.u }}',
             u'tags': [u'tag'],
             u'type': u'product'}
 
        s_data = json.dumps(data)
        resp = self.client.post(url, data=s_data, content_type='application/json', follow=True)

Replace [API_token] with a valid API token from the API tokens page. To access, expand the User menu and go to Settings > Other Integrations > Fresh Relevance Access Tokens.

SmartBlock list API

This API returns a list of SmartBlocks stored in the system.

https://api.freshrelevance.com/api/[website_id]/smartblocks/?api_token=[API_token]

The following options allow you to modify the output of the API's list view which is accessible via a GET request.

Query string parameter	Functionality
limit	Specifies the maximum number of SmartBlocks to return from the API. For example, `?limit=50` will return the first 50 SmartBlocks rather than the default of 25.
page	Specifies the page to fetch. If not specified then the first page will be returned. For example, `?page=2` will return the second page of results.
filterByType	Takes a comma separated list of SmartBlock types and filters the output. For example, `?filterByType=banner,coupon` Will output a list of all Banner and Coupon SmartBlocks. Invalid SmartBlock types are ignored.
tags	A comma separated list of tags to match. Will return any SmartBlocks that match one or more of the provided tags. For example, `?tags=Recommendation,Banner` will return any SmartBlocks with the tag "Recommendation" or the tag "Banner".
folder_id	Returns only SmartBlocks in the supplied folder. For example, `?folder_id=abc000000000` returns only SmartBlocks in the folder with the folder id of "abc000000000".
search_string	Takes a string and returns only SmartBlocks that has that string in it's "name" parameter. For example, `?search_string=test` will return all SmartBlocks with the word "test" in the name.
include_deleted	Indicates whether to include deleted SmartBlocks in the result. By default deleted SmartBlocks will not be included. For example, `?include_deleted=true` will return all the Slots, including ones that have been deleted.
load_slot_list	Indicates whether to load the "slots" field which contains a list of Slots that contain that SmartBlock. By default this field is not included as including this field may reduce performance. For example, `?load_slot_list=true`
include_live_flag	Indicates whether to load the "is_live" field which contains a Boolean indicating whether that piece of content has recently received impressions from your shoppers. For example, `?include_live_flag=true`
typeCount	Boolean Will output a count of all SmartBlocks of each type. For example, `?typeCount=true` "results": [{ "product": 50, "instagram": 4, "custom": 2, "countdown": 13, "popover": 2, "banner": 21, "webcrop": 1 }]

The response for each SmartBlock includes the layout key. This can be used to lookup the layout, which includes the HTML used by that SmartBlock.

Layouts may be shared by more than one SmartBlock. So, for example:

https://api.freshrelevance.com/api/[website_id]/smartblocks/?api_token=[API_token] returns various data including

layout= 7zkghol: {
    ...
    layout: "7zkghol",
    ...
}

This call:

https://api.freshrelevance.com/api/[website_id]/layouts/7zkghol/?api_token=[API_token] would then return this response, including the HTML used by the SmartBlock

 {
    "content_tag": null,
    "name": "Copy of 2020-02-04 Welcome discount - left",
    "version": 0,
    "html": "
content will be here 
",
    "content_type": "banner",
    "active": true,
    "dt": "2020-02-04T11:39:54.770000",
    "slug": "7zkghol",
    "template_style": "banner_new_customer_2"
}

SmartBlock bulk API

This API allows multiple SmartBlocks to be edited at once. For example, to update the folder ID of multiple SmartBlocks make the following request. Replace the values "smartblock1,smartblock2" with a comma separated list of the SmartBlock slugs to update. The new field values should be included in the request body.

POST https://api.freshrelevance.com/api/[website_id]/smartblocks/smartblock1,smartblock2/bulk/?api_token=[API_token] {
    "folder_id": "[NEW FOLDER ID]"
}

This API supports updating the "folder_id", "locked" and "active" fields. The "active" field should be set to true to undelete the SmartBlocks. To delete multiple SmartBlocks use the DELETE method on the same API URL. Make sure to insert the comma separated list of SmartBlocks. No body data is required to delete SmartBlocks with the bulk API.

 DELETE https://api.freshrelevance.com/api/[website_id]/smartblocks/smartblock1,smartblock2/bulk/?api_token=[API_token]

Clone SmartBlock API

A POST request to this API will clone a SmartBlock. No extra data is required in the request body. It will create a copy of the SmartBlock specified by the [smartblock_id] value and return the new SmartBlock data. https://api.freshrelevance.com/api/[website_id]/smartblocks/[smartblock_id]/clone/?api_token=[API_token]

Slot list API

This API returns a list of Slots in the system. Only Slots that contain at least one SmartBlock will be returned.

https://api.freshrelevance.com/api/[webstie_id]/slots/?api_token=[API_token]

The following options allow you to modify the output of the API's list view which is accessible via a GET request.

Query string parameter	Functionality
limit	Specifies the maximum number of Slots to return from the API. For example, `?limit=50` will return the first 50 Slots rather than the default of 25.
page	Specifies the page to fetch. If not specified then the first page will be returned. For example, `?page=2` will return the second page of results.
tags	A comma separated list of tags to match. Will return any Slots that match one or more of the provided tags. For example, `?tags=Recommendation,Banner` will return any Slots with the tag "Recommendation" or the tag "Banner".
folder_id	Returns only SmartBlocks in the supplied folder. For example, `?folder_id=abc000000000` returns only SmartBlocks in the folder with the folder ID of "abc000000000".
slot_type	Takes a Slot type character code to return only that type of Slot. For example `?slot_type=e` will return only email Slots and `?slot_type=w` will return only web Slots
search_string	Takes a string and returns only Slots that have that string in either the "name" or "slug" parameters. For example, `?search_string=test` will return all Slots with the word "test" in it's name.
include_deleted	Indicates whether to include deleted Slots in the result. By default deleted Slots will not be included. For example, `?include_deleted=true` will return all the Slots, including ones that have been deleted.
load_smartblock_list	Indicates whether to load the "smartblocks" field which contains a list of SmartBlocks that are contained within the Slot. By default this field is not included as including this field may reduce performance. For example, `?load_smartblock_list=true`
include_empty_slots	Indicates whether to include Slots that contain no SmartBlocks. If a Slot does not contain any SmartBlocks then some fields may be missing including "smartblock_type", "height", "width" and "smartblocks". By default only slots that contain at least one SmartBlock are included. For example, `?include_empty_slots=true`
include_live_flag	Indicates whether to load the "is_live" field which contains a Boolean indicating whether that piece of content has recently received impressions from your shoppers. For example, `?include_live_flag=true`

Create Slot API

A POST request to this API will create a new Slot. https://api.freshrelevance.com/api/[website_id]/slots/?api_token=[API_token]

The required parameters are similar to that of the "Slot Update" API and are listed below.

Parameter	Type	Required	Default Value	Example
name	String	true	-	"Main Offer"
unique_slot_reference	String	true	-	main-offer
tags	List	true	-	["people-like-you-buy"]
slot_type	String	true	-	EMAIL = 'e' WEB = 'w' TRIGGED EMAIL = 'te'
smartblock_id	String	true	-	“hxr549a”
personalised	Boolean	false	false	true, false
active	Boolean	false	true	true, false
folder_id	String	false	-	abc000000000

Clone Slot API

A POST request to this API will clone a Slot. No extra data is required in the request body. It will create a copy of the slot specified by the [slotid] value and return the new Slots data. https://api.freshrelevance.com/api/[website_id]/slots/[slotid]/clone/?api_token=[API_token]

Layout API

Method	Functionality
GET	List existing Layouts
POST	Create a new Layout

URL query string options

Parameter	Example	Description	Default
page	&page=2	Specify which page to return.	1
limit	&limit=100	Specifies the number maximum of results to return.	10
include_deleted	&include_deleted=true	If true then include deleted layouts in the result.	false
include_html	&include_html=false	Specified whether the html object should be returned or not. Set to false to improve performance.	true
include_live_flag	&include_live_flag=true	If true then include the is_live flag in the results. This may reduce performance so only include if required.	false

Result parameters

Parameter	Type	Required	Example
name	string	true	"New Layout"
type	string	false	"engage", "convert", "recover", "product", "instagram", "countdown", "banner", "custom"
html	string	true	HTML Document

Slot Bulk API

This API allows multiple Slots to be edited at once. For example, to update the folder ID of multiple Slots make the following request. Replace the values "slot1,slot2" with a comma separated list of the Slot slugs to update. The new field values should be included in the request body.

POST https://api.freshrelevance.com/api/[website_id]/slots/slot1,slot2/bulk/?api_token=[API_token] {
    "folder_id": "[NEW FOLDER ID]"
}

This API supports updating the "folder_id", "locked" and "active" fields. The "active" field should be set to true to undelete the Slots. To delete multiple Slots use the DELETE method on the same API URL. Make sure to insert the comma separated list of Slots. No body data is required to delete Slots with the bulk API.

DELETE https://api.freshrelevance.com/api/[website_id]/slots/slot1,slot2/bulk/?api_token=[API_token]

SmartBlock API - Details / Update

https://api.freshrelevance.com/api/[website_id]/smartblocks/smartblock-id/?api_token=[API_token]

Show detailed information about a single item by supplying the SmartBlock in the URL as show above. Post requests to this URL will update the specified item. The following sections outline the functionality of each endpoint and the parameters required by them.

For more information, contact Support.

Method	Functionality
GET	Show details of specified SmartBlock
POST	Update specified SmartBlock

Parameter	Type	Required	Example
name	string	true	"New Product SmartBlock"
redirect_url	string	true	{{ product.u }}
data_sources	List	true	[ "/products/recommended/after/prids/history/", "/products/recommended/with/prids/", "/products/recommended/after/prids/", "/products/personalised/browsed/", "/products/personalised/carted/", "/products/personalised/abandoned/", "/products/personalised/purchased/", "/products/personalised/custom/", "/cart/current/", "/cart/purchased/", "/cart/abandoned/", "/wishList/", "/products/personalised/targeted/", "/products/trending/browsed/", "/products/trending/carted/", "/products/trending/abandoned/", "/products/trending/purchased/", "/products/impulse/", "/products/new/", "/products/all/", "/products/by_id/" ]
filters	List	true	[{ “field”: “curr”, “val”: “GBP”, }, { "field": "sbr", "val": ["DEMO", "DEMO2"], }]
layout_id	string	true	“product_52”
item_count	integer	true	1,2,3,4 etc.
tags	List	true	[ “people-like-you-buy” ]
personalised	bool	true	true, false
active	bool	true	true, false

Slot API - Details / Update

https://api.freshrelevance.com/api/[website_id]/slots/slot-id/?api_token=[API_token]

Show detailed information about a single slot by supplying the Slot ID in the URL as shown above. Post requests to this URL will update the specified item. The following sections outline the functionality of each endpoint and the parameters required by them.

Method	Functionality
GET	Show details of specified Slot
POST	Update specified Slot

Parameter	Type	Required	Example
name	string	true	"Main Offer"
tags	List	true	["people-like-you-buy"]
smartblock_id	string	true	“hxr549a”
personalised	bool	true	true, false
active	bool	true	true, false
folder_id	String	false	abc000000000

Layout API - Details / Update

https://api.freshrelevance.com/api/[website_id]/layouts/layout-id/?api_token=[API_token]

Show detailed information about a single layout by supplying the layout ID in the URL as show above. Post requests to this URL will update the specified item. The following sections outline the functionality of each endpoint and the parameters required by them.

Method	Functionality
GET	Show details of specified Layout
POST	Update specified Layout

Parameter	Type	Required	Example
html	string	true	HTML Document

Mobile and app API

JavaScript API - JS API

Product import API

Marketing rule types

Create Custom data tables