{"componentChunkName":"component---src-templates-simple-markdown-js","path":"/developer-portal/v2/recipes/custom-connections/","matchPath":"","result":{"data":{"markdownRemark":{"html":"

Work with Custom Connections

\n

1. General

\n

Custom Connections let you push your own data into Drata so it can be used for compliance evidence. The behavior depends on the provider type you choose when creating the connection:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
Provider typeSchema required?Record endpoint
CUSTOMYes — you define the schema via schema or sampleData + displayNameKey/custom-connections/{connectionId}/resources/{resourceId}/records
MDMNo — Drata uses a fixed common device model/custom-connections/{connectionId}/devices
HRISNo — Drata uses a fixed common HRIS model/custom-connections/{connectionId}/hris-user-identities
\n
\n

Note: Passing schema, sampleData, displayNameKey, or workspaceIds for an MDM or HRIS connection will return a 400 Bad Request.

\n
\n

Sections 3 and 4 of this recipe (record and session management) apply to CUSTOM connections only. For MDM and HRIS connections, refer to the Devices and HRIS User Identities endpoint references respectively.

\n

For CUSTOM connections, records can be uploaded two ways:

\n\n

The session-based approach is recommended for bulk syncs where you want an all-or-nothing replacement of your data.

\n
\n

2. Setup

\n

2.1 Create a Custom Connection

\n
\n
\n
Copy
\n
Copied
\n
\n 
POST https://public-api.drata.com/public/v2/custom-connections
\n
\n

CUSTOM connection (user-defined schema)

\n

You define the schema for your records. Use schema to provide a JSON Schema directly, or sampleData to have Drata infer the schema from a representative record. displayNameKey is required and must be a top-level key in the schema.

\n

Option A: Provide a JSON Schema directly

\n
\n
\n
Copy
\n
Copied
\n
\n 
{\n  \"name\": \"Software Inventory\",\n  \"providerTypes\": [\"CUSTOM\"],\n  \"workspaceIds\": [1],\n  \"displayNameKey\": \"packageName\",\n  \"description\": \"Software packages installed across the fleet.\",\n  \"schema\": {\n    \"type\": \"object\",\n    \"properties\": {\n      \"packageName\": { \"type\": \"string\" },\n      \"version\": { \"type\": \"string\" },\n      \"vendor\": { \"type\": \"string\" },\n      \"installedAt\": { \"type\": \"string\" },\n      \"isApproved\": { \"type\": \"boolean\" }\n    },\n    \"additionalProperties\": true\n  }\n}
\n
\n

Option B: Provide sample data and let Drata infer the schema

\n
\n
\n
Copy
\n
Copied
\n
\n 
{\n  \"name\": \"Software Inventory\",\n  \"providerTypes\": [\"CUSTOM\"],\n  \"workspaceIds\": [1],\n  \"displayNameKey\": \"packageName\",\n  \"description\": \"Software packages installed across the fleet.\",\n  \"sampleData\": {\n    \"packageName\": \"1Password\",\n    \"version\": \"8.10.36\",\n    \"vendor\": \"AgileBits\",\n    \"installedAt\": \"2024-01-15T00:00:00Z\",\n    \"isApproved\": true\n  }\n}
\n
\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
FieldRequiredDescription
nameYesDisplay name for the connection
providerTypesYes[\"CUSTOM\"]
workspaceIdsYesAt least one workspace ID
schemaNo*JSON Schema for your records. Provide either schema or sampleData, not both. *Required if sampleData is not provided.
sampleDataNo*A representative record from which Drata infers the schema. Provide either sampleData or schema, not both. *Required if schema is not provided.
displayNameKeyYesTop-level schema field used as the human-readable label for each record in the Drata UI (e.g. \"packageName\"). Must exist as a property in the provided or inferred schema.
descriptionNoOptional description
\n
\n

MDM connection (fixed device model)

\n

MDM connections use Drata's built-in device data model. Do not provide schema, sampleData, displayNameKey, or workspaceIds — MDM connections are global.

\n
\n
\n
Copy
\n
Copied
\n
\n 
{\n  \"name\": \"Fleet MDM\",\n  \"providerTypes\": [\"MDM\"],\n  \"description\": \"Device inventory synced from our MDM solution.\"\n}
\n
\n

After creating, use the Devices endpoints to upload device records.

\n
\n

HRIS connection (fixed HRIS model)

\n

HRIS connections use Drata's built-in HRIS data model. Do not provide schema, sampleData, displayNameKey, or workspaceIds — HRIS connections are global.

\n
\n
\n
Copy
\n
Copied
\n
\n 
{\n  \"name\": \"Employee Directory\",\n  \"providerTypes\": [\"HRIS\"],\n  \"description\": \"Employee roster synced from our internal HRIS.\"\n}
\n
\n

After creating, use the HRIS User Identities endpoints to upload employee records.

\n
\n

Common fields for all connection types:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
FieldRequiredDescription
nameYesDisplay name for the connection
providerTypesYesOne of: CUSTOM, MDM, HRIS
descriptionNoOptional description
\n

Reference: Create Custom Connection API

\n
\n

2.2 Retrieve the Resource ID (CUSTOM connections only)

\n

All CUSTOM record and session operations require a resourceId. This is created automatically when you create the connection and is tied to the schema you provided.

\n

Fetch it by expanding customResources on the connection:

\n
\n
\n
Copy
\n
Copied
\n
\n 
GET https://public-api.drata.com/public/v2/custom-connections/{connectionId}?expand[]=customResources
\n
\n

Response (relevant fields):

\n
\n
\n
Copy
\n
Copied
\n
\n 
{\n  \"id\": 42,\n  \"customResources\": [\n    {\n      \"id\": 7,\n      \"name\": \"Software Inventory\",\n      \"schema\": { ... },\n      \"createdAt\": \"2025-01-01T00:00:00Z\",\n      \"updatedAt\": \"2025-01-01T00:00:00Z\"\n    }\n  ]\n}
\n
\n

Use customResources[0].id as the resourceId in all subsequent record and session requests.

\n

Reference: Get Custom Connection API

\n
\n

3. Managing Records Directly

\n
\n

CUSTOM connections only. For MDM and HRIS connections, use the Devices and HRIS User Identities endpoints instead.

\n
\n

Use the direct upload approach for incremental updates — adding, updating, or removing individual records without replacing the full dataset.

\n

3.1 Upsert Records

\n

Records are matched by id. If a record with that ID already exists it is updated; otherwise a new record is created. You can send a single object or an array.

\n
\n
\n
Copy
\n
Copied
\n
\n 
POST https://public-api.drata.com/public/v2/custom-connections/{connectionId}/resources/{resourceId}/records
\n
\n

Request Payload (single record):

\n
\n
\n
Copy
\n
Copied
\n
\n 
{\n  \"data\": {\n    \"id\": \"PKG-001\",\n    \"packageName\": \"1Password\",\n    \"version\": \"8.10.36\",\n    \"isApproved\": true\n  }\n}
\n
\n

Request Payload (multiple records):

\n
\n
\n
Copy
\n
Copied
\n
\n 
{\n  \"data\": [\n    {\n      \"id\": \"PKG-001\",\n      \"packageName\": \"1Password\",\n      \"version\": \"8.10.36\",\n      \"isApproved\": true\n    },\n    {\n      \"id\": \"PKG-002\",\n      \"packageName\": \"Zoom\",\n      \"version\": \"6.2.0\",\n      \"isApproved\": true\n    }\n  ]\n}
\n
\n
\n

Note: If an active session exists for this connection/resource, directly uploaded records are automatically grouped under it.

\n
\n

Reference: Upsert Records API

\n
\n

3.2 Update a Record

\n

Update a specific record by its recordId.

\n
\n
\n
Copy
\n
Copied
\n
\n 
PUT https://public-api.drata.com/public/v2/custom-connections/{connectionId}/resources/{resourceId}/records/{recordId}
\n
\n

Request Payload:

\n
\n
\n
Copy
\n
Copied
\n
\n 
{\n  \"data\": {\n    \"version\": \"8.10.40\",\n    \"isApproved\": false\n  }\n}
\n
\n

Reference: Update Record API

\n
\n

3.3 Delete a Record

\n
\n
\n
Copy
\n
Copied
\n
\n 
DELETE https://public-api.drata.com/public/v2/custom-connections/{connectionId}/resources/{resourceId}/records/{recordId}
\n
\n

Returns 204 No Content on success.

\n

Reference: Delete Record API

\n
\n

3.4 List Records

\n
\n
\n
Copy
\n
Copied
\n
\n 
GET https://public-api.drata.com/public/v2/custom-connections/{connectionId}/resources/{resourceId}/records
\n
\n

Optionally filter by session using the sessionId query parameter:

\n
\n
\n
Copy
\n
Copied
\n
\n 
GET https://public-api.drata.com/public/v2/custom-connections/{connectionId}/resources/{resourceId}/records?sessionId=upload-2025-04-01
\n
\n

Reference: List Records API

\n
\n

4. Session-Based Record Management

\n
\n

CUSTOM connections only. For MDM and HRIS connections, use the Devices and HRIS User Identities endpoints instead.

\n
\n

Sessions are designed for bulk syncs where you want to stage an entire dataset and commit it atomically. When you complete a session, it becomes the authoritative dataset — everything not in that session is permanently deleted.

\n

4.1 Session States

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
StateDescription
IN_PROGRESSSession is open. Records are staged but not yet live.
ACTIVESession has been completed. Its records are the live dataset.
CANCELLEDSession was aborted. All staged records are discarded.
ARCHIVEDSystem-managed. A previously ACTIVE session that was replaced by a newer one. Its records have been deleted.
\n

Only one session can be IN_PROGRESS at a time per connection/resource.

\n
\n

4.2 Upload Records to a Session

\n

Choose any string as your sessionId — if the session doesn't exist yet it will be created in IN_PROGRESS state. You can call this endpoint multiple times with the same sessionId to upload in batches.

\n
\n
\n
Copy
\n
Copied
\n
\n 
POST https://public-api.drata.com/public/v2/custom-connections/{connectionId}/resources/{resourceId}/sessions/{sessionId}
\n
\n

Session ID rules: 3–64 characters, letters/numbers/hyphens/underscores only (e.g. upload-2025-04-01, batch_sync_v2).

\n

Request Payload:

\n
\n
\n
Copy
\n
Copied
\n
\n 
{\n  \"data\": [\n    {\n      \"id\": \"PKG-001\",\n      \"packageName\": \"1Password\",\n      \"version\": \"8.10.36\",\n      \"isApproved\": true\n    },\n    {\n      \"id\": \"PKG-002\",\n      \"packageName\": \"Zoom\",\n      \"version\": \"6.2.0\",\n      \"isApproved\": true\n    }\n  ]\n}
\n
\n

Records uploaded to a session are staged and not visible as live data until the session is completed.

\n

Reference: Upsert Records with Session API

\n
\n

4.3 Complete a Session

\n

Once all records are uploaded, complete the session to make them live.

\n
\n
\n
Copy
\n
Copied
\n
\n 
POST https://public-api.drata.com/public/v2/custom-connections/{connectionId}/resources/{resourceId}/sessions/{sessionId}/actions
\n
\n

Request Payload:

\n
\n
\n
Copy
\n
Copied
\n
\n 
{\n  \"action\": \"complete\"\n}
\n
\n

What happens on completion:

\n
    \n
  1. \nThe session transitions from \nIN_PROGRESS\n → \nACTIVE\n
    2. \n
  2. \nAll records in the session become the live dataset\n
    3. \n
  3. \nAny previously ACTIVE session is archived and its records are \npermanently deleted\n
    4. \n
  4. \nAny records that were uploaded directly (not via a session) are also \npermanently deleted\n
    5. \n
\n
\n

Warning: Completing a session is destructive and irreversible. Every record not part of the completing session — including any records uploaded via the direct endpoint — will be hard deleted.

\n
\n

Response:

\n
\n
\n
Copy
\n
Copied
\n
\n 
{\n  \"sessionId\": \"upload-2025-04-01\",\n  \"status\": \"ACTIVE\",\n  \"action\": \"complete\",\n  \"connectionId\": 42,\n  \"resourceId\": 7\n}
\n
\n

Reference: Perform Session Action API

\n
\n

4.4 Cancel a Session

\n

To discard a session and all its staged records without committing them:

\n
\n
\n
Copy
\n
Copied
\n
\n 
POST https://public-api.drata.com/public/v2/custom-connections/{connectionId}/resources/{resourceId}/sessions/{sessionId}/actions
\n
\n

Request Payload:

\n
\n
\n
Copy
\n
Copied
\n
\n 
{\n  \"action\": \"cancel\"\n}
\n
\n

The session transitions to CANCELLED and all staged records are deleted. The previously active dataset (if any) is unaffected.

\n

Reference: Perform Session Action API

\n
\n

4.5 List Sessions

\n
\n
\n
Copy
\n
Copied
\n
\n 
GET https://public-api.drata.com/public/v2/custom-connections/{connectionId}/resources/{resourceId}/sessions
\n
\n

Filter by status using the status query parameter:

\n
\n
\n
Copy
\n
Copied
\n
\n 
GET https://public-api.drata.com/public/v2/custom-connections/{connectionId}/resources/{resourceId}/sessions?status=IN_PROGRESS
\n
\n

Reference: List Sessions API

\n
\n

5. Managing Custom Connections

\n

5.1 List Custom Connections

\n
\n
\n
Copy
\n
Copied
\n
\n 
GET https://public-api.drata.com/public/v2/custom-connections
\n
\n

Use expand[] to include sub-objects in the response:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
ValueDescription
customResourcesIncludes the resource(s) and their schemas
createdByUserIncludes the user or API key that created the connection
\n
\n
\n
Copy
\n
Copied
\n
\n 
GET https://public-api.drata.com/public/v2/custom-connections?expand[]=customResources
\n
\n

Reference: List Custom Connections API

\n
\n

5.2 Get Custom Connection

\n
\n
\n
Copy
\n
Copied
\n
\n 
GET https://public-api.drata.com/public/v2/custom-connections/{connectionId}
\n
\n

Supports the same expand[] values as List.

\n

Reference: Get Custom Connection API

\n
\n

5.3 Update Custom Connection

\n

Only clientAlias and description can be updated after creation.

\n
\n
\n
Copy
\n
Copied
\n
\n 
PUT https://public-api.drata.com/public/v2/custom-connections/{connectionId}
\n
\n

Request Payload:

\n
\n
\n
Copy
\n
Copied
\n
\n 
{\n  \"clientAlias\": \"Fleet Software Tracker\",\n  \"description\": \"Software packages synced nightly from our asset management tool\"\n}
\n
\n

Reference: Update Custom Connection API

\n
\n

5.4 Delete Custom Connection

\n
\n
\n
Copy
\n
Copied
\n
\n 
DELETE https://public-api.drata.com/public/v2/custom-connections/{connectionId}
\n
\n

Returns 204 No Content on success. Deletes the connection and all associated records.

\n

Reference: Delete Custom Connection API

","headings":[{"value":"Work with Custom Connections","depth":1},{"value":"1. General","depth":2},{"value":"2. Setup","depth":2},{"value":"2.1 Create a Custom Connection","depth":3},{"value":"CUSTOM connection (user-defined schema)","depth":4},{"value":"MDM connection (fixed device model)","depth":4},{"value":"HRIS connection (fixed HRIS model)","depth":4},{"value":"2.2 Retrieve the Resource ID (CUSTOM connections only)","depth":3},{"value":"3. Managing Records Directly","depth":2},{"value":"3.1 Upsert Records","depth":3},{"value":"3.2 Update a Record","depth":3},{"value":"3.3 Delete a Record","depth":3},{"value":"3.4 List Records","depth":3},{"value":"4. Session-Based Record Management","depth":2},{"value":"4.1 Session States","depth":3},{"value":"4.2 Upload Records to a Session","depth":3},{"value":"4.3 Complete a Session","depth":3},{"value":"4.4 Cancel a Session","depth":3},{"value":"4.5 List Sessions","depth":3},{"value":"5. Managing Custom Connections","depth":2},{"value":"5.1 List Custom Connections","depth":3},{"value":"5.2 Get Custom Connection","depth":3},{"value":"5.3 Update Custom Connection","depth":3},{"value":"5.4 Delete Custom Connection","depth":3}]},"contentItem":{"data":{"lastModified":"2026-05-01T19:59:45.000Z","enableToc":null,"disableLastModified":null,"tocMaxDepth":null,"requestLogin":false}},"siteConfig":{"enableToc":false,"disableLastModified":false,"tocMaxDepth":4}},"pageContext":{"matchPath":"","id":"9a8df30e-e5aa-57c3-bbbb-bf736942eece__redocly content/developer-portal/v2/recipes/custom-connections/","seo":{"title":"Work with Custom Connections","description":null,"image":"","keywords":null,"jsonLd":null,"lang":null,"siteUrl":null},"pageId":"developer-portal/v2/recipes/custom-connections.md","pageBaseUrl":"/developer-portal/v2/recipes/custom-connections","type":"markdown","toc":{"enable":true,"maxDepth":4,"headings":[{"depth":1,"value":"Work with Custom Connections","id":"work-with-custom-connections"},{"depth":2,"value":"1. General","id":"1-general"},{"depth":2,"value":"2. Setup","id":"2-setup"},{"depth":3,"value":"2.1 Create a Custom Connection","id":"21-create-a-custom-connection"},{"depth":4,"value":"CUSTOM connection (user-defined schema)","id":"custom-connection-user-defined-schema"},{"depth":4,"value":"MDM connection (fixed device model)","id":"mdm-connection-fixed-device-model"},{"depth":4,"value":"HRIS connection (fixed HRIS model)","id":"hris-connection-fixed-hris-model"},{"depth":3,"value":"2.2 Retrieve the Resource ID (CUSTOM connections only)","id":"22-retrieve-the-resource-id-custom-connections-only"},{"depth":2,"value":"3. Managing Records Directly","id":"3-managing-records-directly"},{"depth":3,"value":"3.1 Upsert Records","id":"31-upsert-records"},{"depth":3,"value":"3.2 Update a Record","id":"32-update-a-record"},{"depth":3,"value":"3.3 Delete a Record","id":"33-delete-a-record"},{"depth":3,"value":"3.4 List Records","id":"34-list-records"},{"depth":2,"value":"4. Session-Based Record Management","id":"4-session-based-record-management"},{"depth":3,"value":"4.1 Session States","id":"41-session-states"},{"depth":3,"value":"4.2 Upload Records to a Session","id":"42-upload-records-to-a-session"},{"depth":3,"value":"4.3 Complete a Session","id":"43-complete-a-session"},{"depth":3,"value":"4.4 Cancel a Session","id":"44-cancel-a-session"},{"depth":3,"value":"4.5 List Sessions","id":"45-list-sessions"},{"depth":2,"value":"5. Managing Custom Connections","id":"5-managing-custom-connections"},{"depth":3,"value":"5.1 List Custom Connections","id":"51-list-custom-connections"},{"depth":3,"value":"5.2 Get Custom Connection","id":"52-get-custom-connection"},{"depth":3,"value":"5.3 Update Custom Connection","id":"53-update-custom-connection"},{"depth":3,"value":"5.4 Delete Custom Connection","id":"54-delete-custom-connection"}]},"data":{"title":""},"catalogInfo":null,"link":"/developer-portal/v2/recipes/custom-connections/","sidebarName":"training","isLanding":false,"showPrevButton":null,"showNextButton":null,"apiVersions":null,"apiVersionId":null,"isDefaultApiVersion":null}},"staticQueryHashes":["1123603147","1302185487","1344209882","1398840060","1520077861","1975142765","2667623876","2950305614","3240152602","3743992808","561138138"]}