> For the complete documentation index, see [llms.txt](https://docs.platform.softwareone.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.platform.softwareone.com/developer-resources/rest-api/notifications-api.md). # Notifications API The **Notifications API** allows you to manage and deliver notifications within the SoftwareOne Marketplace Platform. With this API, you can: * Create and retrieve notification batches (emails) sent to specific categories and contacts. You can also retrieve attachments associated with those messages. * Create and manage notification categories (such as orders, subscriptions, and more). * Create and manage contacts. Contacts are the recipients who receive notifications. * Retrieve sent messages and delivery information. ## Before you start Review the shared API docs before you work with notifications resources. * [Authentication](/developer-resources/rest-api.md) * [URL structure](/developer-resources/api-usage-and-reference/url-structure.md) * [Error handling](/developer-resources/api-usage-and-reference/errors-handling.md) ## Core concepts The Notifications API is built around the following core resources: * **Batch** – Represents an email being sent to a specific category and multiple contacts. * **Category** – Represents a logical grouping of notifications (for example, orders or subscriptions). Categories help organize and control notification types. * **Contact** – Represents a contact who receives the notifications. * **Message** – Represents an individual notification sent to a contact, including delivery details and status. * **Subscriber** – Handles the configuration of notifications for accounts. It's the connection between an account and a notification category. ## Browse collections The API is organized into collections, each containing a set of operations. Access to these operations varies by role, depending on whether you are a `client`, `vendor`, or `operations` user. Use the following links to jump to the collection you need: * [Batches](#batches) * [Categories](#categories) * [Contacts](#contacts) * [Footer](#footer) * [Message](#message) * [Subscriber](#subscriber) * [Template](#template) * [Template Variant](#template-variant) ### Batches
View Batches operations | Operation | Method | Description | Access | | ------------------------------------------------------------------------------------------------------- | ------ | ------------------------ | ------------------- | | [Create batch](/developer-resources/rest-api/notifications-api/batches/create-batch.md) | POST | Creates a new batch. | vendor, ops | | [List batches](/developer-resources/rest-api/notifications-api/batches/list-batches.md) | GET | Gets a list of batches. | vendor, ops | | [Get batch by id](/developer-resources/rest-api/notifications-api/batches/get-batch.md) | GET | Gets batch details. | vendor, ops | | [Get batch attachment](/developer-resources/rest-api/notifications-api/batches/get-batch-attachment.md) | GET | Gets a batch attachment. | vendor, client, ops |
### Categories
View Categories operations | Operation | Method | Description | Access | | ------------------------------------------------------------------------------------------------------ | ------ | --------------------------------------- | ---------------------------- | | [Create category](/developer-resources/rest-api/notifications-api/categories/create-category.md) | POST | Creates a new notification category. | ops | | [List categories](/developer-resources/rest-api/notifications-api/categories/list-categories.md) | GET | Gets a list of notification categories. | vendor, client, ops, contact | | [Get category by id](/developer-resources/rest-api/notifications-api/categories/get-category.md) | GET | Gets notification category details. | vendor, client, ops, contact | | [Update category](/developer-resources/rest-api/notifications-api/categories/update-category.md) | PUT | Updates a notification category. | ops | | [Delete category](/developer-resources/rest-api/notifications-api/categories/delete-category.md) | DELETE | Deletes a notification category. | ops | | [Publish category](/developer-resources/rest-api/notifications-api/categories/publish-category.md) | POST | Publishes a notification category. | ops | | [Unpublish category](/developer-resources/rest-api/notifications-api/categories/unpublish-category.md) | POST | Unpublishes a notification category. | ops |
### Contacts
View Contacts operations | Operation | Method | Description | Access | | ---------------------------------------------------------------------------------------------- | ------ | ------------------------ | ---------------------------- | | [Create contact](/developer-resources/rest-api/notifications-api/contacts/create-contact.md) | POST | Creates a new contact. | ops | | [List contacts](/developer-resources/rest-api/notifications-api/contacts/list-contacts.md) | GET | Gets a list of contacts. | vendor, client, ops, contact | | [Get contact by id](/developer-resources/rest-api/notifications-api/contacts/get-contact.md) | GET | Gets contact details. | vendor, client, ops, contact | | [Update contact](/developer-resources/rest-api/notifications-api/contacts/update-contact.md) | PUT | Updates a contact. | vendor, client, ops, contact | | [Delete contact](/developer-resources/rest-api/notifications-api/contacts/delete-contact.md) | DELETE | Deletes a contact. | ops | | [Block contact](/developer-resources/rest-api/notifications-api/contacts/block-contact.md) | POST | Blocks a contact. | ops | | [Unblock contact](/developer-resources/rest-api/notifications-api/contacts/unblock-contact.md) | POST | Unblocks a contact. | ops |
### Footer
View Footer operations | Capability | Method | Description | Access | | ---------------------------------------------------------------------------------------- | ------ | ------------------------------------------------- | ------ | | [Create footer](/developer-resources/rest-api/notifications-api/footer/create-footer.md) | POST | Creates a new footer. | ops | | [Get footer](/developer-resources/rest-api/notifications-api/footer/get-footer.md) | GET | Retrieves a footer by id. | ops | | [List footer](/developer-resources/rest-api/notifications-api/footer/list-footers.md) | GET | Retrieves all footers. | ops | | [Update footer](/developer-resources/rest-api/notifications-api/footer/update-footer.md) | PUT | Updates the footer content or sets it as default. | ops | | [Delete footer](/developer-resources/rest-api/notifications-api/footer/delete-footer.md) | DELETE | Permanently removes the footer. | ops |
### Message
View Message operations | Capability | Method | Description | Access | | ------------------------------------------------------------------------------------------ | ------ | ----------------------- | ------------------- | | [List messages](/developer-resources/rest-api/notifications-api/messages/list-messages.md) | GET | Retrieves all messages. | vendor, client, ops | | [Get message](/developer-resources/rest-api/notifications-api/messages/get-message.md) | GET | Get a message by id. | vendor, client, ops |
### Subscriber
View Subscriber operations | Operation | Method | Description | Access | | ----------------------------------------------------------------------------------------------------------------------------------------------- | ------ | ---------------------------------------------------------------------------------------- | ------------------- | | [List subscribers](/developer-resources/rest-api/notifications-api/subscribers/list-subscribers.md) | GET | Gets a list of subscribers. | vendor, client, ops | | [Get subscriber by id](/developer-resources/rest-api/notifications-api/subscribers/get-subscriber.md) | GET | Gets subscriber details. | vendor, client, ops | | [Update subscriber](/developer-resources/rest-api/notifications-api/subscribers/update-subscriber.md) | PUT | Modifies recipients of a given configuration. | vendor, client, ops | | [Disable subscriber](/developer-resources/rest-api/notifications-api/subscribers/disable-subscriber.md) | POST | Disables the category for the account. | vendor, client, ops | | [Enable subscriber](/developer-resources/rest-api/notifications-api/subscribers/enable-subscriber.md) | POST | Enables the category for the account. | vendor, client, ops | | [Get contacts in account and category](/developer-resources/rest-api/notifications-api/subscribers/get-contacts-within-account-and-category.md) | GET | Returns contacts configured to receive notifications for the given account and category. | vendor, ops |
### Template
View Template operations | Capability | Method | Description | Access | | -------------------------------------------------------------------------------------------------- | ------ | ---------------------------------------------------------------------- | ----------- | | [List templates](/developer-resources/rest-api/notifications-api/template/list-templates.md) | GET | Gets a list of template. | vendor, ops | | [Create template](/developer-resources/rest-api/notifications-api/template/create-template.md) | POST | Creates a new template. | vendor, ops | | [Get template](/developer-resources/rest-api/notifications-api/template/get-template.md) | GET | Gets template details. | vendor, ops | | [Update template](/developer-resources/rest-api/notifications-api/template/update-template.md) | PUT | Updates template properties. Only speciic fields can be modified. | vendor, ops | | [Delete template](/developer-resources/rest-api/notifications-api/template/delete-template.md) | DELETE | Permanently removes the template and all its language variants | vendor, ops | | [Activate template](/developer-resources/rest-api/notifications-api/template/activate-template.md) | POST | Activates the template, making it available for sending notifications. | vendor, ops |
### Template Variant
View Template Variant operations | Capability | Method | Description | Access | | ----------------------- | ------ | ------------------------------------------------------------------------------------------------------ | ----------- | | List template variant | GET | Gets a list of template variants | vendor, ops | | Create template variant | POST | Adds a new language variant to the template with subject and body content for the specified language. | vendor, ops | | Get template variant | GET | Gets a template variant. | vendor, ops | | Update template variant | PUT | Updates the subject and/or body content of the language variant. Only specific fields can be modified. | vendor, ops | | Delete template variant | DELETE | Permanently removes the language variant from the template. | vendor, ops |
--- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.platform.softwareone.com/developer-resources/rest-api/notifications-api.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.