Custom Data Records

Custom Data Records are JSON evidence records pushed to a Custom Connection resource. Use the session management endpoints to batch upload records and track the status of bulk operations. You can create monitors on this data to provide continuous compliance. The help docs have more information.

List Custom Data Records

List Custom Data Records 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
path Parameters
connectionId
required
number
resourceId
required
number
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
sessionId
string [ 3 .. 64 ] characters

Filter records by session ID.

Example: sessionId=session-abc-123
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

get/custom-connections/{connectionId}/resources/{resourceId}/records
Request samples 
Response samples 
application/json
{
  • "data": [
    • {
      • "id": "employee-001",
      • "attributes": {
        • "id": "employee-001",
        • "name": "John Doe",
        • "department": "Engineering",
        • "status": "Active"
        },
      • "sessionId": "session-abc-123",
      • "createdAt": "2025-07-01T16:45:55.246Z",
      • "updatedAt": "2025-07-01T16:45:55.246Z"
      }
    ],
  • "pagination": {
    • "cursor": "string",
    • "totalCount": 0
    }
}
Upsert Custom Data Records
Create or update Custom Data records for a Custom Connection.


🔒 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 
path Parameters
connectionId
required
number
 
resourceId
required
number
 
Request Body schema: application/json
required
required
Array of objects or object
The Custom Data record(s) to be created or updated. Can be a single object or an array of objects for bulk upload. Records with matching IDs will be updated; new records will be created. Records will be added grouped under ACTIVE session if one exists.


 
Responses 
200
Successful


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


404
Not Found


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


500
Internal server error


post/custom-connections/{connectionId}/resources/{resourceId}/records
Request samples 
application/json
{
  • "data": [
    • {
      • "id": "employee-001",
      • "name": "John",
      • "last_name": "Doe",
      • "department": "Engineering",
      • "status": "Active"
      },
    • {
      • "id": "employee-002",
      • "name": "Jane",
      • "last_name": "Smith",
      • "department": "Sales",
      • "status": "Active"
      }
    ]
}
Response samples 
application/json
{
  • "id": "fd52f04f-a030-44ea-a5af-40919194ab7e",
  • "createdAt": "2020-07-06 12:00:00.000000",
  • "updatedAt": "2020-07-06 13:00:00.000000",
  • "statusCode": 200,
  • "data": {
    • "YOUR": "DATA",
    • "PROPERTIES": {
      • "WILL": "BE_HERE"
      }
    }
}
List Custom Data Sessions
List Custom Data Sessions 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 
path Parameters
connectionId
required
number
 
resourceId
required
number
 
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
status
string (CustomDataSessionStatusEnum) 
Filter sessions by status


 Enum: "IN_PROGRESS" "ACTIVE" "CANCELED" "ARCHIVED"  
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


get/custom-connections/{connectionId}/resources/{resourceId}/sessions
Request samples 
Response samples 
application/json
{
  • "data": [
    • {
      • "id": 1,
      • "sessionId": "session-abc-123",
      • "status": "ACTIVE",
      • "createdAt": "2025-07-01T16:45:55.246Z",
      • "updatedAt": "2025-07-01T16:45:55.246Z",
      • "activatedAt": "2025-07-01T16:45:55.246Z",
      • "canceledAt": "2025-07-01T16:45:55.246Z"
      }
    ],
  • "pagination": {
    • "cursor": "string",
    • "totalCount": 0
    }
}
Upsert Custom Data Records with Session Management
Insert or update Custom Data records in batches using Session Management.


🔒 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 
path Parameters
connectionId
required
number
 
resourceId
required
number
 
sessionId
required
string
 
Request Body schema: application/json
required
required
Array of objects or object
The Custom Data record(s) to be created or updated within a session. Can be a single object or an array of objects for bulk upload. Records remain inactive until the session is completed via the session action endpoint.


 
Responses 
200
Successful


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


404
Not Found


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


500
Internal server error


post/custom-connections/{connectionId}/resources/{resourceId}/sessions/{sessionId}
Request samples 
application/json
{
  • "data": [
    • {
      • "id": "employee-001",
      • "name": "John",
      • "last_name": "Doe",
      • "department": "Engineering",
      • "status": "Active"
      },
    • {
      • "id": "employee-002",
      • "name": "Jane",
      • "last_name": "Smith",
      • "department": "Sales",
      • "status": "Active"
      }
    ]
}
Response samples 
application/json
{
  • "id": "fd52f04f-a030-44ea-a5af-40919194ab7e",
  • "createdAt": "2020-07-06 12:00:00.000000",
  • "updatedAt": "2020-07-06 13:00:00.000000",
  • "statusCode": 200,
  • "data": {
    • "YOUR": "DATA",
    • "PROPERTIES": {
      • "WILL": "BE_HERE"
      }
    }
}
Perform Session Action
Perform an action on a Custom Data record Session


🔒 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 
path Parameters
connectionId
required
number
 
resourceId
required
number
 
sessionId
required
string
 
Request Body schema: application/json
required
action
required
string
The action to perform on the session.


    

  • complete: Mark session as complete, sets data as active and permanently deletes all data that is not part of the session
    • 

  • cancel: Cancels session and discard data associated with that session
    • 



 Enum: "complete" "cancel"  
Responses 
200
Successful


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


422
Unprocessable Entity


500
Internal server error


post/custom-connections/{connectionId}/resources/{resourceId}/sessions/{sessionId}/actions
Request samples 
application/json
{
  • "action": "complete"
}
Response samples 
application/json
{
  • "sessionId": "upload-2024-03-13",
  • "status": "ACTIVE",
  • "action": "complete",
  • "connectionId": 123,
  • "resourceId": 456
}
Update Custom Data Record
Update an existing Custom Data record by ID.


🔒 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
 
resourceId
required
number
 
recordId
required
string
 
Request Body schema: application/json
required
required
object
The custom data to update


 
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


413
The file was too large to upload


500
Internal server error


put/custom-connections/{connectionId}/resources/{resourceId}/records/{recordId}
Request samples 
application/json
{
  • "data": {
    • "employeeId": "EMP-001",
    • "name": "Jane Smith",
    • "department": "Engineering",
    • "startDate": "2024-01-15T00:00:00Z",
    • "isActive": true,
    • "accessLevel": 3,
    • "tags": [
      • "engineer",
      • "remote"
      ],
    • "metadata": {
      • "lastReview": "2025-03-01T00:00:00Z"
      }
    }
}
Response samples 
application/json
{
  • "id": "employee-001",
  • "attributes": {
    • "id": "employee-001",
    • "name": "John Doe",
    • "department": "Engineering",
    • "status": "Active"
    },
  • "sessionId": "session-abc-123",
  • "createdAt": "2025-07-01T16:45:55.246Z",
  • "updatedAt": "2025-07-01T16:45:55.246Z"
}
Delete Custom Connection Data Record
Delete a Custom Data Record by ID.


🔒 Requires Custom Connections Data: Delete 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
 
resourceId
required
number
 
recordId
required
string
 
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


404
Not Found


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


500
Internal server error


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