Devices

Find device documents by document type

Get a list of documents for a given device and document type

🔒 Requires Devices: Manage Device Documents permission.

Securitybearer
Request
path Parameters
deviceId
required
number
query Parameters
type
string (DeviceDocumentTypeEnum)

Filter documents by their type

Enum: "PASSWORD_MANAGER_EVIDENCE" "AUTO_UPDATES_EVIDENCE" "HARD_DRIVE_ENCRYPTION_EVIDENCE" "ANTIVIRUS_EVIDENCE" "LOCK_SCREEN_EVIDENCE"
Responses
200
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

412

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

500

Internal server error

get/devices/{deviceId}/documents
Request samples
Response samples
application/json
{}

Upload device compliance document by device id

Upload a new device document for a given device

🔒 Requires Devices: Manage Device Documents permission.

Securitybearer
Request
path Parameters
deviceId
required
number
Request Body schema:
required
type
required
string

The device document type

Enum: "PASSWORD_MANAGER_EVIDENCE" "AUTO_UPDATES_EVIDENCE" "HARD_DRIVE_ENCRYPTION_EVIDENCE" "ANTIVIRUS_EVIDENCE" "LOCK_SCREEN_EVIDENCE"
file
string <binary>

Accepted file extensions: .pdf, .docx, .odt, .xlsx, .ods, .pptx, .odp, .gif, .jpeg, .jpg, .png

base64File
string

JSON string with external evidence in Base64 format.

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/devices/{deviceId}/documents
Request samples
No sample
Response samples
application/json
{}

Delete a Device Document

Removes a specific device document using the provided document ID

🔒 Requires Devices: Manage Device Documents permission.

Securitybearer
Request
path Parameters
documentId
required
number
Responses
200

Successful

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

500

Internal server error

delete/devices/documents/{documentId}
Request samples
Response samples
application/json
{
  • "statusCode": 0,
  • "message": "string",
  • "code": 0,
  • "debugInfo": {
    • "name": "string",
    • "message": "string",
    • "stack": "string"
    }
}

Get device document signed download URL

Get device document download URL by document ID

🔒 Requires Devices: Manage Device Documents permission.

Securitybearer
Request
path Parameters
documentId
required
number
Responses
200
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

500

Internal server error

get/devices/documents/{documentId}/download
Request samples
Response samples
application/json
{}

Get a list of devices

🔒 Requires Devices: List Devices permission.

Securitybearer
Request
query Parameters
page
number >= 1
Default: 1

Which page of data are you requesting

limit
number [ 1 .. 50 ]
Default: 20

How many items are you requesting

externalId
string <= 191 characters

An externally sourced unique identifier for a device

expand[]
Array of strings

List of subcollections and sub-objects to expand

Items Enum: "asset" "complianceChecks" "documents" "identifiers"
Example: expand[]=COMPLIANCE_CHECKS
macAddress
string

The device MAC address

Example: macAddress=65-F9-3D-85-7B-6B,99-A9-3E-14-7A-3E
serialNumber
string

The device serial number

Example: serialNumber=NKRTSPY456
sourceType
string

Device source type

Enum: "AGENT" "JAMF" "INTUNE" "KANDJI" "JUMPCLOUD" "HEXNODE_UEM" "UNKNOWN" "RIPPLING" "WORKSPACE_ONE" "KOLIDE" "CUSTOM" "INTUNE_GCC_HIGH"
Example: sourceType=AGENT
personnelId
number

Personnel Id

Responses
200
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

412

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

500

Internal server error

get/devices
Request samples
Response samples
application/json
{
  • "data": [
    • {
      • "externalId": "3000",
      • "personnelId": 206,
      • "userId": 207,
      • "id": 3,
      • "osVersion": "MacOS 11",
      • "serialNumber": "q77gfdp0xg03vcu6t1fi",
      • "model": "MacBook Pro 14-in(2021)",
      • "macAddress": "91:2b:4a:7a:51:73",
      • "encryptionEnabled": null,
      • "firewallEnabled": null,
      • "gateKeeperEnabled": null,
      • "lastCheckedAt": "2024-11-25T22:16:23.479Z",
      • "sourceType": "AGENT",
      • "createdAt": "2024-11-25T22:16:23.479Z",
      • "updatedAt": "2024-12-08T22:20:15.041Z",
      • "deletedAt": null,
      • "appsCount": null
      },
    • {
      • "externalId": "4000",
      • "personnelId": 305,
      • "userId": 306,
      • "id": 4,
      • "osVersion": "MacOS 12",
      • "serialNumber": "locldk8eyxn28eyb3ktj",
      • "model": "MacBook Pro 16-in(2021)",
      • "macAddress": "0f:8a:67:b2:90:ad",
      • "encryptionEnabled": null,
      • "firewallEnabled": null,
      • "gateKeeperEnabled": null,
      • "lastCheckedAt": "2024-11-25T22:16:23.705Z",
      • "sourceType": "AGENT",
      • "createdAt": "2024-11-25T22:16:23.705Z",
      • "updatedAt": "2024-12-08T22:20:15.041Z",
      • "deletedAt": null,
      • "appsCount": null
      }
    ],
  • "page": 1,
  • "limit": 10,
  • "total": 100
}

Get a list of devices for a given personnel item

🔒 Requires Devices: List Devices permission.

Securitybearer
Request
path Parameters
personnelId
required
number
query Parameters
page
number >= 1
Default: 1

Which page of data are you requesting

limit
number [ 1 .. 50 ]
Default: 20

How many items are you requesting

externalId
string <= 191 characters

An externally sourced unique identifier for a device

expand[]
Array of strings

List of subcollections and sub-objects to expand

Items Enum: "asset" "complianceChecks" "documents" "identifiers"
Example: expand[]=COMPLIANCE_CHECKS
macAddress
string

The device MAC address

Example: macAddress=65-F9-3D-85-7B-6B,99-A9-3E-14-7A-3E
serialNumber
string

The device serial number

Example: serialNumber=NKRTSPY456
sourceType
string

Device source type

Enum: "AGENT" "JAMF" "INTUNE" "KANDJI" "JUMPCLOUD" "HEXNODE_UEM" "UNKNOWN" "RIPPLING" "WORKSPACE_ONE" "KOLIDE" "CUSTOM" "INTUNE_GCC_HIGH"
Example: sourceType=AGENT
Responses
200
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

500

Internal server error

get/personnel/{personnelId}/devices
Request samples
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"
}

Get a specific device

🔒 Requires Devices: List Devices permission.

Securitybearer
Request
path Parameters
deviceId
required
number

The device ID

query Parameters
expand[]
Array of strings

List of subcollections and sub-objects to expand

Items Enum: "asset" "complianceChecks" "documents" "identifiers" "deviceApps"
Example: expand[]=COMPLIANCE_CHECKS
Responses
200
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

412

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

500

Internal server error

get/devices/{deviceId}
Request samples
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",
  • "apps": [ ]
}

Get a list of devices for a given connection

🧪 BETA: Get a list of devices for a given connection

🔒 Requires Devices: List Devices 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.

query Parameters
page
number >= 1
Default: 1

Which page of data are you requesting

limit
number [ 1 .. 50 ]
Default: 20

How many items are you requesting

externalId
string <= 191 characters

An externally sourced unique identifier for a device

expand[]
Array of strings

List of subcollections and sub-objects to expand

Items Enum: "asset" "complianceChecks" "documents" "identifiers"
Example: expand[]=COMPLIANCE_CHECKS
macAddress
string

The device MAC address

Example: macAddress=65-F9-3D-85-7B-6B,99-A9-3E-14-7A-3E
serialNumber
string

The device serial number

Example: serialNumber=NKRTSPY456
personnelId
number

Personnel Id

Responses
200
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

500

Internal server error

get/custom-connections/{connectionId}/devices
Request samples
Response samples
application/json
{
  • "data": [
    • {
      • "externalId": "3000",
      • "personnelId": 206,
      • "userId": 207,
      • "id": 3,
      • "osVersion": "MacOS 11",
      • "serialNumber": "q77gfdp0xg03vcu6t1fi",
      • "model": "MacBook Pro 14-in(2021)",
      • "macAddress": "91:2b:4a:7a:51:73",
      • "encryptionEnabled": null,
      • "firewallEnabled": null,
      • "gateKeeperEnabled": null,
      • "lastCheckedAt": "2024-11-25T22:16:23.479Z",
      • "sourceType": "AGENT",
      • "createdAt": "2024-11-25T22:16:23.479Z",
      • "updatedAt": "2024-12-08T22:20:15.041Z",
      • "deletedAt": null,
      • "appsCount": null
      },
    • {
      • "externalId": "4000",
      • "personnelId": 305,
      • "userId": 306,
      • "id": 4,
      • "osVersion": "MacOS 12",
      • "serialNumber": "locldk8eyxn28eyb3ktj",
      • "model": "MacBook Pro 16-in(2021)",
      • "macAddress": "0f:8a:67:b2:90:ad",
      • "encryptionEnabled": null,
      • "firewallEnabled": null,
      • "gateKeeperEnabled": null,
      • "lastCheckedAt": "2024-11-25T22:16:23.705Z",
      • "sourceType": "AGENT",
      • "createdAt": "2024-11-25T22:16:23.705Z",
      • "updatedAt": "2024-12-08T22:20:15.041Z",
      • "deletedAt": null,
      • "appsCount": null
      }
    ],
  • "page": 1,
  • "limit": 10,
  • "total": 100
}

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"
}

Get device apps

Get a list of apps associated with a given device

🔒 Requires Devices: List Devices permission.

Securitybearer
Request
path Parameters
deviceId
required
number

The device ID

query Parameters
page
number >= 1
Default: 1

Which page of data are you requesting

limit
number [ 1 .. 50 ]
Default: 20

How many items are you requesting

Responses
200
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

412

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

500

Internal server error

get/devices/{deviceId}/apps
Request samples
Response samples
application/json
{
  • "data": [
    • {
      • "id": 242,
      • "installedApp": "Photoshop version 26.0 license 1a2b3c"
      },
    • {
      • "id": 243,
      • "installedApp": "Microsoft Word version 2411 (Build 18227.20162) license 9w9e8b"
      }
    ],
  • "page": 1,
  • "limit": 10,
  • "total": 100
}