API Reference - Cases – Trackops Support Center

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 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
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:

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. 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 location. See 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.

Listing Cases

Getting a Case

Creating a Case

Updating a Case

See Also