Personnel

Personnel are people who work for your organization. The help docs have more information.

List Personnel

Get a paginated list of Personnel records.

🔒 Requires Personnel: List Personnel permission.

Securitybearer
Request
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 .. 50 ]
Default: 20

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"
expand[]
Array of strings (PersonnelExpandEnum)

List of subcollections and sub-objects to expand

Items Enum: "customFields" "complianceChecks" "reasonProvider" "user"
employmentStatus[]
Array of strings (EmploymentStatusEnum)

Personnel by employment statuses

Items Enum Value Description
CURRENT_EMPLOYEE

Current Employee

FORMER_EMPLOYEE

Former Employee

CURRENT_CONTRACTOR

Current Contractor

FORMER_CONTRACTOR

Former Contractor

FUTURE_HIRE

Future Hire – Based on the HRIS data

UNKNOWN

Unknown – The personnel did not match an HRIS record

OUT_OF_SCOPE

Out of Scope – Manually marked as out of scope

SERVICE_ACCOUNT

Service Account – Automatically marked as out of scope

SPECIAL_FORMER_EMPLOYEE

Special Former Employee – Deprecated status for manually created personnel

SPECIAL_FORMER_CONTRACTOR

Special Former Contractor – Deprecated status for manually created personnel

Responses
200

Successful

400

Malformed data and/or validation errors

401

Invalid Authorization

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/personnel
Request samples 
Response samples 
application/json
{
  • "data": [
    • {
      • "id": 1,
      • "userId": 1,
      • "user": {
        • "id": 1,
        • "email": "[email protected]",
        • "firstName": "Sally",
        • "lastName": "Smith",
        • "createdAt": "2025-07-01T16:45:55.246Z",
        • "updatedAt": "2025-07-01T16:45:55.246Z"
        },
      • "employmentStatus": "CURRENT_EMPLOYEE",
      • "notHumanReason": "This is not a real personnel, but a placeholder for anyone in charge of X",
      • "reasonProvider": {
        • "id": 1,
        • "email": "[email protected]",
        • "firstName": "Sally",
        • "lastName": "Smith",
        • "createdAt": "2025-07-01T16:45:55.246Z",
        • "updatedAt": "2025-07-01T16:45:55.246Z"
        },
      • "complianceChecks": [
        • {
          • "id": 1,
          • "type": "FULL_COMPLIANCE",
          • "status": "MISCONFIGURED",
          • "checkFrequency": "ONCE",
          • "expiresAt": "2019-08-24T14:15:22Z",
          • "lastCheckedAt": "2019-08-24T14:15:22Z",
          • "completionDate": "2019-08-24T14:15:22Z",
          • "createdAt": "2023-01-01T00:00:00.000Z",
          • "updatedAt": "2023-01-01T00:00:00.000Z"
          }
        ],
      • "startedAt": "2023-01-01T00:00:00.000Z",
      • "separatedAt": "2023-12-31T00:00:00.000Z",
      • "statusUpdatedAt": "2019-08-24T14:15:22Z",
      • "createdAt": "2023-01-01T00:00:00.000Z",
      • "updatedAt": "2023-01-01T00:00:00.000Z",
      • "customFields": [
        • {
          • "customFieldId": 1,
          • "name": "Stakeholders",
          • "value": "Security & IT"
          }
        ]
      }
    ],
  • "pagination": {
    • "cursor": "string"
    }
}
Get Personnel
Get a single Personnel record.


🔒 Requires Personnel: Get Personnel permission.


Securitybearer 
Request 
path Parameters
required
number or string
An integer Personnel ID or User's email address prefixed with email:


 
query Parameters
expand[]
Array of strings (PersonnelExpandEnum) 
List of subcollections and sub-objects to expand


Items Enum: "customFields" "complianceChecks" "reasonProvider" "user"  
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/personnel/{personnelId}
Request samples 
Response samples 
application/json
{
  • "id": 1,
  • "userId": 1,
  • "user": {
    • "id": 1,
    • "email": "[email protected]",
    • "firstName": "Sally",
    • "lastName": "Smith",
    • "createdAt": "2025-07-01T16:45:55.246Z",
    • "updatedAt": "2025-07-01T16:45:55.246Z"
    },
  • "employmentStatus": "CURRENT_EMPLOYEE",
  • "notHumanReason": "This is not a real personnel, but a placeholder for anyone in charge of X",
  • "reasonProvider": {
    • "id": 1,
    • "email": "[email protected]",
    • "firstName": "Sally",
    • "lastName": "Smith",
    • "createdAt": "2025-07-01T16:45:55.246Z",
    • "updatedAt": "2025-07-01T16:45:55.246Z"
    },
  • "complianceChecks": [
    • {
      • "id": 1,
      • "type": "FULL_COMPLIANCE",
      • "status": "MISCONFIGURED",
      • "checkFrequency": "ONCE",
      • "expiresAt": "2019-08-24T14:15:22Z",
      • "lastCheckedAt": "2019-08-24T14:15:22Z",
      • "completionDate": "2019-08-24T14:15:22Z",
      • "createdAt": "2023-01-01T00:00:00.000Z",
      • "updatedAt": "2023-01-01T00:00:00.000Z"
      }
    ],
  • "startedAt": "2023-01-01T00:00:00.000Z",
  • "separatedAt": "2023-12-31T00:00:00.000Z",
  • "statusUpdatedAt": "2019-08-24T14:15:22Z",
  • "createdAt": "2023-01-01T00:00:00.000Z",
  • "updatedAt": "2023-01-01T00:00:00.000Z",
  • "customFields": [
    • {
      • "customFieldId": 1,
      • "name": "Stakeholders",
      • "value": "Security & IT"
      }
    ]
}
Update Personnel
Update a single Personnel record. Note: Once fields are manually updated, automatic updates from identity providers (IDP) and HRIS systems will be ignored for those fields. Use the resync endpoint to restore automatic updates.


🔒 Requires Personnel: Update Personnel - applies to V2 only permission.


Securitybearer 
Request 
path Parameters
required
number or string
An integer Personnel ID or User's email address prefixed with email:


 
Request Body schema: application/json
required
startedAt
string
The date when this person started working at the company. Note: Once manually set, automatic updates from identity providers (IDP) and HRIS systems will be ignored. Use the resync endpoint to restore automatic updates.


 
separatedAt
string
The date when this person was separated from the company system.


 
employmentStatus
string
The desired employment status to be updated


 Enum Value Description
CURRENT_EMPLOYEE
Current Employee


FORMER_EMPLOYEE
Former Employee


CURRENT_CONTRACTOR
Current Contractor


FORMER_CONTRACTOR
Former Contractor


FUTURE_HIRE
Future Hire – Based on the HRIS data


UNKNOWN
Unknown – The personnel did not match an HRIS record


OUT_OF_SCOPE
Out of Scope – Manually marked as out of scope


SERVICE_ACCOUNT
Service Account – Automatically marked as out of scope


SPECIAL_FORMER_EMPLOYEE
Special Former Employee – Deprecated status for manually created personnel


SPECIAL_FORMER_CONTRACTOR
Special Former Contractor – Deprecated status for manually created personnel


 
notHumanReason
string  <= 30000 characters 
Explains why the employment status of this personnel is marked as OUT_OF_SCOPE. This field is required if the employmentStatus is set to OUT_OF_SCOPE.


 
Array of objects (CustomFieldSubmitRequestPublicV2Dto) 
Custom Fields for the Person


 
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/personnel/{personnelId}
Request samples 
application/json
{
  • "startedAt": "2020-07-06",
  • "separatedAt": "2020-07-06",
  • "employmentStatus": "CURRENT_CONTRACTOR",
  • "notHumanReason": "This is not a real personnel, but a placeholder for anyone in charge of X",
  • "customFields": [
    • {
      • "id": 1,
      • "name": "Compliance Status",
      • "value": "Security & IT"
      }
    ]
}
Response samples 
application/json
{
  • "id": 1,
  • "userId": 1,
  • "user": {
    • "id": 1,
    • "email": "[email protected]",
    • "firstName": "Sally",
    • "lastName": "Smith",
    • "createdAt": "2025-07-01T16:45:55.246Z",
    • "updatedAt": "2025-07-01T16:45:55.246Z"
    },
  • "employmentStatus": "CURRENT_EMPLOYEE",
  • "notHumanReason": "This is not a real personnel, but a placeholder for anyone in charge of X",
  • "reasonProvider": {
    • "id": 1,
    • "email": "[email protected]",
    • "firstName": "Sally",
    • "lastName": "Smith",
    • "createdAt": "2025-07-01T16:45:55.246Z",
    • "updatedAt": "2025-07-01T16:45:55.246Z"
    },
  • "complianceChecks": [
    • {
      • "id": 1,
      • "type": "FULL_COMPLIANCE",
      • "status": "MISCONFIGURED",
      • "checkFrequency": "ONCE",
      • "expiresAt": "2019-08-24T14:15:22Z",
      • "lastCheckedAt": "2019-08-24T14:15:22Z",
      • "completionDate": "2019-08-24T14:15:22Z",
      • "createdAt": "2023-01-01T00:00:00.000Z",
      • "updatedAt": "2023-01-01T00:00:00.000Z"
      }
    ],
  • "startedAt": "2023-01-01T00:00:00.000Z",
  • "separatedAt": "2023-12-31T00:00:00.000Z",
  • "statusUpdatedAt": "2019-08-24T14:15:22Z",
  • "createdAt": "2023-01-01T00:00:00.000Z",
  • "updatedAt": "2023-01-01T00:00:00.000Z",
  • "customFields": [
    • {
      • "customFieldId": 1,
      • "name": "Stakeholders",
      • "value": "Security & IT"
      }
    ]
}