{"openapi":"3.0.3","info":{"title":"Slots API","description":"Manages slots within Dotdigital Personalization. Slots are the placeholders on a web page or digital surface where personalised content blocks are rendered. Operations include listing all slots for a website, creating new slots, retrieving a specific slot's configuration, updating slot properties, and deleting slots.","version":"1.0.1"},"servers":[{"url":"https://{region}-api-freshrelevance.dotdigital.com/api","variables":{"region":{"description":"The region id your account belongs to","enum":["r1","r2","r3"],"default":"r1"}}}],"security":[{"apiTokenAuth":[]}],"paths":{"/{website_id}/slots/":{"get":{"tags":["Manage slot"],"summary":"List slots","description":"Retrieves a list of the slots.","operationId":"getListSlots","parameters":[{"name":"website_id","in":"path","description":"Website ID for the account you are posting data to.","required":true,"schema":{"type":"string"},"example":"abc123"},{"name":"format","in":"query","description":"Get data in JSON format.","required":true,"schema":{"type":"string","enum":["json"]},"example":"json"},{"name":"limit","in":"query","description":"Get this number of records to return in results array (pagination).","schema":{"minimum":1,"type":"integer","default":25},"example":50},{"name":"page","in":"query","description":"Which page of results you wish to return; First page is indexed as 1.","schema":{"type":"integer","default":1},"example":1},{"name":"tags","in":"query","description":"A comma seperated list of tags to match.","required":false,"schema":{"type":"array","items":{"type":"string"}},"example":"Recommendation,Banner"},{"name":"folder_id","in":"query","description":"If provided only slots contained in the specified folder will be returned.","required":false,"schema":{"type":"string"},"example":"abc12345"},{"name":"slot_type","in":"query","description":"If provided only slots of the type in the specified will be returned.\n* **e** - Email slot\n* **te** - Triggered email slot\n* **w** - Web slot","required":false,"schema":{"type":"string","enum":["e","te","w"]},"example":"e"},{"name":"search_string","in":"query","description":"Returns only Slots that have the search string in either it's **name** or **slug** parameters.","required":false,"schema":{"type":"string"},"example":"test"},{"name":"include_deleted","in":"query","description":"Indicates whether to include deleted slots or not.","required":false,"schema":{"type":"boolean","default":false},"example":true},{"name":"load_smartblock_list","in":"query","description":"Indicates whether to return the **smartblocks** field or not, containing l list of Smartblocks that are used in the slot.","required":false,"schema":{"type":"boolean","default":false},"example":true},{"name":"include_empty_slots","in":"query","description":"Indicates whether to include slots with no Smartblocks or not.","required":false,"schema":{"type":"boolean","default":false}},{"name":"include_live_flag","in":"query","description":"Indicates whether to include **is_live** fields or not, which indicates that the content has recently received an impression.","required":false,"schema":{"type":"boolean","default":false},"example":true}],"responses":{"200":{"description":"The slots content in the requested format.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/inline_response_200"},"examples":{"success":{"value":{"count":2,"total":132,"page":1,"links":{"next":"https://api.freshrelevance.com/api/abc1234/slots/?limit=2&page=2&tags=Recommendation%2CBanner&include_deleted=false&load_smartblock_list=true&include_empty_slots=false&include_live_flag=true"},"results":[{"slug":"ls-test-old-smartblock-2dot","name":"LS test old smartblock-2dot","type":"Email Personalization","dt":"2024-11-20T14:43:43.648000","personalised":true,"item_count":3,"width":198,"height":334,"tags":["Recommendation"],"smartblock_type":"product","folder_id":"5f95ytrvghmq","active":true,"last_edited_by":"joe.bloggs","locked":false,"ignore_control_group":false,"merge_params":["prid"],"preview_url":"https://c8.dycdn.net/abc1234/s/ls-test-old-smartblock-2dot/?preview=true&k=ocemgn4","thumbnail_url":"https://c8.dycdn.net/abc1234/s/ls-test-old-smartblock-2dot/?format=thumb&k=ocemgn4&cachebust=1733222058638","details":"https://api.freshrelevance.com/api/abc1234/slots/ls-test-old-smartblock-2dot/","smartblocks":[{"slug":"j2t8lei","name":"LS test old smartblock","type":"product","dt":"2024-11-07T10:23:10.771000"}],"is_live":false},{"slug":"ls-test-min-width","name":"ls test min width","type":"Email Personalization","dt":"2024-11-20T14:43:43.645000","personalised":true,"item_count":1,"width":0,"height":0,"tags":["Banner"],"smartblock_type":"banner","folder_id":"5f95ytrvghmq","active":true,"last_edited_by":"joe.bloggs","locked":false,"ignore_control_group":false,"merge_params":[],"preview_url":"https://c8.dycdn.net/abc1234/s/ls-test-min-width/?preview=true&k=ocemgn4","thumbnail_url":"https://c8.dycdn.net/abc1234/s/ls-test-min-width/?format=thumb&k=ocemgn4&cachebust=1733222059386","details":"https://api.freshrelevance.com/api/abc1234/slots/ls-test-min-width/","smartblocks":[{"slug":"bpf5d3l","name":"ls test min width","type":"banner","dt":"2024-10-28T09:46:03.915000"}],"is_live":true}]}}}}}},"400":{"$ref":"#/components/responses/ErrorResponse"},"401":{"description":"Unauthorized"},"403":{"$ref":"#/components/responses/403Response"}}},"post":{"tags":["Manage slot"],"summary":"Create slot","description":"Creates a new slot.","operationId":"postCreateSlot","parameters":[{"name":"website_id","in":"path","description":"Website ID for the account you are posting data to.","required":true,"schema":{"type":"string"},"example":"abc123"},{"name":"format","in":"query","description":"Get data in JSON format.","required":true,"schema":{"type":"string","enum":["json"]},"example":"json"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/website_id_slots_body"}}}},"responses":{"200":{"description":"The created slot slug.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SlotSlugDetails"}}}},"400":{"$ref":"#/components/responses/ErrorResponse"},"401":{"description":"Unauthorized"},"403":{"$ref":"#/components/responses/403Response"}}}},"/{website_id}/slots/{slot_id}/":{"get":{"tags":["Manage slot"],"summary":"Get slot","description":"Gets the specified slot details.","operationId":"getGetSlot","parameters":[{"name":"website_id","in":"path","description":"Website ID for the account you are posting data to.","required":true,"schema":{"type":"string"},"example":"abc123"},{"name":"format","in":"query","description":"Get data in JSON format.","required":true,"schema":{"type":"string","enum":["json"]},"example":"json"},{"name":"slot_id","in":"path","description":"The Slot unique id / slug to update.","required":true,"schema":{"type":"string"},"example":"my-slot"}],"responses":{"200":{"description":"The slot details.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Slot"}}}},"400":{"$ref":"#/components/responses/ErrorResponse"},"401":{"description":"Unauthorized"},"403":{"$ref":"#/components/responses/403Response"}}},"post":{"tags":["Manage slot"],"summary":"Update slot","description":"Updates a slot and returns the updated slot details.","operationId":"postUpdateSlot","parameters":[{"name":"website_id","in":"path","description":"Website ID for the account you are posting data to.","required":true,"schema":{"type":"string"},"example":"abc123"},{"name":"format","in":"query","description":"Get data in JSON format.","required":true,"schema":{"type":"string","enum":["json"]},"example":"json"},{"name":"slot_id","in":"path","description":"The Slot unique id / slug to update.","required":true,"schema":{"type":"string"},"example":"my-slot"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/slots_slot_id_body"}}}},"responses":{"200":{"description":"The updated slot details.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Slot"}}}},"400":{"$ref":"#/components/responses/ErrorResponse"},"401":{"description":"Unauthorized"},"403":{"$ref":"#/components/responses/403Response"}}},"delete":{"tags":["Manage slot"],"summary":"Delete slot","description":"Deletes the specified slot.","operationId":"delDeleteSlot","parameters":[{"name":"website_id","in":"path","description":"Website ID for the account you are posting data to.","required":true,"schema":{"type":"string"},"example":"abc123"},{"name":"format","in":"query","description":"Get data in JSON format.","required":true,"schema":{"type":"string","enum":["json"]},"example":"json"},{"name":"slot_id","in":"path","description":"The Slot unique id / slug to update.","required":true,"schema":{"type":"string"},"example":"my-slot"}],"responses":{"200":{"description":"Successfully deleted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/inline_response_200_1"}}}},"400":{"$ref":"#/components/responses/ErrorResponse"},"401":{"description":"Unauthorized"},"403":{"$ref":"#/components/responses/403Response"}}}},"/{website_id}/slots/{slot_id}/clone/":{"post":{"tags":["Manage slot"],"summary":"Clone slot","description":"Clones a slot and returns the cloned slot details.","operationId":"postCloneSlot","parameters":[{"name":"website_id","in":"path","description":"Website ID for the account you are posting data to.","required":true,"schema":{"type":"string"},"example":"abc123"},{"name":"format","in":"query","description":"Get data in JSON format.","required":true,"schema":{"type":"string","enum":["json"]},"example":"json"},{"name":"slot_id","in":"path","description":"The Slot unique id / slug to clone.","required":true,"schema":{"type":"string"},"example":"my-original-slot"}],"responses":{"200":{"description":"The cloned slot details.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Slot"}}}},"400":{"$ref":"#/components/responses/ErrorResponse"},"401":{"description":"Unauthorized"},"403":{"$ref":"#/components/responses/403Response"}}}},"/{website_id}/slots/{slugs}/bulk/":{"post":{"tags":["Bulk operations"],"summary":"Bulk update slots","description":"Allows multiple slots to be edited at once for example, to update the folder id of multiple slots.\nThis API supports updating the `folder_id`, `locked` and `active` fields only. The `active` field should be set to `true` to undelete the slots.","operationId":"postBulkUpdateSlots","parameters":[{"name":"website_id","in":"path","description":"Website ID for the account you are posting data to.","required":true,"schema":{"type":"string"},"example":"abc123"},{"name":"format","in":"query","description":"Get data in JSON format.","required":true,"schema":{"type":"string","enum":["json"]},"example":"json"},{"name":"slugs","in":"path","description":"Slot slug(s), comma delimited list of slugs","required":true,"style":"simple","schema":{"type":"array","items":{"minLength":1,"type":"string","example":"wddaq4t"}}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/slugs_bulk_body"}}},"required":true},"responses":{"200":{"description":"Successful call","content":{"application/json":{"schema":{"$ref":"#/components/schemas/inline_response_200_2"}}}},"400":{"$ref":"#/components/responses/ErrorResponse"},"401":{"description":"Unauthorized"},"403":{"$ref":"#/components/responses/403Response"}}},"delete":{"tags":["Bulk operations"],"summary":"Bulk delete slots","description":"Allows multiple slots to be deleted at once.","operationId":"delBulkDeleteSlots","parameters":[{"name":"website_id","in":"path","description":"Website ID for the account you are posting data to.","required":true,"schema":{"type":"string"},"example":"abc123"},{"name":"format","in":"query","description":"Get data in JSON format.","required":true,"schema":{"type":"string","enum":["json"]},"example":"json"},{"name":"slugs","in":"path","description":"Slot slug(s), comma delimited list of slugs","required":true,"style":"simple","schema":{"type":"array","items":{"minLength":1,"type":"string","example":"wddaq4t"}}}],"responses":{"200":{"description":"Successfully deleted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/inline_response_200_3"}}}},"400":{"$ref":"#/components/responses/ErrorResponse"},"401":{"description":"Unauthorized"},"403":{"$ref":"#/components/responses/403Response"}}}}},"components":{"schemas":{"SlotSlugDetails":{"required":["ok","slug"],"type":"object","properties":{"ok":{"type":"boolean","description":"Whether the call succeeded or not.","example":true,"enum":[true]},"slug":{"type":"string","description":"Unique identifier for the slot.","example":"my-new-slot"}}},"Slot":{"required":["active","details","dt","folder_id","ignore_control_group","item_count","last_edited_by","locked","merge_params","name","personalised","preview_url","slug","tags","thumbnail_url","type"],"type":"object","properties":{"slug":{"type":"string","description":"Unique id for the slot.","example":"279326-merge-test"},"name":{"type":"string","description":"Name of slot.","example":"279326-merge-test"},"type":{"type":"string","description":"The Slots type","example":"Email Personalization"},"dt":{"type":"string","description":"Date last modified in ISO-8601 format.","example":"2024-10-31T05:38:33.878Z"},"personalised":{"type":"boolean","description":"If the slot uses personalisation or not","example":true},"item_count":{"type":"integer","description":"Number of itesm of content in the slot.","example":3},"width":{"type":"integer","description":"Width in pixels of the the slot.","nullable":true,"example":600},"height":{"type":"integer","description":"Height in pixels of the the slot.","nullable":true,"example":400},"tags":{"type":"array","description":"Tags associated with the slot.","example":["promo","landing_page"],"items":{"type":"string"}},"smartblock_type":{"type":"string","description":"The Smartblock type used in the slot","nullable":true,"example":"Countdown"},"folder_id":{"type":"string","description":"The folder identifier the slot is assigned to.","nullable":true,"example":"35437653dfe"},"active":{"type":"boolean","description":"Indicates whether the slot is in use or not.","example":true},"locked":{"type":"boolean","description":"Indicates whether the slot is locked to prevent editing or not.","example":false},"last_edited_by":{"type":"string","description":"Username of who updated the Slot last.","nullable":true,"example":"joe.blogs"},"ignore_control_group":{"type":"boolean","description":"Indicates whether the slots control group is ignored or not.","example":false},"merge_params":{"type":"array","description":"Any merge parameters that apply to this slot.","items":{"type":"object","additionalProperties":{"type":"string"}}},"preview_url":{"type":"string","description":"URL to preview the slot.","format":"url"},"thumbnail_url":{"type":"string","description":"URL to thumbnail of the slot.","format":"url"},"details":{"type":"string","description":"URL to retrive the slots details.","format":"url"}}},"folder_id":{"type":"object","properties":{"folder_id":{"type":"string","description":"The folder id this Smartblock belongs to, if any","nullable":true}}},"locked":{"type":"object","properties":{"locked":{"type":"boolean","description":"Whether the Smartblock is locked to read-only","example":false}}},"active":{"type":"object","properties":{"active":{"type":"boolean","description":"Indicates whether the Smartblock is active or not","default":true}}},"PaginatedData":{"required":["count","links","page","total"],"type":"object","properties":{"page":{"minimum":1,"type":"integer","description":"The index for the page of data returned.","example":1},"count":{"minimum":0,"type":"integer","description":"Number of records in the page.","example":12},"total":{"minimum":0,"type":"integer","description":"Total number of records in the set.","example":12},"links":{"$ref":"#/components/schemas/PaginatedData_links"}},"description":"Data page and pagination links"},"inline_response_200":{"allOf":[{"$ref":"#/components/schemas/PaginatedData"},{"required":["results"],"type":"object","properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/Slot"}}},"description":"The slots content in the requested format."}]},"website_id_slots_body":{"required":["name","slot_type","smartblock_id","tags","unique_slot_reference"],"type":"object","properties":{"name":{"type":"string","description":"Name of slot.","example":"New test slot"},"unique_slot_reference":{"type":"string","description":"The unique identifier for the slot (_slug_).","example":"new-test-slot"},"tags":{"type":"array","description":"Any tags to associate with the slot.","example":["Landing_page","Promo"],"items":{"type":"string"}},"slot_type":{"type":"string","description":"Type of slot.\n* **w** - Website\n* **e** - Email\n* **te** - Triggered Email","example":"w","enum":["w","e","te"]},"smartblock_id":{"type":"string","description":"The unique Smartblock id this slot will contain.","example":"hxr5643"},"personalised":{"type":"boolean","description":"Whether to personalize the slots content or not.","example":true,"default":false},"active":{"type":"boolean","description":"Whether the slot is active or not.","example":true,"default":true},"folder_id":{"type":"string","description":"The folder id to place the slot into.","example":"acv44332"}},"description":"The new slot details."},"slots_slot_id_body":{"type":"object","properties":{"name":{"type":"string","description":"Name of slot.","example":"279326-merge-test"},"tags":{"type":"array","description":"Tags associated with the slot.","example":["promo","landing_page"],"items":{"type":"string"}},"smartblock_id":{"type":"string","description":"The unique Smartblock id this slot will contain.","example":"hxr5643"},"personalised":{"type":"boolean","description":"Whether to personalize the slots content or not.","example":true},"active":{"type":"boolean","description":"Whether the slot is active or not.","example":true},"folder_id":{"type":"string","description":"The folder id to place the slot into.","example":"acv44332"}},"description":"The new slot details."},"inline_response_200_1":{"required":["ok","results"],"type":"object","properties":{"ok":{"type":"boolean","description":"Indicates whether the call succeeded.","enum":[true]},"results":{"type":"array","description":"Details of the deleted slot.","items":{"$ref":"#/components/schemas/Slot"}}}},"slugs_bulk_body":{"allOf":[{"description":"The properties to update on all slots"},{"$ref":"#/components/schemas/active"},{"$ref":"#/components/schemas/locked"},{"$ref":"#/components/schemas/folder_id"}]},"inline_response_200_2":{"required":["errors","ok","results"],"type":"object","properties":{"ok":{"type":"boolean","description":"Indicates if the call was successful or not.","example":true},"errors":{"type":"array","description":"Any error messages returned.","items":{"type":"string"}},"results":{"type":"array","description":"The updated details.","items":{"$ref":"#/components/schemas/Slot"}}}},"inline_response_200_3":{"required":["ok","results"],"type":"object","properties":{"ok":{"type":"boolean","description":"Indicates whether the call succeeded.","enum":[true]},"errors":{"type":"array","description":"Any errors that occurred.","example":[],"items":{"type":"string","description":"Error detail."}},"results":{"type":"array","description":"Details of the deleted slot(s).","items":{"$ref":"#/components/schemas/Slot"}}}},"PaginatedData_links":{"type":"object","properties":{"next":{"type":"string","description":"URL of the next page.","format":"url","nullable":true},"previous":{"type":"string","description":"URL of the previous page.","format":"url","nullable":true}},"description":"Page navigation links"}},"responses":{"ErrorResponse":{"description":"An error occurred","content":{"application/json":{"schema":{"required":["error","ok"],"type":"object","properties":{"ok":{"type":"boolean","description":"Indicates the call failed","enum":[false]},"error":{"oneOf":[{"type":"string","description":"The reason the call errored","example":"Validation error. No folder bd8eciompb7y, unable to delete"},{"type":"object","additionalProperties":{"minItems":1,"type":"array","items":{"type":"string","example":"This field may not be null."}},"description":"Fields with issues and their errors"}]}}}}}},"403Response":{"description":"Forbidden - Usually you are requesting data for a website you don't have access to."}},"parameters":{"WebsiteId":{"name":"website_id","in":"path","description":"Website ID for the account you are posting data to.","required":true,"schema":{"type":"string"},"example":"abc123"},"FormatJson":{"name":"format","in":"query","description":"Get data in JSON format.","required":true,"schema":{"type":"string","enum":["json"]},"example":"json"},"Limit":{"name":"limit","in":"query","description":"Get this number of records to return in results array (pagination).","schema":{"minimum":1,"type":"integer","default":25},"example":50},"Page":{"name":"page","in":"query","description":"Which page of results you wish to return; First page is indexed as 1.","schema":{"type":"integer","default":1},"example":1}},"securitySchemes":{"apiTokenAuth":{"type":"apiKey","name":"x-api-key","in":"header"}}},"x-samples-languages":["curl","csharp","java","javascript","node","python","php","ruby"]}