Cases are the core objects that store the majority of data throughout the system. Other objects, such as subjects, cannot exist on their own without a case.
Returns a collection of case records, optionally filtered by the available request parameters.
Available Request Parameters:
|id||integer||no||ID of the case.|
|client||integer||no||ID of the root (parent) client the case is assigned to.|
|location||integer||no||ID of the client location the case is assigned to.|
|case_region||integer||no||ID of the case region the case is assigned to.|
|case_status||integer||no||ID of the case status the case currently resides in.|
|created_from||date||no||Created on or after the date, as determined by the user. (Alias: From).|
|created_to||date||no||Created on or before the date, as determined by the user. (Alias: To).|
|created_from_system||timestamp||no||Created on or after the date, as determined by the system.|
|created_to_system||timestamp||no||Created on or before the date, as determined by the system.|
|due_from||date||no||Due on or after the date.|
|due_to||date||no||Due on or before the date.|
|updated_from||timestamp||no||Updated on or after the date.|
|updated_to||timestamp||no||Updated on or before the date.|
|is_request||boolean||no||When true, only return case requests. When false, only return cases.|
|primary_contact||integer||no||ID of the primary client contact assigned to the case.|
|primary_investigator||integer||no||ID of the primary investigator assigned to the case.|
|primary_manager||integer||no||ID of the primary case manager assigned to the case.|
|primary_salesperson||integer||no||ID of the primary salesperson assigned to the case.|
|primary_subject||integer||no||ID of the primary subject assigned to the case.|
|reference_value_1||string||no||Value of the 1st reference on the case (e.g. a claim number). The corresponding reference label is defined in the case type configuration.|
|reference_value_2||string||no||Value of the 2nd reference on the case (if in use). The corresponding reference label is defined in the case type configuration.|
|reference_value_3||string||no||Value of the 3rd reference on the case (if in use). The corresponding reference label is defined in the case type configuration.|
|series_number||integer||no||The series number, as indicated by the case number. Related/Re-Opened cases will contain the same series number.|
|series_instance||integer||no||The series instance, as indicated by the case number. Each time a case is re-opened the series instance is incremented (e.g. 01, 02, 03).|
|case_number||string||no||The fully formatted Trackops case number, as it appears in your system.|
Note: All timestamp parameters are queried and returned in UTC.
Getting a Case
Returns a single case record, based on the numeric ID.
Creating a Case
Creates a new case based on the given criteria. Upon success, returns a case object. See the example request at the bottom of this section for a better idea of how a fully formed request should look.
|case_type_id||integer||yes||ID of the case type. See Case Types|
|client_id||integer||yes||ID of the client location. See Client Locations|
|primary_contact_id||integer||yes||ID of the client contact. See Client Contacts|
|case_region_id||integer||yes||ID of the case region. See Case Regions|
|company_location_id||integer||no||ID of the internal company location|
|referral_source_id||integer||no||ID of the referral source for this case.|
|reference_value_1||string||no||Value of Reference No. 1 (Case Type Config)|
|reference_value_2||string||no||Value of Reference No. 2 (Case Type Config)|
|reference_value_3||string||no||Value of Reference No. 3 (Case Type Config)|
|case_location||string||no||Geographic location of case (e.g. Denver, CO)|
|budget_money||decimal||no||The initial case budget in money (e.g. 1000)|
|budget_hours||decimal||no||The initial case budget in hours (e.g. 8)|
|notes||string||no||Public notes and instructions for this case|
|scheduling_notes||string||no||Specific criteria to be used during scheduling|
|admin_notes||string||no||Private notes, only visible by staff|
|case_services_list||array||no||List of services to perform (See Case Services)|
|case_flags_list||array||no||List of case flags to apply (See Case Flags)|
|custom_fields||collection||no||Custom field objects to create (see below)|
|subjects||collection||no||Subject objects to create (see below)|
Working with Custom Fields
Custom fields can be added to both cases and subjects, and are are always sent as a collection underneath the custom_fields array. Each custom field consists of two parts, the id and the value. The id represents the internal ID related to that field, and the value is the actual data to be populated for that field. It is important to note that custom field values must be formatted specific to the type of field that is being submitted. See the chart below for examples for each type of field value.
Custom Field Reference
Please note, the IDs listed in these examples are for demonstration purposes. The ID's of your fields will change. See API Reference - Fields for information on obtaining a field list, including IDs.
|Field Type||Description||Example Value|
|Address||A physical address||
|Country||A two character ISO country code||
An ISO-formatted date stamp.
The system can auto-detect some common date formats, however it is recommended to convert your dates into ISO format for consistency.
|Input (Long Answer)||
A multi-line string.
Line breaks can be added by using \n characters.
|Input (Short Answer)||A single-line string.||
|Money||A numeric value (without currency code).||
An exact match from the available choices.
Please review the available to choices for your multiple choice fields in order to properly validate the input before submitting the request.
A person's name.
Only the last name is required.
A numeric value.
Whole numbers and decimals are allowed.
A fully qualified domain name.
All website addresses must begin with https:// to be considered valid.
|Yes / No||
A boolean value.
Available choices are 1 or 0.
|Yes / No / NA||
A boolean value with empty fields.
Available choices are 1, 0, or an empty string.
Adding Subjects to the Case
You can add as many subjects as you want to into the subjects array, or you can opt not to add any subjects at all. Subject data is made up almost entirely of custom fields (see above for custom field reference information). There are three specific fields that must be addressed when adding subjects:
- subject_type_id - This is the type of subject you are submitting. The subject type determines which fields will be available when creating the case.
- is_primary - The primary subject is the one that is associated as the target of the case (e.g. Claimant). Other, supporting subjects like addresses or vehicles should not be marked as primary.
- is_pinned - When enabled, the subject's profile card will be tagged to the overview of the case. In most situations you will want to mark this as true.
All additional subject data will be submitted in the form of custom fields using the custom_fields array.
Remember that not all of the custom fields need to be filled out when submitting a subject on a new case, only fields that are marked as Required by the subject type must be entered. See the example below for a fully documented example request.
Example New Case Request
A new case is created by POSTing a JSON object to the specified end point using the above criteria. The JSON object must contain the required fields (as shown above) and must be nested under a casefile object. See the following example request:
"case_location": "Denver, CO",
"notes": "Try to find out if the claimant is actually hurt.",
"scheduling_notes": "One weekday and one weekend day",
"admin_notes": "Created by the API",
"case_services_list": [1, 2],
"value": "answer for field number 1"
"value": "answer for field number 2"
"value": "Big John"
"value": "This is an API Test \n\n Hello World."
"address_1": "2000 Blake St",
"address_2": "STE 123",
Note: The above request is for demonstration purposes only, your implementation will require unique data provided by your account.