Add reference information to agents, users, and organizations

Updated May 15, 2025 18:52

Overview

Reference fields allow you to add descriptive information to agents, users, and organizations in your environment. This descriptive information can be used to add context for administrators, and also to integrate with external systems.

This article describes how to use the reference fields from both the Incydr console and the Incydr API.

Reference fields

The following reference fields are available:

External Reference: Intended for optional external reference information, such as a serial number, asset tag, employee ID, or help desk issue ID.
Notes: Intended for optional descriptive information.

Considerations

The examples in this article use the command-line tool curl to interact with the Incydr API. For a list of tools that can be used to interact with the API, see Tools for interacting with the Incydr API.

Use the Incydr console to edit reference information

Organizations, users, and insider risk agents

Sign in to the Incydr console.
From Administration > Environment, select Organizations, Users, or Agents.
Click the name of the organization, agent, or user.
Click Reference to view any existing reference information.
Click Edit to add or update reference information.
- Use External reference to record optional external reference information like serial numbers, asset tags, or employee IDs.
- Enter any Notes about the agent or user.
- Click Save to save your changes.

Backup agent

Sign in to the Incydr console.
From Administration > Environment, select Agents.
Click the name of a backup agent.
Select Actions > Edit device backup defaults.
Click Reference.
Add details to one or both reference fields.
Click Save.

Use the Incydr API to add reference information

Consider using the Incydr API to add reference information if you need to:

Add reference information for many agents, users, or organizations in your environment via scripting.
Configure an external system in your environment to automatically set reference information.

The examples below illustrate how to set the reference information for one user, agent, or organization at a time. If you want to set values for many items at once, use the examples as the basis for a custom script. In the examples below:

Replace console.us.code42.com with the base URL you use to access your Incydr cloud instance.
Replace <auth_token> with an authentication token.

Incydr Developer Portal
See the Developer Portal for more API documentation and resources. The portal provides:

A single access point for documentation of methods for Incydr, including the REST API, Incydr SDK, and command-line interface (CLI)
A single request URL for API calls to each cloud instance
API reference documentation

Use the Developer Portal for your API needs as much as possible. APIs in the portal are the preferred way to integrate with Incydr. If you use APIs that do not appear on the Developer Portal, contact our Technical Support Engineers for guidance on the best way to integrate with Incydr.

Use the Incydr API to add reference information for an agent

Applies to the backup agent only

The Incydr API Computer resource allows you to set the computerExtRef and notes parameters for a device.

Find a device's guid using one of these methods:

Search by the userUid of the user that owns the device:

curl -X GET 'https://console.us.code42.com/api/v1/Computer?userUid=<userUid>' -H 'Authorization: Bearer <auth_token>' | python3 -mjson.tool

Search for the device by name:

curl -X GET 'https://console.us.code42.com/api/v1/Computer?q=<name>' -H 'Authorization: Bearer <auth_token>' | python3 -mjson.tool

Locate the device's guid in the output. For example:
```
"guid": "681099810721783680"
```

Set the computerExtRef and notes parameters for the appropriate device guid:

curl -X PUT -d '{ "computerExtRef": "Asset 410", "notes": "A note about the device" }' -H 'Content-Type: application/json' 'https://console.us.code42.com/api/v1/Computer/<guid>?idType=guid' -H 'Authorization: Bearer <auth_token>' | python3 -mjson.tool

Examine the output of the command to verify that computerExtRef and notes contain the correct values.

Use the Incydr API to add reference information for a user

The Incydr API User resource allows you to set the userExtRef and notes parameters for a user.

Find a user's userUid using one of these methods:

Search for the user by email address:

curl -X GET 'https://console.us.code42.com/api/v1/User?email=<email_address>' -H 'Authorization: Bearer <auth_token>' | python3 -mjson.tool

Search for the user by username:

curl -X GET 'https://console.us.code42.com/api/v1/User?username=<username>' -H 'Authorization: Bearer <auth_token>' | python3 -mjson.tool

Search for the user by first and last name:

curl -X GET 'https://console.us.code42.com/api/v1/User?q=<firstname>&&<lastname>' -H 'Authorization: Bearer <auth_token>' | python3 -mjson.tool

Locate the user's userUid in the output. For example:
```
"userUid": "fa1633c3e5507360"
```

Set the userExtRef and notes parameters for the appropriate userUid:

curl -X PUT -d '{ "userExtRef": "ID040189", "notes": "A note about the user" }' -H 'Content-Type: application/json' 'https://console.us.code42.com/api/v1/User/<userUid>?idType=uid' -H 'Authorization: Bearer <auth_token>' | python3 -mjson.tool

Examine the output of the command to verify that userExtRef and notes contain the correct values.

Use the Incydr API to add reference information for an organization

The Incydr API Org resource allows you to set the orgExtRef and notes parameters for an organization.

Find the organization's orgUid by searching for its name:

curl -X GET 'https://console.us.code42.com/api/v1/Org?q=<organization_name>' -H 'Authorization: Bearer <auth_token>' | python3 -mjson.tool

Locate the organization's orgUid in the output. For example:
```
"orgUid": "691968598454770525"
```

Set the orgExtRef and notes parameters for the appropriate orgUid:

curl -X PUT -d '{ "orgExtRef": "An organization identifier", "notes": "A note about this organization" }' -H 'Content-Type: application/json' 'https://console.us.code42.com/api/v1/Org/<orgUid>?idType=orgUid' -H 'Authorization: Bearer <auth_token>' | python3 -mjson.tool

Examine the output of the command to verify that orgExtRef and notes contain the correct values.