Custom Connections

Custom Connections allow users to integrate external systems with Drata. This includes Custom Data connections for pushing JSON evidence and Custom Device connections for device management and monitoring

Create Custom Connection

Create a new Custom Connection. Currently, only Custom Device connections are supported.

🔒 Requires Custom Connections Data: Create Custom Connection Data permission.

💎 Requires your account have the Custom Connections and Tests feature. Contact your CSM for help upgrading.

Securitybearer
Request
Request Body schema: application/json
required
name
required
string

Name for the Custom Connection

providerTypes
required
Array of strings

Provider types for the Custom Connection. Currently only MDM is supported.

Items Value: "MDM"
Responses
201

Created

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

post/custom-connections
Request samples
application/json
{
  • "name": "My Custom Connection",
  • "providerTypes": [
    • "MDM"
    ]
}
Response samples
application/json
{
  • "id": 1,
  • "clientAlias": "My Custom Connection",
  • "description": "Custom connection for managing Employee Data",
  • "providerTypes": [
    • "MDM"
    ],
  • "createdAt": "2025-07-01T16:45:55.246Z",
  • "updatedAt": "2025-07-01T16:45:55.246Z",
  • "createdById": 1,
  • "createdByUser": {
    • "id": 1,
    • "email": "[email protected]",
    • "firstName": "Sally",
    • "lastName": "Smith",
    • "createdAt": "2025-07-01T16:45:55.246Z",
    • "updatedAt": "2025-07-01T16:45:55.246Z"
    }
}

List Custom Connections

Find Custom Connections matching the provided filters.

🔒 Requires Custom Connections Data: List Custom Connections permission.

💎 Requires your account have the Custom Connections and Tests feature. Contact your CSM for help upgrading.

Securitybearer
Request
query Parameters
cursor
string

This parameter is used to paginate through results. No value is needed for the first request. If there are additional results, the response will contain a pagination.cursor value that can be used in the subsequent request to retrieve the next page of results

size
number [ 1 .. 50 ]
Default: 20

Number of results to return

sort
string (SortTypeLimitedEnum)

Which field to sort by

Enum: "createdAt" "updatedAt"
sortDir
string (SortDirectionEnum)

The direction to sort the data

Enum: "ASC" "DESC"
expand[]
Array of strings (CustomConnectionExpandEnum)

List of subcollections and sub-objects to expand

Items Value: "createdByUser"
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/custom-connections
Request samples 
Response samples 
application/json
{
  • "data": [
    • {
      • "id": 1,
      • "clientAlias": "My Custom Connection",
      • "description": "Custom connection for managing Employee Data",
      • "providerTypes": [
        • "MDM"
        ],
      • "createdAt": "2025-07-01T16:45:55.246Z",
      • "updatedAt": "2025-07-01T16:45:55.246Z",
      • "createdById": 1,
      • "createdByUser": {
        • "id": 1,
        • "email": "[email protected]",
        • "firstName": "Sally",
        • "lastName": "Smith",
        • "createdAt": "2025-07-01T16:45:55.246Z",
        • "updatedAt": "2025-07-01T16:45:55.246Z"
        }
      }
    ],
  • "pagination": {
    • "cursor": "string"
    }
}
Get Custom Connection
🔒 Requires Custom Connections Data: List Custom Connections permission.


💎 Requires your account have the Custom Connections and Tests feature. Contact your CSM for help upgrading.


Securitybearer 
Request 
path Parameters
connectionId
required
number
 
query Parameters
expand[]
Array of strings (CustomConnectionExpandEnum) 
List of sub-collections and sub-objects to expand


Items Value: "createdByUser"  
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}
Request samples 
Response samples 
application/json
{
  • "id": 1,
  • "clientAlias": "My Custom Connection",
  • "description": "Custom connection for managing Employee Data",
  • "providerTypes": [
    • "MDM"
    ],
  • "createdAt": "2025-07-01T16:45:55.246Z",
  • "updatedAt": "2025-07-01T16:45:55.246Z",
  • "createdById": 1,
  • "createdByUser": {
    • "id": 1,
    • "email": "[email protected]",
    • "firstName": "Sally",
    • "lastName": "Smith",
    • "createdAt": "2025-07-01T16:45:55.246Z",
    • "updatedAt": "2025-07-01T16:45:55.246Z"
    }
}
Update Custom Connection
Update Custom Connection details


🔒 Requires Custom Connections Data: Create and Update Custom Connection Data permission.


💎 Requires your account have the Custom Connections and Tests feature. Contact your CSM for help upgrading.


Securitybearer 
Request 
path Parameters
connectionId
required
number
 
Request Body schema: application/json
required
clientAlias
string or null
Alias for the Custom Connection


 
description
string
Description for Custom Connection


 
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


put/custom-connections/{connectionId}
Request samples 
application/json
{
  • "clientAlias": "My Updated Custom Connection",
  • "description": "Updated description for Custom Connection"
}
Response samples 
application/json
{
  • "id": 1,
  • "clientAlias": "My Custom Connection",
  • "description": "Custom connection for managing Employee Data",
  • "providerTypes": [
    • "MDM"
    ],
  • "createdAt": "2025-07-01T16:45:55.246Z",
  • "updatedAt": "2025-07-01T16:45:55.246Z",
  • "createdById": 1,
  • "createdByUser": {
    • "id": 1,
    • "email": "[email protected]",
    • "firstName": "Sally",
    • "lastName": "Smith",
    • "createdAt": "2025-07-01T16:45:55.246Z",
    • "updatedAt": "2025-07-01T16:45:55.246Z"
    }
}
Delete Custom Connection
🔒 Requires custom-connections-delete permission.


💎 Requires your account have the Custom Connections and Tests feature. Contact your CSM for help upgrading.


Securitybearer 
Request 
path Parameters
connectionId
required
number
 
Responses 
204
No Content


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


delete/custom-connections/{connectionId}
Request samples 
Response samples 
application/json
{
  • "statusCode": 0,
  • "message": "string",
  • "code": 0,
  • "debugInfo": {
    • "name": "string",
    • "message": "string",
    • "stack": "string"
    }
}