If your organization uses a tool or system that Drata doesn’t currently integrate with, you can still automate evidence collection. With Custom Connections and Tests (CCT), you can send structured JSON data from any source, whether cloud-based, on-premises, or proprietary, directly into Drata and create custom tests.

CCT includes two key capabilities:

Custom Connections: Set up a connection to push JSON evidence into Drata from any external system.
Custom Tests: Create and run custom tests against your data.

Complete workflow overview

Here’s how to connect an external system to Drata and run custom tests on the submitted data.

Create a Custom Connection
Connect your external system and define the schema for the data you want to send.
Submit Evidence
Submit your first dataset to confirm your connection and schema are working correctly.
Automate Data Syncs
Set up a recurring data submission process using a tool like Make.com, Tines, or a scheduled script (such as a cron job). This ensures evidence is collected continuously without manual effort.
Create a Custom Test
Use the Test Builder to define rules that validate your custom data—for example, checking whether MFA is enabled.
Review Results and Link to Controls
View pass/fail results, manage exceptions, and map custom tests to compliance controls in Drata.

Prerequisites

Availability: Custom Connections and Tests are available on the Advanced and Enterprise plans.

Limitations

The third-party platform configuration as well as the automation of the workflow and its cadence is set by the customer. This is NOT a standard integration.
The use of custom connections requires developers to access the API and manually build into the workflow. The time required varies based on the complexity of each organization's configuration.
The cadence and how data is pulled and pushed into Drata is determined and manually initiated by the customers.

Set Up a Custom Connection

In the left navigation panel, select Connections.
Near the upper-right corner, select Create connection.
Enter a name, description, and workspace for your connection.

Set Up Your Data Source

Understand Data Structure Requirements

Before setting up your data source, review the following important notes.

Your JSON must include at least one property at the top level that's a string or number—like a name, email, or ID. Drata uses this property to create a display name, which helps you identify individual records in test results.
Arrays are supported as properties at the top level, but if your JSON object is inside an array (for example, [ { "email": "[email protected]" } ]), Drata can’t generate a display name and won’t support the schema.
Multiple properties at the root level are supported, even if one of them is an array. For example:
```
{
  "userId": "abc123",
  "email": "[email protected]",
  "roles": ["admin"]
}
```
If your data includes complex nested arrays, you may need to use the advanced test editor to create custom tests.

Learn more about JSON Schema.

Set Up Your Data Source

Enter a name and description for your data source.
Choose how to provide your schema:
- JSON Schema: Manually define the structure of your data, specifying the structure, data types, and required fields.
  - Example JSON schema:
    {
    "title": "Person",
    "type": "object",
    "properties": {
    "id": {
    "type": "string"
    },
    "firstName": {
    "type": "string"
    },
    "lastName": {
    "type": "string"
    },
    "title": {
    "type": "string"
    },
    "mfa": {
    "type": "boolean"
    }
    },
    "required": ["firstName", "lastName", "title", "mfa"],
    "additionalProperties": false
    }
- Sample JSON Data : Provide example JSON payload. Drata will automatically generate a schema based on the structure of your sample data.
  - This is the recommended approach. You can use a sample API response from your system to ensure the schema accurately reflects your real-world data.
Select Validate or Generate to verify or create your schema.
- If you provide sample JSON, Drata verifies that it can generate a schema and updates it accordingly.
Display Name: Choose a field that Drata will use to identify records in test results.
- For example, if you want to identify users who don’t have MFA enabled, select the email field as the display name.
API key: Choose to create an API key or utilize an existing API key.
- Create an API key (Recommended approach): The required scopes are already applied.
- Use existing API key: Ensure your API key has the required scopes:
  - Read Data
  - Add Data
  - Update Data
  - Delete Data

Submit Your First Data

After setting up your custom connection, submit a record or dataset to confirm that your configuration is working correctly.

Requirements:

The request body must include a top-level data field containing your JSON payload.
Maximum JSON size: 5 MB

Response behavior:

Drata's response will vary depending on whether the record is new or an update:

Status Code	Description
201 CREATED	The record was successfully created.
200 OK	An existing record was updated.

Upload data by sending JSON evidence records through a third-party tool or automation platform, such as Make.com or Tines.

To view or manage your submitted records, go to the Manage tab.

Behavior differs depending on whether your data includes a unique identifier.

After submitting your record, select View Data for more information.

You can also expand the side panel to view additional available API calls.

Single Evidence Submission Scenarios

Here are some more examples for submitting a single piece of evidence or list of evidence items.

Scenario 1: New Evidence Without ID

If the payload does not include an ID, a new record will be created. A uuid will be generated for the evidence to be used in subsequent operations.

Request:

{
 "firstName": "Fred",
 "lastName": "Krueger",
 "title": "Antagonist"
}

Response:

HTTP/1.1 201 Created

{
 "id": "3aae5645-82cf-46ea-9e34-d5fe682eff48",
 "firstName": "Fred",
 "lastName": "Krueger",
 "title": "Antagonist",
 "createdAt": "2024-10-31T15:59:35.318Z",
 "updatedAt": "2024-10-31T15:59:35.318Z"
}

Scenario 2: Existing Evidence With ID

If the payload includes an ID, a lookup will be performed in the custom_data table. If a record is found, it will be updated. If no record is found, a new record will be created using the provided id.

Payload:

{
 "id": "928764",
 "name": "John Doe",
 "age": 28
}

Response:

HTTP/1.1 200 OK
{
 "id": "928764",
 "name": "John Doe",
 "age": 28,
 "createdAt": "2024-12-02T15:30:00Z",
 "updatedAt": "2024-12-03T15:35:00Z"
}

Array of Evidence Behavior

Processing Rules:

Each object in the array will be validated and processed individually. Responses will include a status code (200, 201, or 400) for each item.

Example Request:

[
 {
   "id": "2",
   "firstName": "Fred",
   "lastName": "Krueger",
   "title": "Antagonist"
 },
 {
   "firstName": "Michael",
   "lastName": "Myers",
   "title": "Serial Killer"
 },
 {
   "id": "230",
   "firstName": "Sarah",
   "lastName": "Connor",
   "title": "Resistance Leader"
 }
]

Example Response:

[
 {
   "id": "2",
   "firstName": "Fred",
   "lastName": "Krueger",
   "title": "Antagonist",
   "statusCode": 201,
   "createdAt": "2024-10-31T15:59:35.318Z",
   "updatedAt": "2024-10-31T15:59:35.318Z"
 },
 {
   "id": "52411ed5-00e3-4c71-ade4-5ee14211250d",
   "firstName": "Michael",
   "lastName": "Myers",
   "title": "Serial Killer",
   "statusCode": 201,
   "createdAt": "2024-10-31T15:59:35.318Z",
   "updatedAt": "2024-10-31T15:59:35.318Z"
 },
 {
   "id": "230",
   "firstName": "Sarah",
   "lastName": "Connor",
   "title": "Resistance Leader",
   "statusCode": 200,
   "createdAt": "2024-10-20T15:59:35.318Z",
   "updatedAt": "2024-10-31T15:59:35.318Z"
 }
]

Create and Run a Custom Test

Go to the Monitoring tab.
- This is where all custom tests associated with your Custom Connections is displayed.
Select Create test.
Enter a name and description for your test.
In the test builder,
- Logic Details:
  - Category: Custom
  - Provider: Enter the custom connection name
- Condition Group: Select the resource (data source) and attributes (for example, hasMFA) for the test.
  - As a reminder, if your data includes complex nested arrays, you may need to use the advanced editor.
Save the test. It will be saved as a draft.
Run or publish the test.
- Navigate to the Monitoring page, or the Monitoring tab on the relevant Custom Connection page.
- For Monitoring page, use the filter to locate your test by category: Custom (Draft) or Custom (Published).
- You can run the test while it’s still in draft to review how the test performs.
- To include your draft test in your monitoring results and evidence collection, publish the test and run it.

Learn more about Drata's Monitoring or Custom Tests.

View the test results

On the Monitoring page, select the desired custom tests. Under the Last test result, select View event to verify event tracking details and raw evidence.
To exclude a record from future tests.
- Select the record.
- Choose the Exclude option.

To learn more about exclusions, go to Exclusions.

Link Tests to Controls

You can additionally link this test to controls.

In the test drawer, scroll to the Control info section.
Select Map controls to link the test to one or more controls.

To learn more about mapping tests and controls, go to Mapping Tests and Controls.

Video Tutorials

To view our video tutorials make sure you are logged into Drata and then, go to Custom Connections and Tests Videos.