Users

Find users by search terms and filters

List users given the provided search terms and filters

🔒 Requires Users: List Users permission.

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

q
string

User first name, or last name, or email, or full name

Example: q=John Doe
roles[]
Array of strings non-empty

A set of User Roles to filter to

Items Enum: "EMPLOYEE" "TECHGOV" "AUDITOR" "ADMIN" "ACT_AS_READ_ONLY" "APP" "RISK_MANAGER" "WORKSPACE_ADMINISTRATOR" "SERVICE_USER" "REVIEWER" "CONTROL_MANAGER" "PEOPLE_OPS" "POLICY_MANAGER" "DEVOPS_ENGINEER" "KNOWLEDGE_BASE" "TRUST_CENTER_MANAGER" "TRUST_CENTER_REVIEWER" "RISK_REGISTER_OWNER"
Example: roles[]=ADMIN&roles[]=TECHGOV
excludeUserIds[]
Array of numbers or null non-empty

A set of user ids to exclude from the returned set

Example: excludeUserIds[]=1&excludeUserIds[]=2&excludeUserIds[]=3
excludeRoles[]
Array of strings or null non-empty

A set of roles to exclude from the returned set

Enum: "EMPLOYEE" "TECHGOV" "AUDITOR" "ADMIN" "ACT_AS_READ_ONLY" "APP" "RISK_MANAGER" "WORKSPACE_ADMINISTRATOR" "SERVICE_USER" "REVIEWER" "CONTROL_MANAGER" "PEOPLE_OPS" "POLICY_MANAGER" "DEVOPS_ENGINEER" "KNOWLEDGE_BASE" "TRUST_CENTER_MANAGER" "TRUST_CENTER_REVIEWER" "RISK_REGISTER_OWNER"
Example: excludeRoles[]=WORKSPACE_ADMINISTRATOR&excludeRoles[]=TECHGOV
includeUserIds[]
Array of numbers or null non-empty

A set of users to return

Example: includeUserIds[]=1&includeUserIds[]=2&includeUserIds[]=3
Responses
200
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/users
Request samples 
Response samples 
application/json
{
  • "data": [
    • {
      • "id": 1,
      • "entryId": "aaaaaaaa-bbbb-0000-cccc-dddddddddddd",
      • "email": "[email protected]",
      • "firstName": "Sally",
      • "lastName": "Smith",
      • "jobTitle": "CEO",
      • "avatarUrl": "https://cdn-prod.imgpilot.com/avatar.png",
      • "drataTermsAgreedAt": "2025-07-01T16:45:55.246Z",
      • "createdAt": "2025-07-01T16:45:55.246Z",
      • "updatedAt": "2025-07-01T16:45:55.246Z",
      • "roles": [
        • "ROLE",
        • "ANOTHER_ROLE"
        ],
      • "backgroundChecks": [
        • {
          • "id": 1,
          • "userId": 1,
          • "status": "OK",
          • "caseId": "abc123",
          • "caseInvitationId": "abc123",
          • "url": "https://app-stage.karmacheck.com/background_check/aaaaaaaa-bbbb-0000-cccc-dddddddddddd",
          • "manualCheckDate": "2020-07-06",
          • "manuallyCheckUrl": "url.com",
          • "type": "CERTN",
          • "source": "DRATA",
          • "reportData": "string",
          • "user": { },
          • "outOfScopeReason": "abc123",
          • "outOfScopeAt": "2025-07-01T16:45:55.246Z",
          • "invitationEmail": "[email protected]",
          • "linkedAt": "2025-07-01T16:45:55.246Z",
          • "createdAt": "2025-07-01T16:45:55.246Z",
          • "updatedAt": "2025-07-01T16:45:55.246Z"
          }
        ],
      • "identities": [
        • {
          • "id": 1,
          • "identityId": "1a2b3c",
          • "username": "Username",
          • "connectedAt": "2025-07-01T16:45:55.246Z",
          • "disconnectedAt": "2025-07-01T16:45:55.246Z",
          • "hasMfa": true,
          • "user": { },
          • "connection": {
            • "id": "1",
            • "clientType": "GOOGLE",
            • "state": "ACTIVE",
            • "connected": false,
            • "connectedAt": "2025-07-01T16:45:55.246Z",
            • "failedAt": "2025-07-01T16:45:55.246Z",
            • "companyId": "12341234",
            • "assignmentId": "FLk12AsS",
            • "user": { },
            • "accountId": "string",
            • "clientId": "abc123",
            • "clientAlias": "My-connection-alias-1",
            • "manuallyUpdatedAt": "2025-07-01T16:45:55.246Z",
            • "aliasUpdatedAt": "2025-07-01T16:45:55.246Z",
            • "deletedAt": "2025-07-01T16:45:55.246Z",
            • "requestorId": "328d3016-71f3-4485-af20-06ce8044da18",
            • "product": { },
            • "writeAccessEnabled": false,
            • "sourcePreference": "LABEL",
            • "securityLabel": "Jira Security Label",
            • "jqlQuery": "project = IT AND type = \"Offboarding\"",
            • "authorized": true,
            • "workspaces": [],
            • "providerTypes": [
              • 5
              ],
            • "code": 10010,
            • "groupLabel": "Everyone"
            },
          • "hasIdp": true,
          • "secondaryEmail": "[email protected]",
          • "firstName": "John",
          • "lastName": "Doe",
          • "startedAt": "2025-07-01T16:45:55.246Z",
          • "separatedAt": "2025-07-01T16:45:55.246Z",
          • "isContractor": true,
          • "jobTitle": "Engineer",
          • "managerId": "x00jk12-2312",
          • "managerName": "string"
          }
        ],
      • "documents": [
        • {
          • "data": [
            • {
              • "id": 1,
              • "name": "Security Training",
              • "type": "SEC_TRAINING",
              • "fileUrl": "http://localhost:5000/download/documents/1",
              • "renewalDate": "2026-10-27",
              • "createdAt": "2025-07-01T16:45:55.246Z",
              • "updatedAt": "2025-07-01T16:45:55.246Z"
              }
            ],
          • "page": 1,
          • "limit": 10,
          • "total": 100
          }
        ]
      }
    ],
  • "page": 1,
  • "limit": 10,
  • "total": 100
}
Get user by id
Get the full detail of a user record


🔒 Requires Users: Get User permission.


Securitybearer 
Request 
path Parameters
id
required
number
 
Responses 
200
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/users/{id}
Request samples 
Response samples 
application/json
{
  • "id": 1,
  • "entryId": "aaaaaaaa-bbbb-0000-cccc-dddddddddddd",
  • "email": "[email protected]",
  • "firstName": "Sally",
  • "lastName": "Smith",
  • "jobTitle": "CEO",
  • "avatarUrl": "https://cdn-prod.imgpilot.com/avatar.png",
  • "drataTermsAgreedAt": "2025-07-01T16:45:55.246Z",
  • "createdAt": "2025-07-01T16:45:55.246Z",
  • "updatedAt": "2025-07-01T16:45:55.246Z",
  • "roles": [
    • "ROLE",
    • "ANOTHER_ROLE"
    ],
  • "backgroundChecks": [
    • {
      • "id": 1,
      • "userId": 1,
      • "status": "OK",
      • "caseId": "abc123",
      • "caseInvitationId": "abc123",
      • "url": "https://app-stage.karmacheck.com/background_check/aaaaaaaa-bbbb-0000-cccc-dddddddddddd",
      • "manualCheckDate": "2020-07-06",
      • "manuallyCheckUrl": "url.com",
      • "type": "CERTN",
      • "source": "DRATA",
      • "reportData": "string",
      • "user": { },
      • "outOfScopeReason": "abc123",
      • "outOfScopeAt": "2025-07-01T16:45:55.246Z",
      • "invitationEmail": "[email protected]",
      • "linkedAt": "2025-07-01T16:45:55.246Z",
      • "createdAt": "2025-07-01T16:45:55.246Z",
      • "updatedAt": "2025-07-01T16:45:55.246Z"
      }
    ],
  • "identities": [
    • {
      • "id": 1,
      • "identityId": "1a2b3c",
      • "username": "Username",
      • "connectedAt": "2025-07-01T16:45:55.246Z",
      • "disconnectedAt": "2025-07-01T16:45:55.246Z",
      • "hasMfa": true,
      • "user": { },
      • "connection": {
        • "id": "1",
        • "clientType": "GOOGLE",
        • "state": "ACTIVE",
        • "connected": false,
        • "connectedAt": "2025-07-01T16:45:55.246Z",
        • "failedAt": "2025-07-01T16:45:55.246Z",
        • "companyId": "12341234",
        • "assignmentId": "FLk12AsS",
        • "user": { },
        • "accountId": "string",
        • "clientId": "abc123",
        • "clientAlias": "My-connection-alias-1",
        • "manuallyUpdatedAt": "2025-07-01T16:45:55.246Z",
        • "aliasUpdatedAt": "2025-07-01T16:45:55.246Z",
        • "deletedAt": "2025-07-01T16:45:55.246Z",
        • "requestorId": "328d3016-71f3-4485-af20-06ce8044da18",
        • "product": { },
        • "writeAccessEnabled": false,
        • "sourcePreference": "LABEL",
        • "securityLabel": "Jira Security Label",
        • "jqlQuery": "project = IT AND type = \"Offboarding\"",
        • "authorized": true,
        • "workspaces": [],
        • "providerTypes": [
          • 5
          ],
        • "code": 10010,
        • "groupLabel": "Everyone"
        },
      • "hasIdp": true,
      • "secondaryEmail": "[email protected]",
      • "firstName": "John",
      • "lastName": "Doe",
      • "startedAt": "2025-07-01T16:45:55.246Z",
      • "separatedAt": "2025-07-01T16:45:55.246Z",
      • "isContractor": true,
      • "jobTitle": "Engineer",
      • "managerId": "x00jk12-2312",
      • "managerName": "string"
      }
    ],
  • "documents": [
    • {
      • "data": [
        • {
          • "id": 1,
          • "name": "Security Training",
          • "type": "SEC_TRAINING",
          • "fileUrl": "http://localhost:5000/download/documents/1",
          • "renewalDate": "2026-10-27",
          • "createdAt": "2025-07-01T16:45:55.246Z",
          • "updatedAt": "2025-07-01T16:45:55.246Z"
          }
        ],
      • "page": 1,
      • "limit": 10,
      • "total": 100
      }
    ]
}
Get user by email
Get the full detail of a user record


🔒 Requires Users: Get User permission.


Securitybearer 
Request 
path Parameters
email
required
string
 
Responses 
200
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/users/{email}/email
Request samples 
Response samples 
application/json
{
  • "id": 1,
  • "entryId": "aaaaaaaa-bbbb-0000-cccc-dddddddddddd",
  • "email": "[email protected]",
  • "firstName": "Sally",
  • "lastName": "Smith",
  • "jobTitle": "CEO",
  • "avatarUrl": "https://cdn-prod.imgpilot.com/avatar.png",
  • "drataTermsAgreedAt": "2025-07-01T16:45:55.246Z",
  • "createdAt": "2025-07-01T16:45:55.246Z",
  • "updatedAt": "2025-07-01T16:45:55.246Z",
  • "roles": [
    • "ROLE",
    • "ANOTHER_ROLE"
    ],
  • "backgroundChecks": [
    • {
      • "id": 1,
      • "userId": 1,
      • "status": "OK",
      • "caseId": "abc123",
      • "caseInvitationId": "abc123",
      • "url": "https://app-stage.karmacheck.com/background_check/aaaaaaaa-bbbb-0000-cccc-dddddddddddd",
      • "manualCheckDate": "2020-07-06",
      • "manuallyCheckUrl": "url.com",
      • "type": "CERTN",
      • "source": "DRATA",
      • "reportData": "string",
      • "user": { },
      • "outOfScopeReason": "abc123",
      • "outOfScopeAt": "2025-07-01T16:45:55.246Z",
      • "invitationEmail": "[email protected]",
      • "linkedAt": "2025-07-01T16:45:55.246Z",
      • "createdAt": "2025-07-01T16:45:55.246Z",
      • "updatedAt": "2025-07-01T16:45:55.246Z"
      }
    ],
  • "identities": [
    • {
      • "id": 1,
      • "identityId": "1a2b3c",
      • "username": "Username",
      • "connectedAt": "2025-07-01T16:45:55.246Z",
      • "disconnectedAt": "2025-07-01T16:45:55.246Z",
      • "hasMfa": true,
      • "user": { },
      • "connection": {
        • "id": "1",
        • "clientType": "GOOGLE",
        • "state": "ACTIVE",
        • "connected": false,
        • "connectedAt": "2025-07-01T16:45:55.246Z",
        • "failedAt": "2025-07-01T16:45:55.246Z",
        • "companyId": "12341234",
        • "assignmentId": "FLk12AsS",
        • "user": { },
        • "accountId": "string",
        • "clientId": "abc123",
        • "clientAlias": "My-connection-alias-1",
        • "manuallyUpdatedAt": "2025-07-01T16:45:55.246Z",
        • "aliasUpdatedAt": "2025-07-01T16:45:55.246Z",
        • "deletedAt": "2025-07-01T16:45:55.246Z",
        • "requestorId": "328d3016-71f3-4485-af20-06ce8044da18",
        • "product": { },
        • "writeAccessEnabled": false,
        • "sourcePreference": "LABEL",
        • "securityLabel": "Jira Security Label",
        • "jqlQuery": "project = IT AND type = \"Offboarding\"",
        • "authorized": true,
        • "workspaces": [],
        • "providerTypes": [
          • 5
          ],
        • "code": 10010,
        • "groupLabel": "Everyone"
        },
      • "hasIdp": true,
      • "secondaryEmail": "[email protected]",
      • "firstName": "John",
      • "lastName": "Doe",
      • "startedAt": "2025-07-01T16:45:55.246Z",
      • "separatedAt": "2025-07-01T16:45:55.246Z",
      • "isContractor": true,
      • "jobTitle": "Engineer",
      • "managerId": "x00jk12-2312",
      • "managerName": "string"
      }
    ],
  • "documents": [
    • {
      • "data": [
        • {
          • "id": 1,
          • "name": "Security Training",
          • "type": "SEC_TRAINING",
          • "fileUrl": "http://localhost:5000/download/documents/1",
          • "renewalDate": "2026-10-27",
          • "createdAt": "2025-07-01T16:45:55.246Z",
          • "updatedAt": "2025-07-01T16:45:55.246Z"
          }
        ],
      • "page": 1,
      • "limit": 10,
      • "total": 100
      }
    ]
}
Find user documents by user id
List user documents given the provided search terms and filters.


🔒 Requires Users: List User Documents permission.


Securitybearer 
Request 
path Parameters
id
required
number
 
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


 
q
string
Filter documents by name


 
 Example:  q=Security training 2020
type
string
Filter documents by their type


 Enum: "SEC_TRAINING" "PASSWORD_MANAGER_EVIDENCE" "AUTO_UPDATES_EVIDENCE" "HARD_DRIVE_ENCRYPTION_EVIDENCE" "ANTIVIRUS_EVIDENCE" "LOCK_SCREEN_EVIDENCE" "MFA_EVIDENCE" "HIPAA_TRAINING_EVIDENCE" "OFFBOARDING_EVIDENCE" "NIST_AI_TRAINING_EVIDENCE"  
 Example:  type=SEC_TRAINING
Responses 
200
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/users/{id}/documents
Request samples 
Response samples 
application/json
{
  • "documents": [
    • {
      • "id": 1,
      • "name": "Security Training",
      • "type": "SEC_TRAINING",
      • "fileUrl": "http://localhost:5000/download/documents/1",
      • "renewalDate": "2026-10-27",
      • "createdAt": "2025-07-01T16:45:55.246Z",
      • "updatedAt": "2025-07-01T16:45:55.246Z"
      }
    ]
}
Upload a document for user by user id
Upload document for user.


🔒 Requires Users: Create User Document permission.


Securitybearer 
Request 
path Parameters
id
required
number
 
Request Body schema: 
required
type
required
string
The user document type


 Enum: "MFA_EVIDENCE" "SEC_TRAINING" "HIPAA_TRAINING_EVIDENCE" "OFFBOARDING_EVIDENCE"  
file
string <binary> 
Accepted file extensions: .pdf, .docx, .odt, .xlsx, .ods, .pptx, .odp, .gif, .jpeg, .jpg, .png


 
base64File
string
JSON string with external evidence in Base64 format.


 
completionDate
string <date-time> 
The date when the compliance was completed


 
Responses 
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


413
The file was too large to upload


500
Internal server error


503
Third party system was unavailable


post/users/{id}/documents
Request samples 
No sample
Response samples 
application/json
{
  • "id": 1,
  • "name": "Security Training",
  • "type": "SEC_TRAINING",
  • "fileUrl": "http://localhost:5000/download/documents/1",
  • "renewalDate": "2026-10-27",
  • "createdAt": "2025-07-01T16:45:55.246Z",
  • "updatedAt": "2025-07-01T16:45:55.246Z"
}
Get user document download link by document id
Get signed download link for user document.


🔒 Requires Users: Download User Document permission.


Securitybearer 
Request 
path Parameters
id
required
number
 
Responses 
200
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/users/documents/{id}/download
Request samples 
Response samples 
application/json
{}
Remove user document by document id and user id
Remove user document.


🔒 Requires Users: Delete User Document permission.


Securitybearer 
Request 
path Parameters
docId
required
number
 
userId
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/users/documents/{docId}/{userId}
Request samples 
Response samples 
application/json
{
  • "statusCode": 0,
  • "message": "string",
  • "code": 0,
  • "debugInfo": {
    • "name": "string",
    • "message": "string",
    • "stack": "string"
    }
}