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

🧪 BETA: 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.

🔒 Requires Devices: Create Device permission.

Securitybearer
Request
path Parameters
connectionId
required
number

The ID of the connection may be obtained in one of two ways:

  • Calling GET /connections and noting the id of the desired custom device connection in the response.
  • In the Drata App:

    • New Device Connection

      1. Navigate to Connections > MDM.
      2. Select the Available Connections tab.
      3. Chose Custom Device Connection.

      After successfully creating a device connection, the connection ID will be displayed under Account Information.

    • Existing Device Connection

      1. Navigate to Connections > MDM.
      2. Select the Active Connections tab.
      3. View a previously created custom device connection.

      The connection ID will be displayed under Account Information.

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

You must upgrade your plan to use this feature

403

You are not allowed to perform this action

404

Not Found

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": "aaaaaaaa-bbbb-0000-cccc-dddddddddddd",
  • "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": "2025-07-01T16:45:55.246Z",
  • "sourceType": "AGENT",
  • "createdAt": "2025-07-01T16:45:55.246Z",
  • "updatedAt": "2025-07-01T16:45:55.246Z",
  • "deletedAt": "2025-07-01T16:45:55.246Z",
  • "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"
}