NAV

Detection List Management API

Overview

You can manually manage users in the High Risk Employees list and Departing Employees list from the Code42 console. To automate the process of managing users in these detection lists, you can write scripts that use the High Risk Employee APIs and Departing Employee APIs. This article provides an introduction to the APIs.

Considerations

Manage users

Create a detection list profile for a user

Before you can manage a Code42 user with the detection management list APIs, you must create a detection list profile for the user with the /v1/detection-lists/user/create API. This profile is for an existing Code42 user and contains the details needed to manage that user on the High Risk Employees and Departing Employees lists. It includes information about the user specifically for use in detection lists, such as notes, risk attributes, and cloud user names. When you add the user to any detection list, the profile accompanies them.

When you create a detection list profile for a user, the information is associated with the user's ID. You must submit the user's ID whenever you run any subsequent APIs to manage the user in a detection list.

Keep in mind that a detection list profile is created automatically when you add Code42 users to detection lists using the Code42 console. You only have to create a detection list profile for a user if one has not been created yet.

Note: Before attempting to create a detection list profile for a user, check to see if a profile already exists by running the /v1/detection-lists/user/getbyusername API or /v1/detection-lists/user/getbyid API. If a profile already exists, attempting to create a profile for the user results in an error.

To create a detection list profile, use the /v1/detection-lists/user/create API command as shown in the following example.

curl -X POST <requestURL>/v1/detection-lists/user/create \
-H 'content-type: application/json' \
-H "authorization: Bearer <AuthToken>" \
-d '{"tenantId": "<SampleTenant>", "userName": "<Code42Username>", "notes": "This is an example user note.", "riskFactors": ["FLIGHT_RISK", "HIGH_IMPACT_EMPLOYEE"], "cloudUsernames": ["<UsernameInCloudService>"]}'

In the preceding example:

An excerpt of an example successful response:

{
  "type$": "USER_V2",
  "tenantId": "1233456",
  "userId": "123456789424242",
  "userName": "john.doe@example.com",
  "displayName": "John Doe",
  "notes": "This is an example user note.",
  "cloudUsernames": [
    "john.doe@gmail.com",
    "john.doe@example.com"
  ],
  "riskFactors": [
    "FLIGHT_RISK",
    "HIGH_IMPACT_EMPLOYEE"
  ]
}

Get the detection list profile for a user

If you need to get a user's detection list profile to find information about the user, use the /v1/detection-lists/user/getbyusername API or /v1/detection-lists/user/getbyid API.

For example, if you don't know a user's ID, you can find it by running the /v1/detection-lists/user/getbyusername API command as shown in the following example.

curl -X POST <requestURL>/v1/detection-lists/user/getbyusername \
-H 'content-type: application/json' \
-H "authorization: Bearer <AuthToken>" \
-d '{ "tenantId": "<SampleTenant>", "username": "<Code42Username>"}'

In the preceding example:

A successful response returns the user ID and other information:

{"type$":"USER_V2","tenantId":"123456","userId":"123456789424242","userName":"john.doe@example.com","displayName":"John Doe","notes":"This is an example user note.","cloudUsernames":["john.doe@gmail.com","john.doe@example.com"],"riskFactors":["FLIGHT_RISK","HIGH_IMPACT_EMPLOYEE"]}

Some available actions

Following are some of the actions you can perform using the High Risk Employee APIs and Departing Employee APIs.

Add a user to a detection list

You can add a user to the High Risk Employees list using the /v1/detection-lists/highriskemployee/add API or add a user to the Departing Employees list using the /v1/detection-lists/departingemployee/add API.

Note: To add multiple users at once, see the Code42 command-line interface.

Add a high risk employee

The following example demonstrates how to add a user to the High Risk Employees list using the /v1/detection-lists/highriskemployee/add API.

curl -X POST <RequestURL>/v1/detection-lists/highriskemployee/add \
-H 'content-type: application/json' \
-H "authorization: Bearer <AuthToken>" \
-d '{ "tenantId": "<SampleTenant>", "userId": "<ID>" }'

In the preceding example:

An excerpt of an example successful response:

{
  "type$": "HIGH_RISK_EMPLOYEE_V2",
  "tenantId": "123456",
  "userId": "123456789424242",
  "userName": "john.doe@example.com",
  "displayName": "John Doe",
  "notes": "This is an example user note.",
  "createdAt": "2020-03-31T19:35:49.4400509Z",
  "status": "OPEN",
  "cloudUsernames": [
    "john.doe@gmail.com",
    "john.doe@example.com"
  ],
  "riskFactors": [
    "FLIGHT_RISK",
    "HIGH_IMPACT_EMPLOYEE"
  ]
}

Add a departing employee

The following example demonstrates how to add a user to the Departing Employees list using the /v1/detection-lists/departingemployee/add API.

curl -X POST <RequestURL>/v1/detection-lists/departingemployee/add \
-H 'content-type: application/json' \
-H "authorization: Bearer <AuthToken>" \
-d '{ "tenantId": "<SampleTenant>", "userId": "<ID>", "departureDate": "<Date>" }'

In the preceding example:

An excerpt of an example successful response:

{
  "type$": "DEPARTING_EMPLOYEE_V2",
  "tenantId": "123456",
  "userId": "123456789424242",
  "userName": "john.doe@example.com",
  "displayName": "John Doe",
  "notes": "This is an example of a user note.",
  "createdAt": "2020-03-31T19:22:18.5651922Z",
  "status": "OPEN",
  "cloudUsernames": [
    "john.doe@gmail.com",
    "john.doe@example.com"
  ],
  "departureDate": "2020-04-07"
}

Obtain a listing of all users in a detection list

You can obtain a list of all users in the High Risk Employees list using the /v1/detection-lists/highriskemployee/search API , or obtain a list of all users in the Departing Employees list using the /v1/detection-lists/departingemployee/search API.

Obtain a list of high risk employees

Obtain a list of high risk employees in Code42 by running the /v1/detection-lists/highriskemployee/search API.

curl -X POST <RequestURL>/v1/detection-lists/highriskemployee/search  \
-H 'content-type: application/json' \
-H "authorization: Bearer <AuthToken>" \
-d '{ "tenantId": "<SampleTenant>", "filterType": "OPEN", "pgSize": "20", "pgNum": "1", "srtKey": "DISPLAY_NAME", "srtDirection": "ASC" }'

In the preceding example:

An excerpt of an example successful response:

{
  "type$": "HIGH_RISK_SEARCH_RESPONSE_V2",
  "items": [
    {
      "type$": "HIGH_RISK_EMPLOYEE_V2",
      "tenantId": "123456",
      "userId": "123456789424242",
      "userName": "john.doe@example.com",
      "displayName": "John Doe",
      "notes": "This is an example note.",
      "createdAt": "2020-03-31T19:35:49.4400500Z",
      "status": "OPEN",
      "cloudUsernames": [
        "john.doe@gmail.com",
        "john.doe@example.com"
      ],
      "riskFactors": [
        "FLIGHT_RISK",
        "HIGH_IMPACT_EMPLOYEE"
      ]
    },
    {
      "type$": "HIGH_RISK_EMPLOYEE_V2",
      "tenantId": "123456",
      "userId": "987654321424242",
      "userName": "jane.smith@example.com",
      "displayName": "Jane Smith",
      "notes": "This is an example note.",
      "createdAt": "2020-03-31T19:45:30.3092900Z",
      "status": "OPEN",
      "cloudUsernames": [
        "jane.smith@gmail.com",
        "jane.smith@example.com"
      ],
      "managerUid": "Jack.Shep",
      "managerUsername": "Jack.Shep@example.com",
      "managerDisplayName": "Jack Shep",
      "title": "People Person",
      "division": "Acme",
      "department": "Human Resources",
      "employmentType": "Full Time",
      "city": "The Island",
      "state": "MN",
      "country": "US",
      "riskFactors": [
        "FLIGHT_RISK",
        "HIGH_IMPACT_EMPLOYEE"
      ]
    }
  ],
  "totalCount": 2,
  "rollups": [
    {
      "type$": "HIGH_RISK_FILTER_ROLLUP_V2",
      "filterType": "OPEN",
      "totalCount": 2
    },
    {
      "type$": "HIGH_RISK_FILTER_ROLLUP_V2",
      "filterType": "EXFILTRATION_24_HOURS",
      "totalCount": 0
    },
    {
      "type$": "HIGH_RISK_FILTER_ROLLUP_V2",
      "filterType": "EXFILTRATION_30_DAYS",
      "totalCount": 0
    }
  ],
  "filterType": "OPEN",
  "pgSize": 20,
  "pgNum": 1,
  "srtKey": "DISPLAY_NAME",
  "srtDirection": "ASC"
}

Obtain a list of departing employees

Obtain a list of departing employees in Code42 by running the /v1/detection-lists/departingemployee/search API.

curl -X POST <RequestURL>/v1/detection-lists/departingemployee/search  \
-H 'content-type: application/json' \
-H "authorization: Bearer <AuthToken>" \
-d '{ "tenantId": "<SampleTenant>", "filterType": "OPEN", "pgSize": "20", "pgNum": "1", "srtKey": "DISPLAY_NAME", "srtDirection": "ASC" }'

In the preceding example:

An excerpt of an example successful response:

{
  "type$": "DEPARTING_EMPLOYEE_SEARCH_RESPONSE_V2",
  "items": [
    {
      "type$": "DEPARTING_EMPLOYEE_V2",
      "tenantId": "123456",
      "userId": "123456789424242",
      "userName": "john.doe@example.com",
      "displayName": "John Doe",
      "notes": "This is an example user note.",
      "createdAt": "2020-03-31T19:22:18.5651920Z",
      "status": "OPEN",
      "cloudUsernames": [
        "john.doe@gmail.com",
        "john.doe@example.com"
      ],
      "departureDate": "2020-04-07"
    }
  ],
  "totalCount": 1,
  "rollups": [
    {
      "type$": "DEPARTING_EMPLOYEE_FILTER_ROLLUP_V2",
      "filterType": "OPEN",
      "totalCount": 1
    },
    {
      "type$": "DEPARTING_EMPLOYEE_FILTER_ROLLUP_V2",
      "filterType": "LEAVING_TODAY",
      "totalCount": 0
    },
    {
      "type$": "DEPARTING_EMPLOYEE_FILTER_ROLLUP_V2",
      "filterType": "EXFILTRATION_24_HOURS",
      "totalCount": 0
    },
    {
      "type$": "DEPARTING_EMPLOYEE_FILTER_ROLLUP_V2",
      "filterType": "EXFILTRATION_30_DAYS",
      "totalCount": 0
    }
  ],
  "filterType": "OPEN",
  "pgSize": 20,
  "pgNum": 1,
  "srtKey": "DISPLAY_NAME",
  "srtDirection": "ASC"
}

View details of a user in a detection list

You can view details of a user in the High Risk Employees list using the /v1/detection-lists/highriskemployee/get API, or view details of a user in the Departing Employees list using the /v1/detection-lists/departingemployee/get API.

The commands to view the details of high risk or departing employee are similar. The following example shows how to view the details of a high risk employee using the /v1/detection-lists/highriskemployee/get API.

curl -X POST <RequestURL>/v1/detection-lists/highriskemployee/get \
-H 'content-type: application/json' \
-H "authorization: Bearer <AuthToken>" \
-d '{ "tenantId": "<SampleTenant>", "userId": "<ID>" }'

In the preceding example:

An excerpt of an example successful response:

{
  "type$": "HIGH_RISK_EMPLOYEE_V2",
  "tenantId": "123456",
  "userId": "123456789424242",
  "userName": "john.doe@example.com",
  "displayName": "John Doe",
  "notes": "This is an example note.",
  "createdAt": "2020-03-31T19:35:49.4400500Z",
  "status": "OPEN",
  "cloudUsernames": [
    "john.doe@gmail.com",
    "john.doe@example.com"
  ],
  "riskFactors": [
    "FLIGHT_RISK",
    "HIGH_IMPACT_EMPLOYEE"
  ]
}

Enable or disable alerts for all users in a detection list

You can enable or disable alerts for all users in a detection list using the /v1/detection-lists/highriskemployee/setalertstate API or the /v1/detection-lists/departingemployee/setalertstate API.

The commands to enable or disable alerts for all high risk or departing employees are similar. The following example shows how to enable alerts for all high risk employees using the /v1/detection-lists/highriskemployee/setalertstate API.

curl -X POST <RequestURL>/v1/detection-lists/highriskemployee/setalertstate \
-H 'content-type: application/json' \
-H "authorization: Bearer <AuthToken>" \
-d '{ "tenantId": "<SampleTenant>", "alertsEnabled": true }'

In the preceding example:

To disable alerts, run the command with the alertsEnabled value set to false.

To verify that the alerts setting is changed as desired, select Alert Settings in the High Risk Employees list or Departing Employees list in the Code42 console.

Remove a user from a detection list

You can remove a user from the High Risk Employees list using the /v1/detection-lists/highriskemployee/remove API, or remove a user froom the Departing Employees list using the /v1/detection-lists/departingemployee/remove API.

Note: To remove multiple users at once, see the Code42 command-line interface.

The commands to remove a user from the High Risk Employees or Departing Employees lists are similar. The following example shows how to remove a user from the High Risk Employees list using the /v1/detection-lists/highriskemployee/remove API.

curl -X POST <RequestURL>/v1/detection-lists/highriskemployee/remove \
-H 'content-type: application/json' \
-H "authorization: Bearer <AuthToken>" \
-d '{ "tenantId": "<SampleTenant>", "userId": "<ID>" }'

In the preceding example:

To verify that the user is removed, generate a listing of all users in the detection list as shown in Obtain a listing of all users in a detection list.