Query data using GET requests

An API client is a prerequisite to making requests to the Caseware Cloud API. See Firm Settings - Integration for more information.

To query data using the Caseware Cloud API, you have the option of making GET requests. Use a GET request that requires a query parameter, and that returns a list of objects and allows advanced filtering. Results are returned as a page of objects in a response message.

Several pages of results may be available, but the page that is returned is the one you request using the page parameter. If you want the next page, you must make another request and increment the page number. Set the pageSize parameter to the number of objects you want to be returned in the response message.

Query syntax in GET requests

The query syntax for the search parameter in any GET request using the Caseware Cloud API is the following:

<fieldName><operator><fieldValue>

Leaving the query blank will return all the objects in the list.

<fieldName> is the name of the top-level field you wish to operate on.

Note: Not all fieldNames are valid. The field must be a primitive data type such as text, numbers, Booleans and dates. Complex data types such as collections or objects are not searchable.

Tip: Most of the fields (or query parameters) 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 entities, see the POST Create operation for entities:

Supported relational operators

<operator> can be any of the following:

• = (equal)
• < (less than)
• > (greater than)
• <> (not equal)

<fieldValue> can be any scalar value, that is, any single value:

For text, that is, any field whose data type is String, you must specify the value within single quotation marks:

fieldName='test'

For fields whose data type contains special characters such as ‘ or \ must use an escape character (\) in the search query:

fieldName='randomText\’s randomText'

For fields whose data type is number, specify the numeric value without quotation marks:

fieldName=123

For fields whose data type is Boolean, specify either true or false:

fieldName=true

For fields whose data type is date, the date must follow this ISO format:

fieldName='YYYY-MM-DDTHH:MM:SS:Z'

Supported logical operators

To help filter your results, you can combine two or more filter statements with the logical operators AND or OR. The AND operator takes precedence over OR. You must specify a space before and after the operator:

<fieldName><operator><fieldValue> AND <fieldName><operator><fieldValue>

Common use cases

See the examples of commonly used queries below. For descriptions of the API endpoints that you can use to query data in your firm, navigate to the Caseware Cloud SDK app with the instructions below.

To navigate to the Caseware Cloud SDK app:

1. In your browser, go to this URL:

• https://<region>.casewarecloud.com/<firm>/sdk

2. On the left, expand /caseware-cloud
3. In Search, type the GET operation whose description you want to view.

For example, if you wanted to get a list of entities, search for Get entities and select Get filtered list of entities in the results.

Query parameters that can be used in the URL of your request are described.

See the format of the request URL by selecting the drop-down of the endpoint to the right:

4. Refer to the response samples to the right for listings and descriptions of the data you can expect in the response.

Filter all entities using EntityNo

Endpoint you need for this example: GET /api/v1/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/v1/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/v1/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/v1/entities?search=metadata%5Beb367d1d-1634-416b-bcba-b748ec8146e4%5D%3D'\''2024-02-08'\''' \                  --header 'Authorization: Bearer OTY5OGVkMmUtZGY1NC0xYTE5LWU0YjYtNzkyNzVlY2I3Y2I0OmY0YWY5ZTZmLTA3YzQtZWU3Mi05MjczLWE1M2M5Y2Q3NTkwYjpmMWVlODEwMy1mMGYwLTRkNDItYmZmZC0zMWVjYTNkMDkyNTA=' 

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/v1/entities/{entityId}

Sample curl request

curl -X 'GET' \          'https://<region>.casewarecloud.com/<firm>/ms/caseware-cloud/api/v1/entities/4' \          -H 'accept: application/json' \          -H 'Authorization: Bearer MDdiZTQ1ZjUtZDY0NC1jZDI3LTZlZGQtOWYyZTFkYjQwNjY4OjEwNTUyYzFhLTU0MGItMTM3Ny0yYzA3LTRhYThhZjYwNGFlNTo1'

Filter users by email

Endpoint you need for this example: GET /api/v1/users

Sample curl request

curl -X 'GET' \          'https://<region>.casewarecloud.com/<firm>/ms/caseware-cloud/api/v1/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/v1/users/{userId}

Sample curl request

curl -X 'GET' \          'https://<region>.casewarecloud.com/<firm>/ms/caseware-cloud/api/v1/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/v1/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/v1/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/v1/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/v1/engagements?search=Confidential%3D%27true%27&itemType=WorkingPapersBundle&page=1&pageSize=50' \          -H 'accept: application/json' \          -H 'Authorization: Bearer NTliMDQ5ZjMtZmVkYi0xMDYwLWViYjItMTFkZTM1MjI2YTA2OjAxMTUzNzVkLWJhOTctOGQwMy0wNTY3LTVkODBhZDBjODgzMzo1'