List

Description

Retrieve a list of cases.

Request

HTTP Method: GET

Query Parameter Description
team_id Optional Retrieve cases for the specified team.
filters Optional Object specifying case filters (see the table below).
order Optional RECENTLY_EDITED, LEAST_RECENTLY_EDITED, PRIORITY_ASC, PRIORITY_DESC, OPENED_ASC, OPENED_DESC, CREATED_ASC or CREATED_DESC.
per_page Optional Set the number of results returned per page. Defaults to 20, maximum is 50.
page Optional Specify the page of results to return if there are multiple pages. Defaults to page 1.

Supported parameters in filters

filters parameters Description
and_tags Optional An array of tag names to AND'd by.
assigned_to_me Optional A boolean (true or false).
assignees Optional An array of user IDs.
assignee_emails Optional An array of user email addresses.
author_emails Optional An array of author emails.
case_ids Optional An array of case IDs.
end_date Optional A timestamp.
exclude_tags Optional An array of tag names to exclude by.
metadata Optional An object of metadata as key-value pairs.
or_tags Optional An array of tag names that are OR'd by.
priority Optional CRITICAL, HIGH, MEDIUM, LOW or INFO.
records Optional A string array of record result values. Cases containing a record matching any of the results provided will be returned. Note: Large text record fields are not queryable in this instance.
resolved_at_start_date Optional A timestamp (ISO 8601 format). Resolved at end date will default to today if not provided.
resolved_at_end_date Optional A timestamp (ISO 8601 format).
search Optional A string that searches against case name, description and ID.
start_date Optional A timestamp (ISO 8601 format). End date will default to today if not provided.
status Optional OPEN or CLOSED.
sub_status_names Optional An array of sub status names.
tags Optional An array of tag names (behaves the same as and_tags).
unassigned Optional A boolean (true or false).
updated_at_start_date Optional A timestamp (ISO 8601 format). Updated at end date will default to today if not provided.
updated_at_end_date Optional A timestamp (ISO 8601 format).
fields Optional An array of objects representing fields. Fields are objects with a case input key and value. 
curl -X GET \
  https://<<META.tenant.domain>>/api/v2/cases \
  -H 'content-type:  application/json' \
  -H 'Authorization:  Bearer <<CREDENTIAL.tines_api_key>>'

Example request with search filters

Sample request params:

{
  "team_id": "1",
  "filters": {
    "search": "Sample search string",
    "status": "OPEN",
    "priority": "HIGH",
    "fields": [
      {
        "key": "company",
        "value": "Tines"
      }
    ]
  },
  "order": "OPENED_DESC",
  "per_page": "10"
}

Example request:

curl -v \
-X GET \
--location \
"https://<<META.tenant.domain>>/api/v2/cases/?order=OPENED_DESC&per_page=10&team_id=1" \
-H 'content-type: application/json' \
-H 'Authorization: Bearer <<CREDENTIAL.tines_api_key>>'
--data '{
    "filters": {
      "status": "OPEN",
      "priority": "HIGH",
      "fields": [
          {
              "key": "version",
              "value": "2.0"
          }
      ]
    }
}'

Response

A successful request will return a JSON object containing the cases the requesting token has access to.

Field description

Parameter Description
case_id The ID of the case.
name The case name.
description The case description.
status The case status - open or closed.
sub_status An object describing the case sub-status.
url The case URL.
metadata Case related metadata represented as key-value pairs.
author An object describing the case author.
opened_by An object describing the user who opened the case.
resolved_by An object describing the user who resolved the case.
assignees An array of users assigned to the case.
tags An array of tags associated with the case.
fields An array of field values for the case.
activities An array of team case actions taken within the case.
activities_meta Metadata defining pagination params required to fetch additional activities for the case.
team The team the case is within - ID & name.
actions An array of case actions for downstream actions associated with the case.
linked_cases An array of cases linked to this case - ID & name.
sla An object describing the case SLA status. Times are in seconds.
slas An an array of SLAs for the case. Times are in seconds.
opened_at ISO 8601 Timestamp representing the date and time the case was opened at.
resolved_at ISO 8601 Timestamp representing the date and time the case was resolved at.
created_at ISO 8601 Timestamp representing the date and time the case was created at.
updated_at ISO 8601 Timestamp representing the date and time the case was updated at.
records An array of records associated with the case, grouped by record type. Each record result includes the field id, name, and value.
records_meta Metadata defining pagination params required to fetch additional records for the case.
priority The case priority - critical, high, medium, low or info.
closure_conditions An array of closure requirements in the form of a set of formula rules that need to evaluate to true to enable the closing of a case.

Sample response

{
  "cases": [
    {
      "case_id": 1,
      "name": "Case 1..25",
      "description": null,
      "status": "OPEN",
      "sub_status": {
        "id": 1,
        "name": "To do"
      },
      "priority": "LOW",
      "url": "http://<<META.tenant.domain>>/team/276/cases/1",
      "metadata": {
        "foo": "bar"
      },
      "author": {
        "user_id": "168",
        "first_name": "Example",
        "last_name": "Person",
        "email": "person_2@example.com",
        "avatar_url": "",
        "is_service_account": false
      },
      "opened_by": null,
      "resolved_by": null,
      "assignees": [
        {
          "user_id": "176",
          "first_name": "Example",
          "last_name": "Person",
          "email": "person_10@example.com",
          "avatar_url": "",
          "is_service_account": false
        },
        {
          "user_id": "178",
          "first_name": "Example",
          "last_name": "Person",
          "email": "person_12@example.com",
          "avatar_url": "",
          "is_service_account": false
        },
        {
          "user_id": "180",
          "first_name": "Example",
          "last_name": "Person",
          "email": "person_14@example.com",
          "avatar_url": "",
          "is_service_account": false
        }
      ],
      "tags": [
        {
          "id": 7,
          "name": "Tag 1"
        },
        {
          "id": 8,
          "name": "Tag 2"
        },
        {
          "id": 9,
          "name": "Tag 3"
        }
      ],
      "sla": {
        "remaining_time_seconds": 0,
        "current_time_seconds": 0,
        "percent_elapsed": 0,
        "exceeded": false,
        "sla_type": "completion"
      },
      "slas": [
        {
          "remaining_time_seconds": 0,
          "current_time_seconds": 0,
          "percent_elapsed": 0,
          "exceeded": false,
          "sla_type": "completion"
        },
        {
          "remaining_time_seconds": 0,
          "current_time_seconds": 0,
          "percent_elapsed": 100,
          "exceeded": true,
          "sla_type": "response"
        }
      ],
      "activities": [
        {
          "id": 109,
          "activity_type": "CREATED",
          "value": "115",
          "user": {
            "user_id": "168",
            "first_name": "Example",
            "last_name": "Person",
            "email": "person_2@example.com",
            "avatar_url": "",
            "is_service_account": false
          },
          "created_at": "2024-03-25T15:40:39Z"
        },
        {
          "id": 111,
          "activity_type": "COMMENTED",
          "value": "I'm a comment",
          "user": {
            "user_id": "170",
            "first_name": "Example",
            "last_name": "Person",
            "email": "person_4@example.com",
            "avatar_url": "",
            "is_service_account": false
          },
          "created_at": "2024-03-25T15:40:39Z"
        },
        {
          "id": 113,
          "activity_type": "COMMENTED",
          "value": "I'm a comment",
          "user": {
            "user_id": "172",
            "first_name": "Example",
            "last_name": "Person",
            "email": "person_6@example.com",
            "avatar_url": "",
            "is_service_account": false
          },
          "created_at": "2024-03-25T15:40:39Z"
        }
      ],
      "team": {
        "id": 276,
        "name": "Test team 1"
      },
      "linked_cases": [{ "case_id": 1, "name": "Case 1" }],
      "closure_conditions": [
        {
          "formula": "=SIZE(team_case.assignees) > 2",
          "name": "Number of assignees"
        }
      ],
      "opened_at": "2024-03-25T15:40:39Z",
      "resolved_at": null,
      "created_at": "2024-03-25T15:40:39Z",
      "updated_at": "2024-03-25T15:40:39Z",
      "records": [
        {
          "record_type_id": 55,
          "record_type_name": "Record type 2",
          "record_type_record_results": [
            {
              "id": 59,
              "results": [
                {
                  "id": 59110,
                  "name": "Timestamp",
                  "value": "2024-04-16T08:02:03Z"
                },
                {
                  "id": 59109,
                  "name": "Story name",
                  "value": "Alert investigation"
                }
              ],
              "created_at": "2024-04-16T08:02:03Z"
            },
            {
              "id": 58,
              "results": [
                {
                  "id": 58110,
                  "name": "Timestamp",
                  "value": "2024-04-16T08:02:03Z"
                },
                {
                  "id": 58109,
                  "name": "Story name",
                  "value": "Alert investigation #1"
                }
              ],
              "created_at": "2024-04-16T08:02:03Z"
            }
          ]
        },
        {
          "record_type_id": 54,
          "record_type_name": "Record type 1",
          "record_type_record_results": [
            {
              "id": 56,
              "results": [
                {
                  "id": 56108,
                  "name": "Timestamp",
                  "value": "2024-04-16T08:02:03Z"
                },
                {
                  "id": 56107,
                  "name": "Story name",
                  "value": "Alert investigation #2"
                }
              ],
              "created_at": "2024-04-16T08:02:03Z"
            },
            {
              "id": 55,
              "results": [
                {
                  "id": 55108,
                  "name": "Timestamp",
                  "value": "2024-04-16T08:02:03Z"
                },
                {
                  "id": 55107,
                  "name": "Story name",
                  "value": "Alert investigation #3"
                }
              ],
              "created_at": "2024-04-16T08:02:03Z"
            }
          ]
        }
      ],
      "actions": [
        {
          "id": 7,
          "url": "http://example.com",
          "label": "Hello, world!",
          "action_type": "page"
        }
      ],
      "fields": [
        {
          "id": 1,
          "value": "Tines",
          "case_input": {
            "id": 1,
            "key": "company",
            "name": "Company"
          }
        }
      ],
      "activities_meta": {
        "current_page": "https://<<META.tenant.domain>>/api/v2/cases/1/activities?per_page=20&page=1",
        "previous_page": null,
        "next_page": null,
        "next_page_number": null,
        "per_page": 20,
        "pages": 1,
        "count": 3
      },
      "records_meta": {
        "current_page": "https://<<META.tenant.domain>>/api/v2/cases/1/records?per_page=20&page=1",
        "previous_page": null,
        "next_page": null,
        "next_page_number": null,
        "per_page": 20,
        "pages": 1,
        "count": 4
      }
    }
  ],
  "meta": {
    "current_page": "https://<<META.tenant.domain>>/api/v2/cases?per_page=20&page=1",
    "previous_page": null,
    "next_page": null,
    "next_page_number": null,
    "per_page": 20,
    "pages": 1,
    "count": 1
  }
}
Was this helpful?