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.

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