Transition guide—Caseware Cloud API V1 to V2

API V1 has helped many customers automate workflows and ensure data in Caseware Cloud is up to date and accurate. However, as customer needs have evolved, we've heard feedback about limitations in V1, particularly around working with Business Units, and Tags. Based on this feedback, we’ve made thoughtful improvements in API V2 to better meet your needs and help you work more efficiently.

Key improvements in API V2 include:

• Compatibility with Business Units (BUs): Improved support for managing multiple business units within your organization.

• Tags management APIs: A new set of API endpoints for automating the management and assignment of tags for better organization and filtering.

• Developer-friendly SDK documentation: Clear and comprehensive SDK documentation designed to simplify integration and development.

API V2 will be launched alongside V1 to ensure backward compatibility, so your existing integrations will continue working during the transition. However, API V1 will be deprecated on October 30, 2025, giving you ample time to migrate to V2 without disruption.

We’ve designed these changes to have the biggest impact on improving your experience, based directly on the feedback we've received. This guide will walk you through the new features, answer common questions around different use cases and workflows, and help ensure a smooth and successful transition to API V2.

Frequently asked questions

General Information About API V2

Q1: What’s the difference between API V1 and V2?

A1: API V2 brings several key improvements over V1, including better support for Business Units (BUs), a more flexible tags management system, and a developer-friendly SDK with clearer documentation. These updates are designed to enhance efficiency, reduce the learning curve for developers, and introduce best practices for integration.

Q2: How does API V2 improve compatibility with Business Units (BUs)?

A2: In API V2, we’ve switched from using site-specific IDs to Globally Unique Identifiers (GUIDs). This ensures that data is uniquely identifiable across all Business Units (BUs), making it easier to manage and scale cross-BU integrations without conflicts. For organizations that don’t use BUs, GUIDs still provide a more robust and future-proof way to handle data, aligning with best practices and improving integration flexibility.

Q3: Will my current V1 integrations continue to work?

A3: Yes, even with the API V2 launch, Caseware continues to support V1 to ensure that your integrations are not disrupted.

Q4: Is there a timeline for when V1 will be deprecated?

A4: V1 will continue to be supported alongside V2, so you can keep using your current integrations for now. However, API V1 will be deprecated on October 30, 2025. We recommend transitioning to V2 before this date to ensure a smooth experience and to take full advantage of the new features and improvements.

Q5: Where can I find the documentation for the new V2 API features?

A5: Detailed documentation for API V2, including information on new endpoints and functionality, is available in our SDK documentation. This includes full descriptions of the new V2 endpoints, examples, and guidelines to help you transition from V1 to V2. The SDK documentation is organized to support both versions, so you can easily switch between the V1 and V2 endpoints based on your integration needs. Additionally, developers can download the Open API Specification directly from the SDK documentation, providing a structured format for integrating with the new V2 API.

Q6: Should I transition to V2 even if I am not using Business Units or Tags?

A6. Yes, we recommend transitioning to API V2, even if you’re not currently using Business Units or Tags. API V1 will eventually be deprecated, and once that happens, your existing integration will no longer be supported. Additionally, from a best practices standpoint, V2 introduces endpoints that use Globally Unique Identifiers (GUIDs), which offer more reliable and scalable solutions compared to non-unique keys. Making the transition will help future-proof your integration.

Q7: Are there any limitations or known issues with V2?

A7: While API V2 offers several improvements, there are a few limitations to be aware of. For example, the tags endpoints still use IDs rather than GUIDs, and we plan to address this in future releases. We also have plans to roll out minor updates to V2 on a regular cadence, incorporating feedback and adding new features. We also welcome your valuable feedback to help us prioritize improvements and ensure V2 meets your needs.

Q8: Will there be future upgrades to API V2?

A8: Yes, we will continue to release minor updates for API V2 on a regular cadence, incorporating new features, enhancements, and bug fixes. We recommend that developers visit the SDK documentation site periodically to stay updated on the latest changes and download the most current Open API Specifications. Please note that API V1 will no longer receive updates going forward, so we encourage transitioning to V2 to benefit from ongoing improvements and support.

Questions about the transition from V1 to V2

Q1: How to plan my transition from V1 to V2?

A1: You can transition from V1 to V2 in one of two ways: a staggered migration or a full switch.

• Phased Migration: Migrate different integrations (e.g., entities, staff, or groups) in separate phases, testing and implementing each one as you go.

• Full Switch: Update all the existing integrations at once but ensure thorough testing in a staging environment before fully switching.

Plan your transition

1. Review the V2 API documentation.

2. Choose your migration approach (phased or full).

3. Update integration code to make API calls to V2 endpoints.

4. Monitor the integration after switching.

This process ensures a smooth transition, regardless of your approach.

For detailed guidance on migrating specific use cases like entities, staff, and more, refer to the relevant sections below.

Q2: How should I handle ID references if I have a mapping database?

A2: If you are using a mapping database or middleware to store and reference CW object identifiers (such as entity IDs), we recommend updating your database to store both the CW ID and the corresponding CWGuid.

Before migrating to V2, you can use the V1 API to look up data by CW ID. In the response, you'll find the CWGuid for each object, which you can then use to update your reference table. This will ensure your system is ready for the transition to V2, where CWGuids will be the primary identifier.

Q3: Can I continue using V1 while transitioning to V2?

A3: Yes, you can continue using V1 while you migrate to V2. V1 and V2 integrations can work in parallel during this migration process. For example, you can run your entities integration on V2 while your staff integration still uses V1

Q4: Do I need to make any code changes to my current integrations?

A4: Yes, to take advantage of the new features in V2, you will need to update your API calls to the new V2 endpoints. The specifics of the changes required will depend on the endpoints you're currently using in V1.

Q5: How can I get support during the transition?

A5: Our support team is available to assist with any questions or challenges you encounter during the transition process.

Q6: Do I need to create new API clients for V2?

A6: No, you don’t need to create new API clients or keys for V2. Your existing V1 clients will continue to work seamlessly with V2. However, if you prefer, you can create new API clients specifically for V2. Once you’ve fully transitioned to V2, you can choose to delete the old V1 clients to ensure that V1 integrations are no longer in use.

Use-case-related questions for V2 migration

Entities

Q1. How do I create an entity in V2?

A1. For Business Units: To create an entity in a specific Business Unit, use the Create an entity in a business unit endpoint. Provide the Business Unit Shortname in the path parameters along with other required details in the request body. The API will create the entity in the specified Business Unit. The response will include a CWGuid, which should be used for any future operations on the entity, replacing the previous entity ID.

If you are not using Business Units, use the standard Create an entity endpoint, as you did in V1. This will create the entity in your cloud site, and here also the CWGuid should be used for subsequent operations.

Q2. How do I call the Get, Update, and Delete Entity endpoints in V2?

A2. In API V2, you must use CWGuids instead of entityIds to identify entities in the Get, Update, and Delete endpoints. Here's how it works:

1. When creating an entity or retrieving a list of entities (e.g., via the Search Filtered List endpoint), the response will include a CWGuid for each entity.

2. For subsequent operations (Get, Update, Delete), you must use the CWGuid provided in the response to reference the specific entity.

For Business Units (BU) firms, using CWGuids ensures that the entity is uniquely identified across all BUs, simplifying operations across multiple business units. The system will use the Guid to perform the requested operation (Get, Update, or Delete) across any Business Unit, ensuring seamless integration.

Users

Q3: How do I Create users in V2?

A3. Creating users in V2 is similar to V1, with an added feature for Business Unit firms. Here's how it works:

For all firms:

Create users in V2 using the Create a user endpoint, similar to V1. The process remains the same for most parameters.

For Business Unit (BU) firms:

BU firms can specify the Business Unit Shortnames to grant the user access to specific BUs. This simplifies managing user access across multiple business units. Here is a sample code with the list of BUs:

Response:

After creating the user, the response will include a CWGuid, which should be used for future operations (Get, Update, Delete) instead of the previous user ID.

Q4: How do I get the details of a user?

A4: In V2, to retrieve a user’s details, use the Get User Details endpoint and provide the user’s CWGuid in the path parameters. In V1, you would have used the user ID, but in V2, the Guid is required instead.

Q5: How do I get the list of Business Units a user has access to?

A5: To get the list of Business Units a user has access to, use the Get User Details endpoint and provide the user’s CWGuid. The response will include all the Business Units the user currently has access to.

Q6: How do I assign or unassign a staff user to different Business Units?

A6: You can assign or unassign a user from Business Units while creating or updating the user.

Create a user

Provide a list of Business Unit Shortnames in the request, specifying which Business Units the user should have access to.

Update user details

You can either assign the user to new Business Units or remove them from existing ones.

To assign the user to a BU:

Include all the Business Units the user should have access to, including the ones they already have access to.

To remove access from a BU:

Include only the BUs the user should retain access to. Any BU not in the list will be removed from the user's access.

Important:
If you don't include the Business Unit field in the update request, no changes will be made to the user’s BU access.

Groups

Q7: How do I create a group in V2?

A7: In V2, to create a group, use the Create Group endpoint and provide the necessary parameters in the request body. Unlike in V1, where you would have received a groupId, in V2, you will receive a CWGuid in the response, which should be used for any future operations on that specific group (such as Get, Update, or Delete).

Q8: How can I add users to a group?

A8: To add a user to a group in V2, use the “Update User Assignment to a Group” endpoint. In V2, instead of using the group ID and user IDs like in V1, you’ll need to provide the CWGuid of the group and the CWGuids of the users you want to add in the request.

By adding or removing users to groups and assigning those groups to specific Business Units, you can efficiently manage user access to different Business Units through their group memberships.

Q9: How do I get the list of Business Units a group has access to?

A9: To get the list of Business Units a group has access to, use the Get group details endpoint and provide the group’s CWGuid. The response will include all the Business Units the group currently has access to.

Q10. Can I assign Groups to Business Units using APIs?

A10. Yes, you can assign or unassign groups from Business Units during group creation or by using the update endpoint.

Create a group

Provide a list of Business Unit Shortnames in the request, specifying which Business Units the group should have access to.

Update group details

You can either assign the group to new Business Units or remove them from existing ones.

• To assign the group to a BU: Include all BUs the group should have access to, including previously assigned ones.

• To remove access from a BU: Include only the BUs the group should retain access to. Any BU not in the list will be removed from the group’s access.

Note: All users in the group will inherit access to the Business Units assigned to the group.

Roles and permissions

Q11: How do I assign roles to users and groups for entities and engagements?

A11. First, retrieve the list of available roles and their GUIDs using the Get Role List API.

Assign roles to a user

To assign roles to a user:

• Provide the CWGuid of the user, the roles to be assigned or removed, and the object details:

  • If the role is system-wide (applicable to the entire system), no additional details are required.

  • If the role is specific to an entity or engagement, provide the object type (e.g., entity or engagement) and the CWGuids of those objects.

Assign roles to a group

To assign roles to a group:

• Provide the CWGuid of the group, the roles (GUIDs) to be assigned or removed, and the object details:

  • If the role is system-wide, no additional parameters are needed.

  • If the role is specific to an entity or engagement, provide the object type and the relevant CWGuids for those objects.

Note for Business Unit (BU) firms: Using CWGuids for role assignments improves efficiency for BU firms by enabling seamless management of role assignments across entities and engagements across different Business Units.

Engagements

Q12: Have there been any changes to the Engagement APIs?

A12: The Get Engagement APIs have not changed from V1 to V2 and continue to function as they did previously. The request parameters still use IDs, just like in V1. However, if you have existing integrations for Engagements using V1, you will still need to migrate to V2 to ensure continued support as V1 will eventually be deprecated.

BU-specific question

Q13: What is a BU Shortname?

A13: Each Business Unit (BU) has several attributes: a URL, a BU Name, a Display Name, and a BU Shortname. While the BU Name and Display Name can be non-unique, the BU Shortname is globally unique, which is why it is used as the identifier for BUs.

The BU Shortname is derived from the BU’s URL suffix and is part of the caseware domain. It can be easily retrieved from the BU URL.

BU attributes described

BU URL (non-editable)	Name	Display Label	Shortname
ca.caseware.ca/test-site	Test Site	Office-NY	test-site
us.caseware.com/company-1-a-b	Company 1	Office 1 (A to B)	company-1-a-b

Important Note: Currently, there is no API available to retrieve the list of BUs and their Shortnames. You can view the list of all BUs by logging into the cloud site and navigating to Settings | Business Units.

Q14: Which BU should I use to call APIs for managing other BUs?

A14: We recommend using the Admin Business Unit (BU) URL to set up your API integrations and manage data across other BUs. The Admin BU serves as the central hub for managing multiple BUs, in line with how we suggest handling administrative tasks through the UI.

Just as we advise admins to manage staff, groups, and other objects from the Admin BU in the user interface, using the Admin BU for your API calls ensures consistency and simplifies administration. This approach helps you maintain better control and visibility when managing data across multiple BUs.