Console Banner API
The Console Banner feature allows platform and product admins to create and manage banners that inform the app users about important notifications, scheduled maintenance, or downtimes directly within the console. Once configured, banners display in real-time, ensuring that all relevant users are informed. Banner can be created for the different level types:
- Stack Level: For core platform-wide activities (e.g., system-wide maintenance).
- Tenant Level: For tenant-specific updates (e.g., customer-specific reminders).
- Solution Level: For specific solutions like DispatchOne or TMS (e.g., scheduled downtime for a particular solution).
Info: To learn more about the usage and implementation of these banners, refer to the JSON Examples section at the bottom of this page.
To access the banner feature, platform/product admins must have the appropriate permissions. If you do not have admin access, reach out to us by visiting the developer portal at https://portal.os1.delhivery.com/ and click the Contact Us button to request access.
Once you have admin access, follow the steps below to start using the Banner API.
- User Role: Ensure you have the Product Admin role to access the banner creation API.
- API Access: All Banner API requests require a valid access token to ensure only authorized users (product admins and support users) can create, update, or delete banners. Refer to the Get Access Token section and get your access token.
The Banner API allows product admins to create, update, and delete banners for their applications. The below section outlines how to use the API, including the endpoints, request parameters, and sample example code snippets.
This table outlines the parameters used in the Banner API requests, including headers, query parameters, and path parameters.
Parameter | Data Type | Description | Required |
|---|---|---|---|
x-developerplatform-access | string | Access token for authentication. | Yes |
levelType | string | Type of the level at which the banner is applicable (e.g., stack). | Yes |
solutionId | string | ID of the solution. | No |
bannerId | string | Universal Unique identifier for the banner (used for updating and deleting) | Yes |
activityDate | string | Date of the banner display (in YYYY-MM-DD format). | Yes |
activeFromTime | string | Start time for banner display (ISO 8601 format) | Yes |
activeUntilTime | string | End time for banner display (ISO 8601 format) | Yes |
activityStartTime | string | The exact start time of the activity that the banner is notifying users about (in ISO 8601 format). | Yes |
activityEndTime | string | The exact end time of the activity that the banner is notifying users about (in ISO 8601 format). | Yes |
title | string | The title of the banner. | Yes |
message | string | The main message of the banner. | Yes |
data | Object | Key-value pairs for dynamic content in message. | Yes |
Register a new banner using the Banner API. Make sure all required fields are valid and that you have the necessary support access with the provided access token.
To register a banner, send a POST request using the endpoint below:
When making requests to the Banner API, include the following header and parameters:
All requests to the Banner API must include the following header:
X-developerplatform-access: This is the access token used for authentication.
Parameter | Description | Required |
|---|---|---|
x-developer platform-access | Access token for authentication. (mandatory). | Yes |
orgId | Unique identifier of the user’s organization. | Yes |
Retrieve a list of banners for a specific level using the GET method. This allows you to fetch active banners for a particular level on the current day.
To get the specific bannerID, send the GET request using the following endpoint:
Parameter | Description | |
|---|---|---|
x-developer platform-access | Access token for authentication. (header). | Yes |
levelType | Specifies the type of level for which banners are requested. Must be one of: stack, tenant, or solution. | Ye |
- levelType: Type of the level for which banners are requested.
In this example, levelType is the query parameter being used to filter the results returned by the API.
Retrieve the details of a specific banner by providing its unique bannerId using the GET method.
Parameter | Description | Required |
|---|---|---|
x-developer platform-access | Access token for authentication. (mandatory). | Yes |
bannerId | Unique identifier for a specific banner.
| Yes |
Update an existing banner using the PATCH method. This allows you to modify various properties of the banner such as title, content, active times, etc.
Note: Banner’s levelType and levelIds field cannot be updated. If these attributes need changes, you must delete the banner and create a new one.
To update a banner, send the PATCH request using the following endpoint:
Parameter | Description | Required |
|---|---|---|
x-developer platform-access | Access token for authentication. (mandatory). | Yes |
bannerId | Unique identifier for a specific banner.
| Yes |
orgID | Unique identifier for the user’s organization. | Yes |
To delete a banner, send a DELETE request to the appropriate API endpoint with the bannerId of the banner you wish to remove.
Upon successful deletion, the API will delete the specific banner.
This banner notifies users of a planned maintenance event that affects the core services related to the overall system, applicable to all users in the stack.
This banner serves as a payment reminder for a specific tenant to ensure only the relevant users are notified.
This banner is specifically meant for users of the DispatchOne solution, providing them information about when the service will be unavailable due to maintenance.