API Reference - Subjects

Subjects are the objects that store detailed information about the target of the investigation.

Subject collections are largely comprised of custom fields.

Listing Subjects

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

GET /api/v1/subjects

Available Request Parameters:

Name	Type	Required	Description
id	integer	no	ID of the subject.
case	integer	no	ID of the case this subject belongs to.
is_primary	integer	no	If yes, the subject must be a "primary" subject.
name	string	no	Name of the subject (last, first if a proper name).
subject_type	integer	no	ID of the subject type this subject belongs to.
created_from	timestamp	no	Created on or after the date.
created_to	timestamp	no	Created 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.

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

Getting a Subject

Returns a single subject record, based on the numeric ID.

GET /api/v1/subjects/{subject_id}

Creating a Subject

Creates a new subject for an existing case. Upon success, returns a subject 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/subjects

Available Parameters

Name	Type	Required	Description
casefile_id	integer	yes	ID of the case. API Reference - Cases
subject_type_id	integer	yes	ID of the subject type; the type of subject you are submitting. The subject type determines which fields will be available when creating the case.
is_primary	boolean	no	Determines if this subject is the "Primary Subject" on the case.
is_pinned	boolean	no	Determines if the subject profile is pinned to the "Overview" tab on the case (recommended true).
custom_fields	collection	yes	Custom field objects to create (see below)

Working with Custom Fields

Custom fields 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 field values, refer to the custom field reference chart in the API Reference - Fields documentation for available field types and example values.

Example New Subject Request

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

{
  "subject": {
    "casefile_id": 123,
    "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 Subject

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

PUT /api/v1/subjects/{subject_id}

 

Available Parameters

Name	Type	Required	Description
casefile_id	integer	yes	ID of the case. API Reference - Cases
is_primary	boolean	no	Determines if this subject is the "Primary Subject" on the case.
is_pinned	boolean	no	Determines if the subject profile is pinned to the "Overview" tab on the case (recommended true).
custom_fields	collection	yes	Custom field objects to create (see below)

Working with Custom Fields

Custom fields 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 field values, refer to the custom field reference chart in the API Reference - Fields documentation for available field types and example values.

Example Update Subject Request 

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

{
  "subject": {
    "is_primary": true,
    "custom_fields": [
      {
        "id": 1,
        "value": {
        "first_name": "John",
        "middle_name": "B",
        "last_name": "Smith"
      }
    ]
  }
}

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