Custom Connections

Custom Connections allow users to integrate external systems with Drata. CUSTOM connections push arbitrary JSON evidence records using a user-defined schema. MDM and HRIS connections use a fixed common model for device management and HR identity data respectively. The help docs for custom connections and tests and custom device connections have more information.

List Custom Connections

Find Custom Connections matching the provided filters.

🔒 Requires Custom Connections Management: 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 .. 500 ]
Default: 50

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"
includeTotalCount
boolean
Default: false

Include total count of all matching records in response. Only honored on first page (when cursor is null).

Example: includeTotalCount=false
expand[]
Array of strings (CustomConnectionExpandEnum)

List of subcollections and sub-objects to expand

Items Enum: "createdByUser" "customResources"
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,
      • "customResources": [
        • {
          • "id": 123,
          • "name": "Employees",
          • "description": "Employee records for compliance tracking",
          • "schema": {
            • "id": "string",
            • "type": "object",
            • "properties": {
              • "name": {
                • "type": "string"
                }
              },
            • "required": [
              • "name"
              ],
            • "additionalProperties": false,
            • "selfRequired": true,
            • "$schema": "http://json-schema.org/draft-07/schema#"
            },
          • "createdAt": "2025-07-01T16:45:55.246Z",
          • "updatedAt": "2025-07-01T16:45:55.246Z",
          • "deletedAt": "2025-07-01T16:45:55.246Z"
          }
        ],
      • "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",
    • "totalCount": 0
    }
}
Create Custom Connection
Create a new Custom Connection. Supported provider types: CUSTOM, MDM, HRIS. CUSTOM connections require schema or sampleData and displayNameKey. MDM and HRIS connections use a fixed common model — schema, sampleData, and displayNameKey must not be provided.


🔒 Requires Custom Connections Management: Create Custom Connection 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. Supported types: CUSTOM, MDM, HRIS. CUSTOM connections require a schema. MDM and HRIS use a fixed common model and do not accept schema fields.


Items Enum: "CUSTOM" "MDM" "HRIS"  
workspaceIds
Array of numbers
Required for CUSTOM connections. IDs of the Workspaces to associate with this Custom Connection. Not applicable for MDM or HRIS connections, which are global.


 
object
Required for CUSTOM connections. Not applicable for MDM or HRIS connections, which use a fixed common model.The JSON Schema definition for the data records this Custom Connection will store. Provide either schema (a valid JSON Schema object) or sampleData (a representative record) — not both. When sampleData is provided, the schema will be inferred automatically.


 
object
Required for CUSTOM connections. Not applicable for MDM or HRIS connections, which use a fixed common model.A sample JSON object representing a single data record. The structure will be used to infer the JSON Schema for this Custom Connection resource. Provide either sampleData or schema — not both.


 
description
string or null
Optional description for the Custom Connection resource.


 
displayNameKey
string
Required for CUSTOM connections. Not applicable for MDM or HRIS connections, which use a fixed common model.The key from the schema that identifies which field should be used as the human-readable display name for each record. For example, if your schema has name, employeeId, and department fields and you set displayNameKey to "name", records will be labeled by their name value wherever they appear in the Drata UI. Must be a top-level key present in schema.properties.


 
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": [
    • "CUSTOM"
    ],
  • "workspaceIds": [
    • 1
    ],
  • "schema": {
    • "type": "object",
    • "properties": {
      • "employeeId": {
        • "type": "string"
        },
      • "name": {
        • "type": "string"
        },
      • "department": {
        • "type": "string"
        },
      • "startDate": {
        • "type": "string"
        },
      • "isActive": {
        • "type": "boolean"
        },
      • "metadata": {
        • "type": "object",
        • "properties": {
          • "lastReview": {
            • "type": "string"
            }
          },
        • "additionalProperties": true
        }
      },
    • "additionalProperties": true
    },
  • "sampleData": {
    • "employeeId": "EMP-001",
    • "name": "Jane Smith",
    • "department": "Engineering",
    • "startDate": "2024-01-15T00:00:00Z",
    • "isActive": true,
    • "metadata": {
      • "lastReview": "2025-03-01T00:00:00Z"
      }
    },
  • "description": "A connection for syncing employee records from our internal HRIS.",
  • "displayNameKey": "name"
}
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,
  • "customResources": [
    • {
      • "id": 123,
      • "name": "Employees",
      • "description": "Employee records for compliance tracking",
      • "schema": {
        • "id": "string",
        • "type": "object",
        • "properties": {
          • "name": {
            • "type": "string"
            }
          },
        • "required": [
          • "name"
          ],
        • "additionalProperties": false,
        • "selfRequired": true,
        • "$schema": "http://json-schema.org/draft-07/schema#"
        },
      • "createdAt": "2025-07-01T16:45:55.246Z",
      • "updatedAt": "2025-07-01T16:45:55.246Z",
      • "deletedAt": "2025-07-01T16:45:55.246Z"
      }
    ],
  • "createdByUser": {
    • "id": 1,
    • "email": "[email protected]",
    • "firstName": "Sally",
    • "lastName": "Smith",
    • "createdAt": "2025-07-01T16:45:55.246Z",
    • "updatedAt": "2025-07-01T16:45:55.246Z"
    }
}
Get Custom Connection
🔒 Requires Custom Connections Management: 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 Enum: "createdByUser" "customResources"  
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,
  • "customResources": [
    • {
      • "id": 123,
      • "name": "Employees",
      • "description": "Employee records for compliance tracking",
      • "schema": {
        • "id": "string",
        • "type": "object",
        • "properties": {
          • "name": {
            • "type": "string"
            }
          },
        • "required": [
          • "name"
          ],
        • "additionalProperties": false,
        • "selfRequired": true,
        • "$schema": "http://json-schema.org/draft-07/schema#"
        },
      • "createdAt": "2025-07-01T16:45:55.246Z",
      • "updatedAt": "2025-07-01T16:45:55.246Z",
      • "deletedAt": "2025-07-01T16:45:55.246Z"
      }
    ],
  • "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 Management: Update Custom Connection 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,
  • "customResources": [
    • {
      • "id": 123,
      • "name": "Employees",
      • "description": "Employee records for compliance tracking",
      • "schema": {
        • "id": "string",
        • "type": "object",
        • "properties": {
          • "name": {
            • "type": "string"
            }
          },
        • "required": [
          • "name"
          ],
        • "additionalProperties": false,
        • "selfRequired": true,
        • "$schema": "http://json-schema.org/draft-07/schema#"
        },
      • "createdAt": "2025-07-01T16:45:55.246Z",
      • "updatedAt": "2025-07-01T16:45:55.246Z",
      • "deletedAt": "2025-07-01T16:45:55.246Z"
      }
    ],
  • "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 Management: Delete Custom Connection 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"
    }
}