Cases API

Last updated
Save as PDF
Share
1. Share
2. Tweet

Who is this article for?

CrashPlan for Small Business

Incydr, yes.

CrashPlan for Enterprise, no.

Code42 for Enterprise, no.

CrashPlan for Small Business, no.

This article applies to Code42 cloud environments.

Overview

This article explains how to use the Code42 API to interact with Cases.

The examples in this article use curl, but the concepts apply to any tool you choose for interacting with the Code42 API.

Cases API details

Base URL

United States
- If you sign in to the Code42 console at https://console.us.code42.com/console, use: https://east-cases.us.code42.com
- If you sign in to the Code42 console at https://www.crashplan.com/console, use: https://default-cases.prod.ffs.us2.code42.com
- Code42 federal environment: If you sign in to the Code42 console at https://console.gov.code42.com/console, use: https://default-cases.gov.code42.com
Ireland: https://default-cases.ie.code42.com

Additional API documentation

United States:
- https://east-cases.us.code42.com/swagger-ui.html#/Cases
- https://default-cases.prod.ffs.us2.code42.com/swagger-ui.html#/Cases
- https://default-cases.gov.code42.com/swagger-ui.html#/Cases (Code42 federal environment only)
Ireland: https://default-cases.ie.code42.com/swagger-ui.html#/Cases

Authentication

Authentication tokens are required in the header of all requests. To obtain an authentication token, use your Code42 administrator credentials to submit a GET request to:

United States:
- If you sign in to the Code42 console at https://console.us.code42.com/console, use:
  https://console.us.code42.com/c42api/v3/auth/jwt?useBody=true
- If you sign in to the Code42 console at https://www.crashplan.com/console, use:
  https://www.crashplan.com/c42api/v3/auth/jwt?useBody=true
- If you sign in to the Code42 console for the Code42 federal environment at https://console.gov.code42.com/console, use:
  https://console.gov.code42.com/c42api/v3/auth/jwt?useBody=true
Ireland: https://console.ie.code42.com/c42api/v3/auth/jwt?useBody=true

For example:

curl -X GET -u "admin@example.com" -H "Accept: application/json" "https://console.us.code42.com/c42api/v3/auth/jwt?useBody=true"

If your organization uses two-factor authentication for local users, you must also include a totp-auth header value containing the Time-based One-Time Password (TOTP) supplied by the Google Authenticator mobile app. The example below includes a TOTP value of 424242.

curl -X GET -u "admin@example.com" -H "totp-auth: 424242" "Accept: application/json" "https://console.us.code42.com/c42api/v3/auth/jwt?useBody=true"

A successful request returns an authentication token. For example:

{
    "v3_user_token": "eyJjdHkiOiJKV1QiLCJlbmMiOiJBMTI4R0NNIiwiZXhwIjoiMjAxOC0wNC0zMFQyMTo0MDoyNy4xMDZaIiwiYWxnIjoiUlNBLU9BRVAtMjU2In0.0H-4bl43zA3cIE5D3o_8vZzJIUgtJt64mZbimNa2TNha761RgVBFaTfttMODXF1ntLUTHl-rD0JuHEAMrIxjpnaODictPizrDVeTA1PgkPrsKot9jp6D7uTEC1Y56qHS1qjP6WHQBpv6ADBfrAfePX3NnwkA5a1I8pB88kSWc1MXZ4uMt-rFcNtlLLPVfwtEXHyNG_bxYJOOn28y2ysJGSBD_Xx1-uK4zKvjWwXfVQG581TntFPy0LamJfJ7IM4wOIG-QrKeV796fJAaHBxNfOe4UWC8WeNcDEvgNZvOPchWTHY4l66OaOjHNeEkoKkxvc35j4V_QpYxe6GXRYK4NA.TJXe9M6goiZbw-tr.y0lUTHHkHU5tRS7bWI8jntMLcxv0HajXTXquV62IG4400i7wi0YSX-6vpsXVgivzztxnPaukgUsLavhZ8-wCiMdEkut4GfijTlDAM_tfmJyZG6Cn5GKIJgSCENrR1JTxvC6dhTvHc41p6T3jXqBWikoJwD9z9Ec3u-OhM3gotQZUfCq0rR8T043RZSN9-0TpxhpPUEUAS6rkAI07QP08l_nUqdQTsNF0Tafe1yfPTYJabkslHhYMlLRYuXwhWr_39h5BY89ud0cW_OyUtjzz83m9iGxv6sba9VBIb2Y95ipXLu6Ie-5wz8zivfjizX6ZQatp5Ep4UZxzsMdqD9j0BFXkXQZuITJLtKfmUX-FZYR8utNrbwtt8u2tvNUK8Ix4Fwa3bWPxlkwrhOdz70M-mxluxpR6EKSrf8xwHagMcahzVPcW5NVL2khr4MwMUKyRV69dAdGiaTKh2rd52znA0aE3OCtelnBrBn4rls0KX71_qZEAdPaLyyqZ4VaurWUfl35zSi2LW_a3-TebgIebHZxC-MxvFEH4DQq6gJDdoX92_YEYEn4tO_dhUTlD0CZ9HhT39XFrO9MBe4DoDzG-Iql_A-nhmCyOrRmQvUlR72XpHVFQQx3X6tqdPxFocgDh5z03-kLB4SjznQSlzJNbzl_knXTBGopoFLn3WHvjX8q327Vmwx1hjrQnO8Eg5rJMoXTJCMEEOkMyjkbFeEzEhTf2jcvvAlnNnxdtjb1Zo05RWwMsPwwHAgGr-0mm-ungNjIGW0MyMTZtK0StP1uRqfI1Q6ghqnGZxEZN_0fvsVlsz4u9A1eBYRE0xzg8p-0g62nAQ8GftpYaUoymgqbL2WCL15r38emLklXSruztosGU4Dtusg4JHEhYPxO4ieqeBu6FLX9fPSA_y3zmd_AEjW40-_6zC3quPYJwytaEIwVH6phtfa2phsOLLw-U-b2QY09-d27YirIjgNRZ7rO4GF3iX8hW3LfFIWj0WKA5HGtGHg.JzHVCE8zfy1qRBf__rhchA"
}

Token considerations

Use this authentication token in your search requests (see sample use cases below).
Authentication tokens expire after one hour.
You must have credentials for a Code42 user with either the Customer Cloud Admin or Security Center User role.
The example above only applies to users who authenticate locally with Code42. Single sign-on (SSO) users must also complete SAML authentication with their SSO provider. If you need assistance with this process, contact your SSO provider.
The URL to obtain the authentication token is different than the URL used to query Cases data.

Request parameters

In the sample use cases, items formatted as <value> represent values you need to customize for your specific request. See below for steps to obtain these values. Do not include the brackets in the request.

For all requests below:

Replace <Base_URL> with the address of your Code42 environment.
Replace <token> with the authentication token obtained above.

For requests about a specific case:

Replace <case number> with the number of the case you want to view or modify. There are two ways to obtain the case number:
1. Use the Return list of cases filtered by status request below to return a list of cases. The case number is the number field in the response.
2. From the Code42 console:
  1. Select Cases.
  2. Select a case.
  3. Select the Case Details tab.
  4. Note the Case ID.

For requests about a specific file event:

Replace <eventId> with a specific event id string. To obtain the event id, either:
- Use the Forensic Search API to search for file events and obtain the value of the eventId parameter.
- Use the Return events associated with a case request below to return events for a case and note the eventId. (Note: The same event can be included in multiple cases, but duplicate events are not allowed in the same case.)

Other values:

Replace <status> with either:
- OPEN to keep the case active and editable.
- CLOSED to resolve the case. Closed cases cannot be re-opened or modified.
Replace <subject User UID> with the User UID of the person being investigated in the case.
Replace <assignee User UID> with the User UID of the security analyst or administrator assigned to investigate the case.

Sample use cases

Create a case

Request

Only the name field is required. To leave a field blank, supply the value null .

curl -X POST '<Base URL>/api/v1/case' -H 'content-type: application/json' -H 'authorization: Bearer <token>'
-d '{
    "name": "Sample case name",
    "description": "Sample description",
    "findings": "Sample findings",
    "subject":  null,
    "assignee": null
}'

Response

{
    "number": 1,
    "name": "Sample case name",
    "createdAt": "2020-10-27T15:16:05.369203Z",
    "updatedAt": "2020-10-27T15:16:05.369203Z",
    "description": "Sample description",
    "findings": "Sample findings",
    "subject": null,
    "subjectUsername": null,
    "status": "OPEN",
    "assignee": null,
    "assigneeUsername": null,
    "createdByUserUid": "806150685834341101",
    "createdByUsername": "05c28ad3-7eca-4d99-8bb7-a5d0995806c8",
    "lastModifiedByUserUid": "806150685834341101",
    "lastModifiedByUsername": "05c28ad3-7eca-4d99-8bb7-a5d0995806c8"
}

Update an existing case

Before updating a case, perform a GET request for that case number to obtain all existing values. For example:

curl -X GET '<Base URL>/api/v1/case/<case number>' -H 'content-type: application/json' -H 'authorization: Bearer <token>'

Missing parameters are set to null
Resubmit all values in the sample PUT command below, even if they're not changing. If you don't send an explicit value for each of these fields, they will be updated to null.

Request

curl -X PUT '<Base URL>/api/v1/case/<case number>' -H 'content-type: application/json' -H 'authorization: Bearer <token>'
-d '{
    "name": "<updated case name>",
    "description": "<updated description>",
    "findings": "<updated findings>",
    "subject": <subject user UID>,
    "assignee": <assignee user UID>,
    "status": "<status>"
}'

Response

{
    "number": 1,
    "name": "Updated name",
    "createdAt": "2020-10-27T15:16:05.369203Z",
    "updatedAt": "2020-10-27T15:20:26.311894Z",
    "description": "Updated description",
    "findings": "Updated findings",
    "subject": 421380797518239242
    "subjectUsername": casey@example.com,
    "status": "OPEN",
    "assignee": 273411254592236331,    
    "assigneeUsername": admin@example.com,
    "createdByUserUid": "806150685834341101",
    "createdByUsername": "05c28ad3-7eca-4d99-8bb7-a5d0995806c8",
    "lastModifiedByUserUid": "806150685834341101",
    "lastModifiedByUsername": "05c28ad3-7eca-4d99-8bb7-a5d0995806c8"
}

Add events to a case

Request

curl -X POST '<Base URL>/api/v1/case/<case_number>/fileevent/<eventId>' -H 'content-type: application/json' -H 'authorization: Bearer <token>'

Response

None (204 on success)

Return events associated with a case

Request

curl -X GET '<Base URL>/api/v1/case/<case_number>/fileevent' -H 'content-type: application/json' -H 'authorization: Bearer <token>'

Response

{
    "events": [
        {
            "eventId": "734430974935_09970279-be77-4cd1-ba08-19d958969832",
            "eventTimestamp": "2020-10-26T18:56:04.661Z",
            "exposure": [
                "SharedToDomain",
                "OutsideTrustedDomains"
            ],
            "fileName": "Products.png",
            "filePath": null
        }
    ]
}

Return list of cases filtered by status

The sample below filters for open cases. To filter for closed cases, change the query parameter to ?status=CLOSED. Other parameters that support filtering include: assignee, createdAt, isAssigned, lastModifiedBy, name, subject, and updatedAt.

Request

curl -X GET '<Base URL>/api/v1/case?status=OPEN' -H 'content-type: application/json' -H 'authorization: Bearer <token>'

Response

{
    "cases": [
        {
            "number": 1,
            "name": "Example Case",
            "createdAt": "2020-10-27T15:16:05.369203Z",
            "updatedAt": "2020-10-27T15:20:26.311894Z",
            "subject": null,
            "subjectUsername": null,
            "status": "OPEN",
            "assignee": null,
            "assigneeUsername": null,
            "createdByUserUid": "806150685834341101",
            "createdByUsername": "05c28ad3-7eca-4d99-8bb7-a5d0995806c8",
            "lastModifiedByUserUid": "806150685834341101",
            "lastModifiedByUsername": "05c28ad3-7eca-4d99-8bb7-a5d0995806c8"
        }
    ],
    "totalCount": 1
}

Export a case

There are two options for exporting cases:

Case summary: Exports a PDF with the case subject, details, and findings. Detailed file activity is not included.
File activity: Exports a CSV file with extensive file metadata details for all events in this case. For field definitions, see the Forensic Search event details.

File export considerations with curl

Use the -o <sample_export.csv> argument to specify a unique filename. Update the filename as appropriate for your request. Do not include the brackets in the request.
Use the -O argument (capital "O") to automatically name the file. This is not recommended if you need to export more than one file, because this method uses the same filename for each export and therefore overwrites the previous file.
Files are saved in the directory from which you issue the curl request in the command line. For example, in the command prompt COMPUTER:~ clyde.bailey$ curl -X GET... the file is saved in the Users/clyde.bailey directory on the device that issued the request.

Case summary PDF

Request

curl -X GET '<Base URL>/api/v1/case/<case number>/export' -o <sample_export.pdf> -H 'authorization: Bearer <token>'

Response

  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100  1618    0  1618    0     0   2528      0 --:--:-- --:--:-- --:--:--  2524

The PDF is saved to your device.

File activity CSV

Request

curl -X GET '<Base URL>/api/v1/case/<case number>/fileevent/export' -o <sample_export.csv> -H 'authorization: Bearer <token>'

Response

  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100  3771    0  3771    0     0   6843      0 --:--:-- --:--:-- --:--:--  6843

The CSV is saved to your device.

External resources

Curl: Command line tool and library reference

Overview

Cases API details

Authentication

Request parameters

Sample use cases

Create a case

Update an existing case

Add events to a case

Return events associated with a case

Return list of cases filtered by status

Export a case

Case summary PDF

File activity CSV

External resources

Related topics