Audit Requests

Audit Requests are the evidence requests that make up an Audit. Each request tracks its status, the Users assigned to it, and the evidence submitted against it.

Map Audit Request Controls 🧪

Map controls to an Audit Request. Only Controls eligible for the audit are attached (in scope, in the audit's workspace, and in the audit's framework or a custom framework); every other requested ID is returned under skipped. Idempotent.

🧪 Note: This endpoint is in beta and may change.

🔒 Requires Audits: Map and Unmap Audit Request Controls permission.

Securitybearer or oauth2
Request
path Parameters
workspaceId
required
number

The Workspace ID associated to the Account

auditId
required
string
requestId
required
number
Request Body schema: application/json
required
controlIds
required
Array of numbers [ 1 .. 100 ] items unique

Control ids to map to (PUT) or unmap from (DELETE) the audit request

Responses
200

Successful

400

Malformed data and/or validation errors

401

Invalid Authorization

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/workspaces/{workspaceId}/audits/{auditId}/requests/{requestId}/controls
Request samples
application/json
{
  • "controlIds": [
    • 1,
    • 2
    ]
}
Response samples
application/json
{
  • "attached": [
    • {
      • "id": 1,
      • "code": "DCF-1001",
      • "name": "Vulnerability Management",
      • "controlNumber": 1
      }
    ],
  • "skipped": [
    • {
      • "controlId": 1,
      • "reason": "NOT_ELIGIBLE"
      }
    ]
}

Unmap Audit Request Controls 🧪

Unmap controls from an audit request. Idempotent — unmapping a control that is not mapped is a no-op, not a 404. Reconciles matching accepted DCF suggestions to rejected and marks the request's evidence package stale.

🧪 Note: This endpoint is in beta and may change.

🔒 Requires Audits: Map and Unmap Audit Request Controls permission.

Securitybearer or oauth2
Request
path Parameters
workspaceId
required
number

The Workspace ID associated to the Account

auditId
required
string
requestId
required
number
Request Body schema: application/json
required
controlIds
required
Array of numbers [ 1 .. 100 ] items unique

Control ids to map to (PUT) or unmap from (DELETE) the audit request

Responses
200

Successful

400

Malformed data and/or validation errors

401

Invalid Authorization

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/workspaces/{workspaceId}/audits/{auditId}/requests/{requestId}/controls
Request samples
application/json
{
  • "controlIds": [
    • 1,
    • 2
    ]
}
Response samples
application/json
{
  • "detached": [
    • 10,
    • 20
    ],
  • "skipped": [
    • 30
    ]
}

List Audit Request DCF Suggestions 🧪

🧪 Note: This endpoint is in beta and may change.

🔒 Requires Customer Request: Get Customer Request permission.

Securitybearer or oauth2
Request
path Parameters
workspaceId
required
number

The Workspace ID associated to the Account

auditId
required
string
requestId
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"
status[]
Array of strings (AuditRequestDcfSuggestionStatusFilterEnum)

Filter by decision status. Rejected suggestions are never returned.

Items Enum: "PENDING" "ACCEPTED"
confidenceLevel[]
Array of strings (ConfidenceLevelEnum)

Filter by confidence level

Items Enum: "HIGH" "MEDIUM" "LOW"
Responses
200

Successful

400

Malformed data and/or validation errors

401

Invalid Authorization

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/workspaces/{workspaceId}/audits/{auditId}/requests/{requestId}/dcf-suggestions
Request samples
Response samples
application/json
{
  • "data": [
    • {
      • "id": 1,
      • "requestId": 1,
      • "dcfCode": "DCF-1",
      • "controlName": "Access Reviews",
      • "controlDescription": "The organization performs quarterly access reviews.",
      • "controlId": 1,
      • "confidenceLevel": "HIGH",
      • "rationale": "This control answers the request because it covers access governance.",
      • "status": "PENDING",
      • "acceptanceSource": "MANUAL",
      • "decidedById": 1,
      • "decidedAt": "2025-07-01T16:45:55.246Z",
      • "createdAt": "2025-07-01T16:45:55.246Z",
      • "updatedAt": "2025-07-01T16:45:55.246Z"
      }
    ],
  • "pagination": {
    • "cursor": "string"
    }
}

Get Audit Request DCF Suggestion 🧪

🧪 Note: This endpoint is in beta and may change.

🔒 Requires Customer Request: Get Customer Request permission.

Securitybearer or oauth2
Request
path Parameters
workspaceId
required
number

The Workspace ID associated to the Account

auditId
required
string
requestId
required
number
suggestionId
required
number
Responses
200

Successful

400

Malformed data and/or validation errors

401

Invalid Authorization

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/workspaces/{workspaceId}/audits/{auditId}/requests/{requestId}/dcf-suggestions/{suggestionId}
Request samples
Response samples
application/json
{
  • "id": 1,
  • "requestId": 1,
  • "dcfCode": "DCF-1",
  • "controlName": "Access Reviews",
  • "controlDescription": "The organization performs quarterly access reviews.",
  • "controlId": 1,
  • "confidenceLevel": "HIGH",
  • "rationale": "This control answers the request because it covers access governance.",
  • "status": "PENDING",
  • "acceptanceSource": "MANUAL",
  • "decidedById": 1,
  • "decidedAt": "2025-07-01T16:45:55.246Z",
  • "createdAt": "2025-07-01T16:45:55.246Z",
  • "updatedAt": "2025-07-01T16:45:55.246Z"
}

Decide an Audit Request DCF Suggestion 🧪

🧪 Note: This endpoint is in beta and may change.

🔒 Requires Audits: Update Audit Request DCF Suggestions permission.

Securitybearer or oauth2
Request
path Parameters
workspaceId
required
number

The Workspace ID associated to the Account

auditId
required
string
requestId
required
number
suggestionId
required
number
Request Body schema: application/json
required
action
required
string

The decision to make on the suggestion

Enum: "ACCEPT" "REJECT"
Responses
200

Successful

400

Malformed data and/or validation errors

401

Invalid Authorization

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/workspaces/{workspaceId}/audits/{auditId}/requests/{requestId}/dcf-suggestions/{suggestionId}/actions
Request samples
application/json
{
  • "action": "ACCEPT"
}
Response samples
application/json
{
  • "id": 1,
  • "requestId": 1,
  • "dcfCode": "DCF-1",
  • "controlName": "Access Reviews",
  • "controlDescription": "The organization performs quarterly access reviews.",
  • "controlId": 1,
  • "confidenceLevel": "HIGH",
  • "rationale": "This control answers the request because it covers access governance.",
  • "status": "PENDING",
  • "acceptanceSource": "MANUAL",
  • "decidedById": 1,
  • "decidedAt": "2025-07-01T16:45:55.246Z",
  • "createdAt": "2025-07-01T16:45:55.246Z",
  • "updatedAt": "2025-07-01T16:45:55.246Z"
}

Accept Audit Request DCF Suggestions 🧪

🧪 Note: This endpoint is in beta and may change.

🔒 Requires Audits: Update Audit Request DCF Suggestions permission.

Securitybearer or oauth2
Request
path Parameters
workspaceId
required
number

The Workspace ID associated to the Account

auditId
required
string
Request Body schema: application/json
required
requestIds
Array of numbers [ 1 .. 500 ] items unique

Audit requests whose pending suggestions to accept. Required unless allRequests is true; send one or the other, not both.

allRequests
boolean

When true, accept on every request in the audit that has a matching pending suggestion, up to 500 requests; above that the call is rejected and the requests must be sent in batches through requestIds. Cannot be sent together with requestIds.

confidenceLevels
Array of strings (ConfidenceLevelEnum) non-empty unique

Accept only pending suggestions at these confidence levels. When omitted, every level is accepted.

Items Enum: "HIGH" "MEDIUM" "LOW"
Responses
200

Successful

400

Malformed data and/or validation errors

401

Invalid Authorization

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/workspaces/{workspaceId}/audits/{auditId}/requests/action-accept-dcf-suggestions
Request samples
application/json
{
  • "requestIds": [
    • 1,
    • 2
    ],
  • "allRequests": false,
  • "confidenceLevels": [
    • "HIGH"
    ]
}
Response samples
application/json
{
  • "data": [
    • {
      • "requestId": 1,
      • "acceptedCount": 3,
      • "mappedCount": 3,
      • "unresolvedCount": 0,
      • "error": null
      }
    ]
}

Generate Audit Request DCF Suggestions 🧪

Starts DCF suggestion generation for each audit request and returns without waiting for it to finish. Each row reports whether a run was STARTED, SKIPPED (a run is already in progress) or FAILED to start. To track progress, list the audit requests (GET .../audits/:auditId/requests) or get one (GET .../audits/:auditId/requests/:requestId) with expand[]=dcfSuggestionsSummary and read generationStatus, or get the audit (GET .../audits/:auditId) with the same expand and wait for requestsGeneratingCount to reach 0.

🧪 Note: This endpoint is in beta and may change.

🔒 Requires Audits: Update Audit Request DCF Suggestions permission.

Securitybearer or oauth2
Request
path Parameters
workspaceId
required
number

The Workspace ID associated to the Account

auditId
required
string
Request Body schema: application/json
required
requestIds
required
Array of numbers [ 1 .. 100 ] items unique

Audit requests to generate DCF suggestions for

Responses
202

Generation was requested; see each row for its outcome.

400

Malformed data and/or validation errors

401

Invalid Authorization

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/workspaces/{workspaceId}/audits/{auditId}/requests/action-generate-dcf-suggestions
Request samples
application/json
{
  • "requestIds": [
    • 1,
    • 2
    ]
}
Response samples
application/json
{
  • "data": [
    • {
      • "requestId": 1,
      • "status": "STARTED",
      • "error": null
      }
    ]
}

List Audit Requests

🔒 Requires Customer Request: Get Customer Request permission.

Securitybearer or oauth2
Request
path Parameters
workspaceId
required
number

The Workspace ID associated to the Account

auditId
required
string
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"
status[]
Array of strings (CustomerRequestStatus)

Filter by audit request status

Items Enum: "OUTSTANDING" "IN_REVIEW" "ACCEPTED" "CHANGES_REQUESTED"
userIds[]
Array of numbers

Filter by IDs of users assigned as owners of the audit request

Example: userIds[]=1&userIds[]=2&userIds[]=3
expand[]
Array of strings (AuditRequestListExpandEnum)

List of subcollections and sub-objects to expand

Items Enum: "owners" "messages" "dcfSuggestionsSummary"
Responses
200

Successful

400

Malformed data and/or validation errors

401

Invalid Authorization

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/workspaces/{workspaceId}/audits/{auditId}/requests
Request samples
Response samples
application/json
{
  • "data": [
    • {
      • "id": 1,
      • "code": "REQ-001",
      • "title": "Provide SOC 2 report",
      • "description": "Please provide the latest SOC 2 Type II report.",
      • "status": "OUTSTANDING",
      • "auditId": "aaaaaaaa-bbbb-0000-cccc-dddddddddddd",
      • "createdAt": "2025-07-01T16:45:55.246Z",
      • "updatedAt": "2025-07-01T16:45:55.246Z",
      • "owners": [
        • {
          • "id": 1,
          • "email": "[email protected]",
          • "firstName": "Sally",
          • "lastName": "Smith",
          • "createdAt": "2025-07-01T16:45:55.246Z",
          • "updatedAt": "2025-07-01T16:45:55.246Z"
          }
        ],
      • "messages": [
        • {
          • "id": 1,
          • "message": "Please provide the latest SOC 2 report.",
          • "sentByEmail": "[email protected]",
          • "createdAt": "2025-07-01T16:45:55.246Z",
          • "updatedAt": "2025-07-01T16:45:55.246Z"
          }
        ],
      • "dcfSuggestionsSummary": {
        • "generationStatus": "COMPLETED",
        • "totalCount": 5,
        • "pendingCount": 3,
        • "acceptedCount": 2
        }
      }
    ],
  • "pagination": {
    • "cursor": "string"
    }
}

Get Audit Request

🔒 Requires Customer Request: Get Customer Request permission.

Securitybearer or oauth2
Request
path Parameters
workspaceId
required
number

The Workspace ID associated to the Account

auditId
required
string
requestId
required
number
query Parameters
expand[]
Array of strings (AuditRequestExpandEnum)

List of subcollections and sub-objects to expand

Items Enum: "owners" "messages" "controls" "dcfSuggestionsSummary"
Responses
200

Successful

400

Malformed data and/or validation errors

401

Invalid Authorization

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/workspaces/{workspaceId}/audits/{auditId}/requests/{requestId}
Request samples
Response samples
application/json
{
  • "id": 1,
  • "code": "REQ-001",
  • "title": "Provide SOC 2 report",
  • "description": "Please provide the latest SOC 2 Type II report.",
  • "status": "OUTSTANDING",
  • "auditId": "aaaaaaaa-bbbb-0000-cccc-dddddddddddd",
  • "createdAt": "2025-07-01T16:45:55.246Z",
  • "updatedAt": "2025-07-01T16:45:55.246Z",
  • "owners": [
    • {
      • "id": 1,
      • "email": "[email protected]",
      • "firstName": "Sally",
      • "lastName": "Smith",
      • "createdAt": "2025-07-01T16:45:55.246Z",
      • "updatedAt": "2025-07-01T16:45:55.246Z"
      }
    ],
  • "messages": [
    • {
      • "id": 1,
      • "message": "Please provide the latest SOC 2 report.",
      • "sentByEmail": "[email protected]",
      • "createdAt": "2025-07-01T16:45:55.246Z",
      • "updatedAt": "2025-07-01T16:45:55.246Z"
      }
    ],
  • "controls": [
    • {
      • "id": 1,
      • "code": "DCF-1001",
      • "name": "Vulnerability Management",
      • "controlNumber": 1
      }
    ],
  • "dcfSuggestionsSummary": {
    • "generationStatus": "COMPLETED",
    • "totalCount": 5,
    • "pendingCount": 3,
    • "acceptedCount": 2
    }
}