API Reference - Case Requests – Trackops Support Center

Important: Case requests are designed to capture case referrals from customers who may not yet be clients. If you are working with cases for existing customers, you should work with Case Objects instead.

Listing Case Requests

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

GET /api/v1/case/requests

Available Request Parameters:

Name	Type	Required	Description
id	integer	no	ID of the case request.
client	integer	no	ID of the root (parent) client the case request is assigned to.
location	integer	no	ID of the client location the case request is assigned to.
case_region	integer	no	ID of the case region the case request is assigned to.
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.
primary_contact	integer	no	ID of the primary client contact assigned to the case request.
primary_subject	integer	no	ID of the primary subject assigned to the case request.
reference_value_1	string	no	Value of the 1st reference on the case request (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 request (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 request (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 request number.
case_request_number	string	no	The fully formatted Trackops case request number, as it appears in your system.

Note: All timestamp parameters are queried and returned in UTC.

Getting a Case Request

Returns a single case request record, based on the numeric ID.

GET /api/v1/case/requests/{case_request_id}

Creating a Case Request

Creates a new case request based on the given criteria. Upon success, returns a case request object. See the example request at the bottom of this section for a better idea of how a fully formed request should look.

Note: Case requests are designed for capturing case referrals for new customers who may not already be clients. If you are creating cases for existing clients, use API Reference - Cases instead.

POST /api/v1/case/requests

Available Parameters

Name	Type	Required	Description
case_type_id	integer	yes	ID of the case type. See Case Types
client	object	yes	See "Working with Client and Contact objects" in this article.
contact	object	yes	See "Working with Client and Contact objects" in this article.
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 Client and Contact objects

Case requests allow you to capture freeform client and contact information. This can be matched later inside the system with an existing client, or a new client can be created based on the submitted information.

Available Client Parameters

Name	Type	Required	Description
name	string	yes	The name of the client (organization if possible)
address_1	string	yes/no	Required if Require Client Address is enabled in General Case Settings
address_2	string	no	Line 2 of the street address
address_3	string	no	Line 3 of the street address
city	string	yes/no	Required if Require Client Address is enabled in General Case Settings
state	string	no	2-character state or province code of the street address.
zip	string	no	The zip code or postal code associated with this address.
country	string	yes	2-character ISO country code of the street address.

Example Client Object

{
  "name": "Your Customer Name", 
  "address_1": "123 Main Street",
  "address_2": "STE 555",
  "address_3": "",
  "city": "Any Town",
  "state": "CO",
  "zip": 12345,
  "country": "US"
}

Available Contact Parameters

Name	Type	Required	Description
first_name	string	no	The first name of the client contact.
middle_name	string	no	The middle name of the client contact.
last_name	string	yes	The last name of the client contact.
email	string	yes	The email address of the client contact.
phone_office	string	yes/no	One phone number is required if Require Client Phone is enabled in General Case Settings
phone_home	string	yes/no	One phone number is required if Require Client Phone is enabled in General Case Settings
phone_mobile	string	yes/no	One phone number is required if Require Client Phone is enabled in General Case Settings
phone_fax	string	no	The fax number of the client contact.

Example Contact Object

{
  "first_name": "Joe",
  "middle_name": "",
  "last_name": "Adjuster",
  "email": "email@example.com",
  "phone_office": "555-555-5555",
  "phone_mobile": "555-555-5555",
  "phone_fax": "555-555-5555"
}

See below for a complete example, which includes both the client and contact objects.

Working with Custom Fields

Custom fields can be added to both case requests 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 Request

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 Body

A new case request 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_request object. See the following example request:

{
  "casefile_request": {
    "case_type_id": 1,
    "client": {
      "name": "Your Customer Name",
      "address_1": "123 Main Street",
      "address_2": "STE 555",
      "address_3": "",
      "city": "Any Town",
      "state": "CO",
      "zip": 12345,
      "country": "US"
    },
    "contact": {
      "first_name": "Joe",
      "middle_name": "",
      "last_name": "Adjuster",
      "email": "email@example.com",
      "phone_office": "555-555-5555",
      "phone_mobile": "555-555-5555",
      "phone_fax": "555-555-5555"
    },
    "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": "Notes and instructions go here.",
    "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 Request

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

PUT /api/v1/case/requests/{case_request_id}

Available Parameters

Name	Type	Required	Description
client_id	integer	no	ID of the client location. See Client Locations
client	object	no	See "Working with Client and Contact objects" in this article.
contact	object	no	See "Working with Client and Contact objects" in this article.
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 Body

A case request 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_request object. See the following example request:

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

Note 1: When updating a client or contact object, the entire object (all fields) must be updated at once.

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