Common use cases

In the Caseware Cloud API, many common use cases involve using the search query parameter in GET requests to filter for the objects you want to retrieve. See the examples of common use cases below. For query syntax, see Query syntax in GET requests.

Filter by GUID

CWGuid is a globally unique identifier to identify objects across business units. It is available as a path parameter for retrievable objects in several endpoints of V2 of Cloud API. You can retrieve the CWGuid after creating an object, such as an Entity or Person, or by retrieving a list of objects. You can also retrieve the CWGuid from search results using a different field. For example, if you are searching entities, search by name or number.

Retrieve the CWGuid from search results

Where you do not know the CWGuid of the object you want to retrieve, use a GET filtered list request to search on a different field. In this example, the search query parameter is used to search for an Entity object whose Name is `Canada Tiny Homes Ltd.`

Before URL encoding the example below looks like so:

https://{region}.casewarecloud.com/{firm}/ms/caseware-cloud/api/v2/entities?search=Name = 'Canada Tiny Homes Ltd.'

Endpoint you need for this example: GET /api/v2/entities/

Sample curl request

                 curl --location 'https://{region}.casewarecloud.com/{firm}/ms/caseware-cloud/api/v2/entities?search%3DName%20%3D%20%27Canada%20Tiny%20Homes%20Ltd.%27=null' \                 --header 'Authorization: Bearer ZjlhMDUxMTUtZTU1Ny00MWU5LWY1MzQtZDNkYWJlOTU3OTljOjZlYzExMTZlLTdlOWEtOTQ5Mi01ODFkLWI3ZWJmYWQ3ZDU2YjpiYTIxYWRhOC05NzdlLTRkZjgtYWY0Ny03ZTQ3M2IxNDMzNzg='

Retrieve an object using its CWGuid

Where you do know the CWGuid of the object you want to retrieve, there are endpoints where cwGuid is a path parameter.

Before URL encoding the example below looks like so:

https://{region}.casewarecloud.com/{firm}/ms/caseware-cloud/api/v2/entities/208e79df-851f-4be7-93f6-25d54fccb6b2

Endpoint you need for this example: GET /api/v2/entities/{cwGuid}

Sample curl request

curl --location 'https://{region}.casewarecloud.com/{firm}/ms/caseware-cloud/api/{version-number}/entities/208e79df-851f-4be7-93f6-25d54fccb6b2 ' \         --header 'Authorization: Bearer NTVjY2EyNjEtYTJhZi05NzNhLWRiMWMtZDFiZWVkM2M0YmJhOmNlMTYxMDE1LWJlMGQtN2I2ZS0yYzFlLTQyNDA0YjNkMjJiNTpiYTIxYWRhOC05NzdlLTRkZjgtYWY0Ny03ZTQ3M2IxNDMzNzg='

Filter all entities using EntityNo

Endpoint you need for this example: GET /api/{version-number}/entities

Values specified for EntityNo must have 10 characters. If an EntityNo does not have 10 characters, then you must right-align input and pad it with empty spaces. For example where EntityNo is set to A2 then your query must be EntityNo='        A2'. Changes to the API query are in progress to ensure that developers no longer need to pad the input with empty spaces. This documentation will be updated when available.

Tip: Most of the fields that can be used to form queries (specified as the value of the search query parameter) are described in the response samples for the object you are querying. For example, if you are querying entities, the fields that can be queried are listed in the code 200 response sample:

Sample curl request

curl -X 'GET' \                 'https://{region}.casewarecloud.com/{firm}/ms/caseware-cloud/api/{version-number}/entities?search=EntityNo%3D%271234567890%27&page=1&pageSize=50' \                 -H 'accept: application/json' \                 -H 'Authorization: Bearer YmFjMGU4MDgtZmFjMC1kMmQzLTZkNjEtZGRmNjdiNWQzMTY5OjczOGYyZGU1LTc2YTctMzRjNC00NzhkLWQ3NGQ1ZTY5MTRhZDo1'

Filter by entity metadata

Endpoint you need for this example: GET /api/{version-number}/entities

You can set the search query parameter to filter entities by their custom entity metadata. The format for the entity metadata search query changes according to where it was created:

Custom entity properties created in firm settings

Recall the syntax for queries using the search query parameter is the following:

<fieldName><operator><fieldValue>

Replace <fieldName> with metadata[{Name}]

• Where {Name} is the GUID that is generated by Caseware Cloud when you create a custom entity property in Settings | Customization | Custom Entity Properties. See Retrieve the GUID for a custom entity property created in firm settings for more information.

Retrieve the GUID for a custom entity property created in firm settings

1. Log in to your Caseware Cloud firm.
2. Display the developer tools in your browser. For example, in Google Chrome, type Ctrl + Shift + C.
3. From the Cloud menu (), select Settings | Customization | Custom Entity Properties. See Custom entity properties for more information.
4. Select an existing custom entity field or add one.
5. Select Network and then the Fetch/XHR filter.
6. Locate the GetEntityMetadataGroupAndDisplay API call and select the Response filter to view the response message in JSON.
7. Locate the Name attribute. Its value is a GUID. In the format example above, replace Name with this GUID. See the example below.

Sample curl request

curl --request GET \                 --url 'https://{region}.casewarecloud.com/{firm}/ms/caseware-cloud/api/{version-number}/entities?search=metadata%5Beb367d1d-1634-416b-bcba-b748ec8146e4%5D%3D'\''2024-02-08'\''' \                 --header 'Authorization: Bearer OTY5OGVkMmUtZGY1NC0xYTE5LWU0YjYtNzkyNzVlY2I3Y2I0OmY0YWY5ZTZmLTA3YzQtZWU3Mi05MjczLWE1M2M5Y2Q3NTkwYjpmMWVlODEwMy1mMGYwLTRkNDItYmZmZC0zMWVjYTNkMDkyNTA=' 

Obtain the context string to update entity metadata

The following method applies where a custom entity field has been created in Caseware Cloud:

1. Log in to your Caseware Cloud firm.
2. From the Cloud menu (), select Settings | Customization | Custom Entity Properties. See Custom entity properties for more information.
3. Select an existing custom entity field or add one.
4. Select Network and then the Fetch/XHR filter.
5. Locate the GetEntityMetadataGroupAndDisplay API call and select the Response filter to view the response message in JSON.
6. Identify the value of Context and use it in the PUT /entities/{entityId}/metadata/{context} request.

Sample response for GetEntityMetadataGroupAndDisplay

{ 						"d": { 						"result": [ 						{ 						"DefaultDisplayName": "Custom field", 						"Order": 1, 						"EntityMetadataDisplayList": [ 						{ 						"Type": "Checkbox", 						"MultipleChoiceItems": [], 						"Context": "dfc67a64-2797-4d92-ac0a-47111594f61f", 						"Name": "f5c4f531-f947-40c2-9ce4-05a09c6b143d", 						"DefaultDisplayName": "Check box", 						"Order": 1, 						"MultiValueByDate": false, 						"IsRequired": false 						} 						], 						"EntityType": "Client" 						} 						], 						"error": [], 						"Errors": [], 						"warning": [] 						} 						}

Filter entities by entityId

In Caseware Cloud, you can obtain the entity ID of the entity you are currently in from your firm URL. In the example below, entityId = 4:

Endpoint you need for this example: GET /api/{version-number}/entities/{entityId}

Sample curl request

curl -X 'GET' \         'https://{region}.casewarecloud.com/{firm}/ms/caseware-cloud/api/{version-number}/entities/4' \         -H 'accept: application/json' \         -H 'Authorization: Bearer MDdiZTQ1ZjUtZDY0NC1jZDI3LTZlZGQtOWYyZTFkYjQwNjY4OjEwNTUyYzFhLTU0MGItMTM3Ny0yYzA3LTRhYThhZjYwNGFlNTo1'

Filter users by email

Endpoint you need for this example: GET /api/{version-number}/users

Sample curl request

curl -X 'GET' \         'https://{region}.casewarecloud.com/{firm}/ms/caseware-cloud/api/{version-number}/users?search=Email%3D%27domain.admin%40yourfirm.com%27&page=1&pageSize=50' \         -H 'accept: application/json' \         -H 'Authorization: Bearer YzZhZGUxNjItZDQ1MS01MjYyLWUyZjEtYjgwYWYxNTdhYmEwOmRjNmI3YWRhLTAxM2ItMmMyNi1iZjhhLTY4ODEyZjc0OTI3ZTo1'

Tip: Most of the fields that can be used to form queries (specified as the value of the search query parameter) are described in the request body schema in the POST Create operation for the object you are querying. For example, if you are querying users, see the POST Create operation for users:

Filter users by ID

Endpoint you need for this example: GET /api/{version-number}/users/{userId}

Sample curl request

curl -X 'GET' \         'https://<region>.casewarecloud.com/<firm>/ms/caseware-cloud/api/{version-number}/users/2' \         -H 'accept: application/json' \         -H 'Authorization: Bearer YWJhZDE3MmQtMGIyOC1hZWVlLWZjM2EtY2VmZjBlYjUwZWNiOjJkODdiODY1LTY0NTUtNjgwNS0xMDQ5LWFjZWMzMWI5ZTZkNTo1'

Filter roles based on name (of the role)

Endpoint you need for this example: GET /api/{version-number}/roles

Tip: Most of the fields (or query parameters) that can be used to form queries in GET requests are described in the request body schema in the POST or PATCH operation for the object you are querying. For example, if you are querying roles, see the PATCH Update operation for role assignments:

Sample curl request

curl -X 'GET' \         'https://<region>.casewarecloud.com/<firm>/ms/caseware-cloud/api/{version-number}/roles?search=Name%3D%27Contact%20-%20Entity%20Access%27&page=1&pageSize=50' \         -H 'accept: application/json' \         -H 'Authorization: Bearer YWJhZDE3MmQtMGIyOC1hZWVlLWZjM2EtY2VmZjBlYjUwZWNiOjJkODdiODY1LTY0NTUtNjgwNS0xMDQ5LWFjZWMzMWI5ZTZkNTo1'

Filter all confidential Working Papers bundles

Endpoint you need for this example: GET /api/{version-number}/engagements

Fields used to create the query in the sample request

Sample curl request

curl -X 'GET' \         'https://{region}.casewarecloud.com/{firm}/ms/caseware-cloud/api/{version-number}/engagements?search=Confidential%3D%27true%27&itemType=WorkingPapersBundle&page=1&pageSize=50' \         -H 'accept: application/json' \         -H 'Authorization: Bearer NTliMDQ5ZjMtZmVkYi0xMDYwLWViYjItMTFkZTM1MjI2YTA2OjAxMTUzNzVkLWJhOTctOGQwMy0wNTY3LTVkODBhZDBjODgzMzo1'