1. API
  2. Cases

Cases: Create

Last updated Open markdown version

Description

Create a case.

Request

HTTP Method: POST

Parameter Description
team_id The team ID the case is within.
name The case name.
description Optional The case description. Supports markdown and mentioning users. To mention a user, use the notation <@user-2435>, replacing '2435' with the user ID.
priority Optional The case priority - critical, high, medium, low or info.
status Optional The case status - open or closed.
sub_status_id Optional The case sub-status ID.
author_email Optional The email of the user creating the cases.
assignee_emails Optional An array of user email addresses to assign to the case. Case will automatically be assigned to the user associated with the API token if none provided.
tag_names Optional An array of tag names.
opened_at Optional ISO 8601 Timestamp representing the date and time the case was opened at.
resolved_at Optional ISO 8601 Timestamp representing the date and time the case was resolved at.
metadata Optional Case related metadata represented as key-value pairs.
closure_conditions Optional 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.

N.B. The formula key should be passed as a raw formula wrapped in strings as opposed to a pill value.
field_values Optional An object containing a key-value pair of case input IDs and values for the case. Case input IDs provided must exist within the team for the field to be successfully added to the case. For case inputs with "Allow multiple" enabled, provide the value as a pipe-delimited string, for example "option1|option2".
tasks Optional An array of task objects to create with the case. Each task object should contain a description and optionally assignee_ids or assignee_emails.
blocks Optional An array of block objects to create with the case. See block parameters below.

Block parameters

Each object in the blocks array accepts:

Parameter Description
title The title of the block.
block_type The type of block to create - options: note, file, linked_cases, metadata, closure_conditions, case_action, block_group and html.
elements An array of elements to add to the block. Required but may be empty for block types that do not support elements.
hidden Optional A boolean (true or false).
guid Optional A client-generated identifier for the block, used for referencing in parent_block_guid.
parent_block_guid Optional The guid of a block_group block within the same request to nest this block inside.

Note element parameters

Parameter Description
content The content of the note.
note_type The type of note - "html" for html blocks and "text" for any others.
color Optional The color of the note - options: white, gold, magenta, green, blue, red, mint, indigo.

File element parameters

Parameter Description
filename The name of the file.
file_contents The base64-encoded contents of the file.
annotation Optional The annotation text for the file.

Sample request

curl -X POST \
  https://<tenant-domain>/api/v2/cases/ \
  -H 'content-type: application/json' \
  -H 'Authorization: Bearer <<CREDENTIAL.tines_api_key>>' \
  -d '{
  "team_id": "team_id",
  "name": "Suspicious login detected",
  "priority": "high",
  "description": "This is a high priority case created via the API",
  "assignee_emails": [
    "jane@tines.io"
  ],
  "tag_names": [
    "login",
    "security"
  ],
  "metadata": {
    "key": "value"
  },
  "closure_conditions": [
    {
      "name": "has at least 1 assignee",
      "formula": "=SIZE(team_case.assignees) > 0"
    }
  ],
  "field_values": {
    "1": "Windows"
  },
  "tasks": [
    {
      "description": "Review security logs",
      "assignee_ids": [123, 456]
    },
    {
      "description": "Contact affected users"
    }
  ],
  "blocks": [
    {
      "title": "Investigation notes",
      "block_type": "note",
      "elements": [
        {
          "content": "Initial triage completed - suspicious IP identified.",
          "note_type": "text",
          "color": "gold"
        }
      ]
    },
    {
      "title": "Evidence",
      "block_type": "block_group",
      "guid": "evidence-group",
      "elements": []
    },
    {
      "title": "Log files",
      "block_type": "file",
      "parent_block_guid": "evidence-group",
      "elements": [
        {
          "filename": "auth-logs.txt",
          "file_contents": "SGVsbG8gV29ybGQ="
        }
      ]
    }
  ]
}'

Response

A successful request will return a JSON object describing the created case.

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.
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.
linked_cases_meta Metadata defining pagination params required to fetch additional linked cases 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 array of SLAs for the case. Times are in seconds.
fields An array of field values for the case.
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.
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.
blocks An array of block objects specifying the block title, slug, type, position, visibility, group, and element ids.
tasks An array of tasks associated with the case.

Sample response

{
  "case_id": 1,
  "name": "Case 1..25",
  "description": null,
  "status": "OPEN",
  "sub_status": {
    "id": 1,
    "name": "To do"
  },
  "priority": "LOW",
  "url": "http://<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"
    }
  ],
  "fields": [
    {
      "id": 1,
      "value": "Windows 11",
      "case_input": {
        "id": 1,
        "key": "operating_system",
        "name": "Operating system",
        "validation_type": "none",
        "validation_options": {}
      }
    }
  ],
  "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": 2, "name": "Case 2" },
    { "case_id": 3, "name": "Case 3" }
  ],
  "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"
    }
  ],
  "blocks": [
    {
      "id": 1,
      "title": "Notes",
      "slug": "blk_notes",
      "block_type": "note",
      "position": 1,
      "hidden": false,
      "block_group_id": null,
      "elements": [
        { "element_id": 54, "id": 54 },
        { "element_id": 674, "id": 674 },
        { "element_id": 524, "id": 524 }
      ]
    },
    {
      "id": 3,
      "title": "Investigation",
      "slug": "blk_investigation",
      "block_type": "block_group",
      "position": 2,
      "hidden": false,
      "block_group_id": null,
      "elements": []
    },
    {
      "id": 2,
      "title": "Additional notes",
      "slug": "blk_additional_notes",
      "block_type": "note",
      "position": 3,
      "hidden": true,
      "block_group_id": 3,
      "elements": [
        { "element_id": 235, "id": 235 },
        { "element_id": 342, "id": 342 },
        { "element_id": 744, "id": 744 }
      ]
    }
  ],
  "tasks": [
    {
      "id": 1,
      "description": "Review security logs",
      "completed": false,
      "assignees": [
        {
          "id": "123"
        },
        {
          "id": "456"
        }
      ],
      "created_at": "2024-03-25T15:40:39Z",
      "updated_at": "2024-03-25T15:40:39Z"
    },
    {
      "id": 2,
      "description": "Contact affected users",
      "completed": false,
      "assignees": [],
      "created_at": "2024-03-25T15:40:39Z",
      "updated_at": "2024-03-25T15:40:39Z"
    }
  ],
  "activities_meta": {
    "current_page": "https://<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://<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": 2
  },
  "linked_cases_meta": {
    "current_page": "https://<tenant-domain>/api/v2/cases/1/linked_cases?per_page=50&page=1",
    "previous_page": null,
    "next_page": null,
    "next_page_number": null,
    "per_page": 50,
    "pages": 1,
    "count": 2
  }
}
Was this helpful?