Create a new device or update an existing device for a custom connection

Create a new device or update an existing device for a custom connection.

An existing device is searched for based upon matching one or more of these supplied properties in the request payload:

  • serialNumber
  • macAddress
  • externalId

If an existing device is found, the existing device is updated. Otherwise a new device is created.

Securitybearer
Request
path Parameters
connectionId
required
number
Request Body schema: application/json
required
personnelId
required
number

Personnel Id

alias
string <= 191 characters

Name of the device.

antivirusEnabled
boolean or null

Flag to indicate antivirus software is installed and enabled

antivirusExplanation
object

Any additional information to explain the antivirusEnabled value

Array of objects (AppTypeRequestPublicDto)

List of installed applications

autoUpdateEnabled
boolean or null

Flag to indicate auto-update enabled or disabled

autoUpdateExplanation
object

Any additional information to explain the autoUpdateEnabled value

Array of objects (AppTypeRequestPublicDto)

List of installed browser extensions

externalId
string

An externally-sourced unique identifier for a device

firewallEnabled
boolean or null

Flag to indicate the firewall is enabled or disabled

firewallExplanation
object

Any additional information to explain the firewallEnabled value

passwordManagerEnabled
boolean or null

Flag to indicate a password manager is in use

encryptionEnabled
boolean or null

Flag to indicate hard disk is encrypted

encryptionExplanation
object

Any additional information to explain the encryptionEnabled value

model
string <= 191 characters

Hardware model

serialNumber
string

Hardware serial number

macAddress
string or null

MAC address

passwordManagerExplanation
object

Any additional information to explain the hasPasswordManager value

platformName
required
string

The Operating System (OS) platform name of the device

Enum: "MACOS" "WINDOWS" "LINUX" "UNIX" "ANDROID"
platformVersion
required
string <= 191 characters

The Operating System (OS) platform version of the device

screenLockEnabled
boolean or null

Flag to indicate hard disk is encrypted

screenLockExplanation
object

Any additional information to explain the screenLockTime value

screenLockTime
number

Amount of time before display is turned off

Array of objects (WindowsServiceRequestPublicDto)

List of applicable Windows services

Responses
201
400

Malformed data and/or validation errors

401

Invalid Authorization

402

Response Code 402

You must pay to activate this feature

403

You are not allowed to perform this action

404

Record Not Found

412

Response Code: 412

You must accept the Drata terms and conditions to use the API

413

The file was too large to upload

500

Internal server error

503

Third party system was unavailable

post/custom-connections/{connectionId}/devices
Request samples
application/json
{
  • "personnelId": 1,
  • "alias": "danielm-01",
  • "antivirusEnabled": true,
  • "antivirusExplanation": {
    • "antivirusApps": [
      • "Crowdstrike windows sensor"
      ]
    },
  • "appList": [
    • {
      • "name": "Microsoft Defender Antivirus",
      • "version": "1.421.12.0",
      • "description": "Microsoft Defender Antivirus"
      }
    ],
  • "autoUpdateEnabled": true,
  • "autoUpdateExplanation": "Disabled",
  • "browserExtensions": [
    • {
      • "name": "Microsoft Defender Antivirus",
      • "version": "1.421.12.0",
      • "description": "Microsoft Defender Antivirus"
      }
    ],
  • "externalId": "9c6bb78e-ac41-471e-9e95-28b0565ea620",
  • "firewallEnabled": true,
  • "firewallExplanation": "On",
  • "passwordManagerEnabled": true,
  • "encryptionEnabled": true,
  • "encryptionExplanation": {
    • "bootPartitionEncryptionDetails": {
      • "partitionFileVault2Percent": 100,
      • "partitionFileVault2State": "ENCRYPTED",
      • "partitionName": "Macintosh HD (Boot Partition)"
      }
    },
  • "model": "Mac16,1",
  • "serialNumber": "BKH8RXT4T9",
  • "macAddress": "01-23-45-67-89-AB",
  • "passwordManagerExplanation": {
    • "passwordManagerApps": [
      • "1password"
      ]
    },
  • "platformName": "MACOS",
  • "platformVersion": "string",
  • "screenLockEnabled": true,
  • "screenLockExplanation": "ScreenLock delay is immediate",
  • "screenLockTime": 15,
  • "windowsServices": [
    • {
      • "description": "Security feature that monitors and controls network traffic entering and exiting the device",
      • "name": "Windows Firewall",
      • "startType": "Automatic",
      • "status": "Running"
      }
    ]
}
Response samples
application/json
{
  • "id": 1,
  • "osVersion": "MacOS 10.15.6",
  • "serialNumber": "C02T6CDJGTFL",
  • "model": "MacBook Pro",
  • "macAddress": "65-F9-3D-85-7B-6B,99-A9-3E-14-7A-3E",
  • "encryptionEnabled": false,
  • "encryptionExplanation": "No encryption provided",
  • "firewallEnabled": true,
  • "firewallExplanation": "{}",
  • "lastCheckedAt": "2020-07-06 12:00:00.000000",
  • "sourceType": "AGENT",
  • "createdAt": "2020-07-06 12:00:00.000000",
  • "updatedAt": "2020-07-06 12:00:00.000000",
  • "deletedAt": "2020-07-06 12:00:00.000000",
  • "appsCount": 20,
  • "complianceChecks": [ ],
  • "identifiers": [ ],
  • "documents": [ ],
  • "isDeviceCompliant": false,
  • "screenLockTime": 30,
  • "screenLockExplanation": {
    • "minutesIdleBeforeSleep": "2",
    • "minutesSleepingBeforePasswordIsRequired": "2"
    },
  • "antivirusEnabled": true,
  • "antivirusExplanation": "No matching app was found",
  • "autoUpdateEnabled": true,
  • "autoUpdateExplanation": "No compliances found",
  • "passwordManagerEnabled": true,
  • "passwordManagerExplanation": {
    • "passwordManagerApps": [
      • "1password 7"
      ]
    },
  • "asset": {
    • "id": 651,
    • "name": "MacBook Pro - Space Black 16-inch",
    • "description": "MacBook Pro Space Black - with 16-inch Liquid Retina XDR display",
    • "assetType": "PHYSICAL",
    • "assetProvider": "AGENT",
    • "removedAt": null,
    • "notes": null,
    • "assetReferenceType": "WORKSTATION",
    • "externalId": null,
    • "externalOwnerId": null,
    • "uniqueId": "zgf5nl7bie2qnw0z2xxx",
    • "createdAt": "2025-01-08T21:31:55.610Z",
    • "updatedAt": "2025-01-08T21:31:55.610Z"
    },
  • "userId": 1,
  • "personnelId": 1,
  • "externalId": "aaaaaaaa-bbbb-0000-cccc-dddddddddddd"
}