Skip to main content
Contact Support

Who is this article for?

Incydr
Code42 for Enterprise
CrashPlan for Enterprise
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.

HOME
GETTING STARTED
RELEASE NOTES
FAQs
APIs
SYSTEM STATUS
Code42 Support

Cases API

  1. Last updated
  2. Save as PDF

Who is this article for?

Incydr
Code42 for Enterprise
CrashPlan for Enterprise
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

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:

Copied!
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.

Copied!
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:
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 Response > 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 .

Copied!
curl -X POST '<Base URL>/api/v1/case' -H 'content-type: application/json' -H 'authorization: v3_user_token <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:

Copied!
curl -X GET '<Base URL>/api/v1/case/<case number>' -H 'content-type: application/json' -H 'authorization: v3_user_token <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
Copied!
curl -X PUT '<Base URL>/api/v1/case/<case number>' -H 'content-type: application/json' -H 'authorization: v3_user_token <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
Copied!
curl -X POST '<Base URL>/api/v1/case/<case_number>/fileevent/<eventId>' -H 'content-type: application/json' -H 'authorization: v3_user_token <token>'
Response

None (204 on success)

Return events associated with a case

Request
Copied!
curl -X GET '<Base URL>/api/v1/case/<case_number>/fileevent' -H 'content-type: application/json' -H 'authorization: v3_user_token <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
Copied!
curl -X GET '<Base URL>/api/v1/case?status=OPEN' -H 'content-type: application/json' -H 'authorization: v3_user_token <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
}

External resources

Curl: Command line tool and library reference

Related topics

  1. Back to top
  • Was this article helpful?

Recommended articles

  1. There are no recommended articles.
  1. Article type
    Topic
    Available in CrashPlan for Enterprise
    No
    Available in Code42 for Enterprise
    No
    Available in Incydr
    Yes
    Available in CrashPlan for Small Business
    No
  2. Tags
    1. API
    2. Cases
    3. Code42 API