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:
https://<region>.casewarecloud.com/<firm>/sdk/caseware-cloud#tag/Entities/operation/createEntity
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>
Operator | Description | Example |
---|---|---|
AND | Join two or more filter statements by the AND operator. | countryCode='CA' AND modifyDate>'2022-01-01' |
OR | Join two or more filter statements by the OR operator. | countryCode='US' OR countryCode='CA' |
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:
- In your browser, go to this URL:
https://<region>.casewarecloud.com/<firm>/sdk
- On the left, expand /caseware-cloud
- 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:
- 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 pad input with empty spaces. For example if the EntityNo is “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:
https://<region>.casewarecloud.com/<firm>/sdk/caseware-cloud#tag/Entities
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 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:
https://<region>.casewarecloud.com/<firm>/sdk/caseware-cloud#tag/Users/operation/createUser
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:
https://<region>.casewarecloud.com/<firm>/sdk/caseware-cloud#tag/Role-Assignment/operation/updateUserRoles
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
Field | Data type | Description |
---|---|---|
Confidential | Boolean | Whether the engagement is confidential. Default: |
type | String | Specifies the type of bundle:
Generally an object that represents a Working Papers engagement.
Generally an object that represents a Cloud engagement but can be used in any number of ways by custom apps:
|
page | Integer | Default: 1 Specify the page requested, starting at page 1. |
pageSize | Integer [1..50] | Default: 50 Specify the number of engagements listed per page. |
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'