Custom Connections

Upsert Custom Data Records

This endpoint allows you to upsert custom data records individually or in bulk.

    * If a record with a matching identifier is found, it will be updated (upserted). 

    * If no matching record is found, a new record will be created with a generated ID. 


    **Session Management (Optional):**

    * `X-Session-ID`: Unique identifier for session upload

    * `X-Session-Complete: true`: Mark session as complete (activates data for evidence generation)

    * `X-Session-Abort: true`: Abort session and mark for cleanup


    When using session management, only data from ACTIVE sessions is used for compliance evaluations.

🔒 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
header Parameters
x-session-id
required
string
x-session-complete
required
string
x-session-abort
required
string
Request Body schema: application/json
required
data
required
object

The Custom data to be created

Responses
200

Successful

201

Created

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

413

The file was too large to upload

500

Internal server error

post/custom-connections/{connectionId}/resources/{resourceId}/records
Request samples
application/json
{
  • "data": {
    • "id": "some-id-here-uuid4",
    • "name": "John",
    • "last_name": "Wick",
    • "age": 5,
    • "data": {
      • "foo": "bar"
      }
    }
}
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"
      }
    }
}

Update custom data record by id

If a record with the id exists it will be updated.

🔒 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 be created

Responses
200

Successful

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

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": {
    • "type": "object",
    • "required": [
      • "comment_id",
      • "user",
      • "text"
      ],
    • "properties": {
      • "comment_id": {
        • "type": "number"
        },
      • "user": {
        • "type": "object",
        • "required": [
          • "id",
          • "name",
          • "email",
          • "has_bought"
          ],
        • "properties": {
          • "id": {
            • "type": "number"
            },
          • "name": {
            • "type": "string"
            },
          • "email": {
            • "type": "string"
            },
          • "has_bought": {
            • "type": "boolean"
            }
          }
        },
      • "text": {
        • "type": "string"
        }
      }
    }
}
Response samples
application/json
{
  • "id": 1
}

Delete a custom data record by id

If a record with the id exists it will be deleted

🔒 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
recordId
required
string
connectionId
required
number
resourceId
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/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"
    }
}
Get all custom data sessions
Get all custom data sessions for the account with pagination support


🔒 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
page
number  >= 1 
 Default:  1
Which page of data are you requesting


 
limit
number  [ 1 .. 50 ] 
 Default:  20
How many items are you requesting


 
connectionId
number
Filter sessions by Custom Connection id


 
 Example:  connectionId=1
resourceId
number
Filter sessions by Custom Resource id


 
 Example:  resourceId=1
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


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


500
Internal server error


get/sessions
Request samples 
Response samples 
application/json
{
  • "data": [
    • {
      • "id": "session-123",
      • "connectionId": 1,
      • "customResourceId": 1,
      • "status": "ACTIVE"
      }
    ],
  • "page": 1,
  • "limit": 10,
  • "total": 100
}
Get paginated evidence data for a specific session
Get paginated evidence data for a specific session by session ID


🔒 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
sessionId
required
string
 
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
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/sessions/{sessionId}/evidence
Request samples 
Response samples 
application/json
{
  • "data": [],
  • "page": 1,
  • "limit": 10,
  • "total": 100,
  • "sessionId": "session-abc-123",
  • "connectionId": 123,
  • "customResourceId": 456
}