API Reference - Cases

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.  

 

Listing Cases

Returns a collection of case records, optionally filtered by the available request parameters.

GET /api/v1/cases

 

Available Request Parameters:

Name Type Required Description
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.

GET /api/v1/cases/{case_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.

POST /api/v1/cases

Available Parameters

Name Type Required Description
case_type_id integer yes ID of the case type. See Case Types
client_id integer yes ID of the client locationSee 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
created_on date yes The date the case was received in ISO format (e.g. 2024-12-01)
due_on date no The due date of the case in ISO format (e.g. 2024-12-01)
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.  

When constructing custom fields, refer to the chart in the API Reference - Fields documentation for available field types and example values.

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:

  1. 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.
  2. 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.
  3. 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. For more information, review the API Reference - Subjects documentation.

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:

{
"casefile": {
"case_type_id": 1,
"client_id": 6,
"primary_contact_id": 2,
"case_region_id": 1,
"created_on": "2019-06-01",
"due_on": "2019-06-15",
"company_location_id": 2,
"reference_value_1": "ABC123-ClaimNumber",
"reference_value_2": "ABC",
"reference_value_3": "123",
"created_on": "2019-05-29",
"case_location": "Denver, CO",
"budget_money": "1500",
"budget_hours": "8",
"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],
"case_flags_list": [1],
"custom_fields": [
{
"id": 1,
"value": "answer for field number 1"
},
{
"id": 2,
"value": "answer for field number 2"
}
],
"subjects": [
{
"subject_type_id": 1,
"is_primary": true,
"is_pinned": true,
"custom_fields": [
{
"id": 1,
"value": {
"first_name": "John",
"middle_name": "B",
"last_name": "Doe"
}
},
{
"id": 3,
"value": "Big John"
},
{
"id": 2,
"value": "1979-10-30"
},
{
"id": 4,
"value": "123-45-6789"
},
{
"id": 16,
"value": "This is an API Test \n\n Hello World."
},
{
"id": 26,
"value": {
"address_1": "2000 Blake St",
"address_2": "STE 123",
"city": "Denver",
"state": "CO",
"zip": "80202",
"country": "US"
}
}
]
}
]
}
}

Note: The above request is for demonstration purposes only, your implementation will require unique data provided by your account.

 

Updating a Case

Updates an existing case. Upon success, returns a case object. All fields are optional when updating a record, meaning fields not included will remain unchanged.

PUT /api/v1/cases/{case_id}

 

Available Parameters

Name Type Required Description
client_id integer no ID of the client locationSee Client Locations
primary_contact_id integer no ID of the client contact. See Client Contacts
case_region_id integer no ID of the case region. See Case Regions
created_on date no The date the case was received in ISO format (e.g. 2024-12-01)
due_on date no The due date of the case in ISO format (e.g. 2024-12-01)
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)
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)

Example Update Case Request 

A case is updated 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:

{
"casefile": {
"due_on": "2024-01-01"
}
}

Note: The above request is for demonstration purposes only, your implementation will require unique data provided by your account.

 

Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request