This article outlines a generic understanding of the Content List feature and its management via API. If you are not yet familiar with Content Lists, please read this article first.
For more sophisticated and ambitious integrations, please reach out to the support team and having read the api documentation beforehand.
Content Lists via API
Content Lists and Content List Items can be managed via API. There are dedicated endpoints for the Content Lists and each of the item types.
Endpoints
There are various endpoints, which need to be called for distinct purposes.
Content Lists
Content Lists are the object in our database to group Content Items. You can use the API to create, manage and delete Content Lists.
.../api/content-lists
- supports GET, POST calls
- used to retrieve all Content Lists or create one Content List
.../api/content-lists/$id
- supports GET, PATCH, DELETE calls
- Lists one or multiple Content List Items of one type
- Used to manage and delete Content Lists
Custom Items
.../api/custom-items
- supports GET, POST calls
- used to retrieve all Content Items with type "CUSTOM" or to create Content Items with type "CUSTOM"
.../api/custom-items/$id
- supports GET, PATCH, DELETE calls
- Content List Item object
- Used to manage and delete Custom Items
Events
.../api/events
- supports GET, POST calls
- used to retrieve all Content Items with type "EVENTS" or create Content Items with type "EVENTS"
.../api/events/$id
- supports GET, PATCH, DELETE calls
- Content List Item object
- Used to manage and delete Events
Menu Items
.../api/menu-items
- supports GET, POST calls
- used to retrieve all Content Items with type "MENU" or create Content Items with type "MENU"
.../api/menu-items
- supports GET, PATCH, DELETE calls
- Content List Item object
- Used to manage and delete Menu Items
Persons
.../api/persons
- supports GET, POST calls
- used to retrieve all Content Items with type "PEOPLE" or create Content Items with type "PEOPLE"
.../api/persons/$id
- supports GET, PATCH, DELETE calls
- Content List Item object
- Used to manage and delete People/Persons
Products
.../api/products
- supports GET, POST calls
- used to retrieve all Content Items with type "PRODUCTS" or create Content Items with type "PRODUCTS"
.../api/products/$id
- supports GET, PATCH, DELETE calls
- Content List Item object
- create, manage and delete Products
Services
.../api/service-items
- supports GET, POST calls
- used to retrieve all Content Items with type "SERVICES" or create Content Items with type "SERVICES"
.../api/service-items/$id
- supports GET, PATCH, DELETE calls
- Content List Item object
- create, manage and delete Services
How to start?
The steps below describe, in a very generic way, what to do to bring the API integration for Content Lists to life:
- Create a Content List
- Remember the responded Content List ID
- Create at least one Content List Item
- Remember the responded Content List Item ID
- Use the PATCH method to update the Content List you just created with the Content Item ID
In the following sections you will find more detailed information about the steps above.
How to manage a Content List?
Info
Your account's privateKey is is required for all your API calls. The key can be found in our platform.
Create
To create a Content List call this endpoint with the POST method:
.../api/content-lists
Provide the following fields in the body (Example type "CUSTOM"):
body
{
"contentList": {
"title": "THIS IS A TITLE",
"type": "CUSTOM",
"items": []
}
}
Note that the array for "items" is empty. This means, that the Content List will be created without any items assigned yet. If you'd like to assign existing items to the Content List when creating it, list the Content Item IDs separated by comma in the items array.
"items": [CONTENT_ITEM_ID1, CONTENT_ITEM_ID2, CONTENT_ITEM_ID3]
In the response of your POST call you will retrieve the ID of the Content List you just created.
Edit
To edit data of a Content List, call this endpoint with the PATCH method:
Replace "$id" with the very Content List ID of the List you want to edit.
.../api/content-lists/$id
The body of the API call should contain the fields you want to edit:
body
{
"contentList": {
"title": "THIS IS A NEW TITLE",
"type": "CUSTOM",
"items": [CONTENT_ITEM_ID41, CONTENT_ITEM_ID442, CONTENT_ITEM_ID34]
}
}
In the response of your PATCH call you will retrieve the updated data fields.
Delete
To delete a Content List call this endpoint via DELETE:
.../api/content-lists/$id
In the response of your DELETE call you will retrieve the message "SUCCESS", when the Content List is successfully deleted. You will no longer be able to call the deleted Content List.
How to manage Content List Items?
Info
Your account's privateKey is is required for all your API calls. The key can be found in our platform.
Create
To create a Content List Item call this endpoint with the POST method (Example type "MENU"):
.../api/menu-items
Provide the following fields in the body (Example type "MENU"):
body
{
"identifier": "THIS IS MY IDENTIFIER",
"title": "BREAKFAST",
"description": "BREAKFAST IS THE MOST IMPORTANT MEAL OF THE DAY",
"category": null,
"image": null,
"url": "https://www.mymenu.com/",
"price": null,
"priceMax": null,
"currency": null,
"listName": "MY MENU"
}
The Content List Item ID will be returned in the response of the POST call.
Edit
To edit data of a Content List Item, call this endpoint with the PATCH method:
Replace "$id" with the Content List Item ID of the Item you want to edit.
.../api/menu-items/$id
The body of the API call should contain the fields you want to edit:
body
{
"identifier": "THIS IS MY NEW IDENTIFIER",
"title": "BREAKFAST 2.0",
"description": "BREAKFAST IS THE VERY MOST IMPORTANT MEAL OF THE DAY",
"category": null,
"image": null,
"url": "https://www.mynewmenu.com/",
"price": null,
"priceMax": null,
"currency": null,
"listName": "MY NEW MENU"
}
The modified data fields will be returned in the response of the PATCH call.
Delete
To delete a Content List Item call this endpoint with the DELETE method:
.../api/menu-items/$id
In the response of your DELETE call you will retrieve the message "SUCCESS", when the Item was successfully deleted. You will no longer be able to call the deleted Content List Item.
How to assign a Content Item to a Content List?
To assign a Content List Item to a Content List you have to call the Content List via PATCH you want to assign items to:
Replace "$id" with the very Content List ID.
.../api/content-lists/$id
The body of the API call should contain the field "items" followed by an array containing the Item IDs you want to assign:
body
{
"contentList": {
"itemIds": [CONTENT_ITEM_ID1, CONTENT_ITEM_ID2, CONTENT_ITEM_ID3]
}
}
The updated data will be returned in the response of the PATCH call.
How to remove a Content List Item from a Content List?
To remove a Content List Item from a Content List you will have to call the Content List with the PATCH method you want to remove items from:
Replace "$id" with the very Content List ID.
.../api/content-lists/$id
The body of the API call should contain the field "items" followed by an array containing the Item IDs you want to keep. Empty the array in case you want to remove all Items:
body
{
"contentList": {
"itemIds": [CONTENT_ITEM_ID1]
}
}
The updated data will be returned in the response of the PATCH call.