About the Cherwell® REST API

The REST API Discovery Tool provides comprehensive API documentation with an intuitive user interface that enables you to discover and test operations using your CSM data. Testing is available for all authentication modes, except SAML.

REST API Revision History

CSM Version Changes


Modified the Add/Edit Canonical Definitions dialog box to be read-only to allow canonical definitions to be maintained and provided only by Cherwell.


  • Added operations for Business Object Lifecycle, including an operation for transitioning a Business Object record.
  • Added v2 of the storedsearches operation to provide greater flexibility for third-party reporting integrations.
  • Added optional "locale" and "lang" parameters to the Swagger UI, allowing the culture to be supplied for API requests from the Swagger UI.
  • Minor bug fixes.


Minor bug fixes.


  • Added the ability to get the status of an Approval Business Object.
  • Added the ability to return an Approval Business Object using the Approval record ID.
  • Added the ability to get all waiting Approvals for the current user.
  • Added the ability to get all pending Approvals that were created by the current user.


  • Added the ability to export all rows of data for Get Results of a Saved Search.
  • Introduced the ability to execute a One-Step™ Action or get a list of available One-Step Actions.


  • Added the ability to connect to third-party tools to retrieve data from CSM using the Cherwell REST API. Configure the REST API by creating a new API Client ID (or use an existing one) to automatically generate a Client Key. The Client Key is used to generate an access token for the REST API.
  • Added authentication to the Service Monitor using the Cherwell REST API. The following configuration keys were added into the web.config for the REST API: UseSAMLADFSRedirect and IDPisADFS.


  • Added the Canonical REST API Mapping Wizard to simplify the process of mapping a canonical Business Object Schema to your custom Business Object Schema.
  • Added operation for retrieving mapped Activity types for Audit, Communication, and Notes.
  • Removed installed documentation. Users are now directed to the version-specific REST API documentation on https://help.cherwell.com.


  • Added Named Object Operations to perform basic functions against Business Objects via the Cherwell REST API. Named Object Operations include nine API operations with simplified URL paths to provide user-friendly, programmatic access to basic CSM functions. You may want to use the Named Object Operations if you are new to the Cherwell REST API or you do not have extensive programming experience. Functions that you can perform using the Named Object Operation include:
    • Delete Business Object
    • Get Business Object
    • Update Business Object
    • Create Business Object
    • Get Business Object Field List
    • Delete Business Object Comment
    • Get Business Object Comments
    • Create Business Object Comment
    • Search for Business Object
  • Added the CherwellCanonical REST API. The CherwellCanonical REST API enables customers and partners to create reusable integrations between third-party software and customized CSM systems by providing a fixed schema to map out-of-the-box Business Objects to customized Business Objects.


Minor bug fixes.


  • Added operations for:
    • Removing Customers from Workgroups.
    • Saving Workgroup Members and Team Members.
    • Getting Teams using the Team ID.
    • Deleting Teams; removing Users from Teams.
    • Getting Users using the Record ID; getting a list of all Users.
    • Adding items to Queues; checking items in to Queues.
    • Removing items from Queues; checking items out of Queues.
    • Getting Queues using Scope, Scope Owner, and Folder.
    • Getting Stored Values using Scope, Scope Owner, and Folder.
    • Creating, updating, and deleting gallery images.
    • Getting gallery images using Scope, Scope Owner, and Folder.
    • Setting the culture for the current User.
  • Added multiple Powershell examples to the documentation. Expanded information about using OAuth2 and SAML protocols with the REST API. Added SAML client examples with and without a final URI query string. Added practice exercises for using the REST API Discovery Tool. Reorganized the Operations List to match Swagger by adding new categories for Team Operations, User Operations, and Queue Operations. Added instructions for re-generating Swagger code with the new categories after upgrading.


  • Added operations for:
    • Creating and updating Teams and Workgroups.
    • Adding a batch of Users to Teams.
    • Getting a Business Object record based on its associated scan code.
  • Added support for HTML content in Business Object fields.


Added multiple C# examples to the documentation.


  • Added v2 of most Security operations to change Error property to ErrorMessage.
  • Added v3 of getuserbyloginid to change Error property to ErrorMessage.


  • Added operations for:
    • Executing Quick Searches.
    • Running Saved Queries that have Prompts.
    • Adding Users to Teams; removing users from Teams.
    • Getting Mobile Forms.
  • Improved Landing Page that includes parameter glossary and Swagger code-gen instructions.


  • Added v2 of getuserbyloginid.
  • Changed API version to match CSM version.


  • Support for Windows, LDAP, and SAML authentication.
  • Attachment management and built-in image retrieval operations added.


Initial Release.