HRIS User Identities

HR user identity records for a Custom HRIS connection. Use the batch upsert endpoint to submit employee records keyed by your own identityId, then use the update endpoint to reflect employment changes (e.g. set separatedAt when an employee leaves). Deleting a record is intended for data submitted in error, not for offboarding. Changes are not applied immediately — they are incorporated the next time identity sync runs, which happens nightly by default. A sync can also be triggered manually from the Personnel page.

List HRIS User Identities 🧪

Returns a cursor-paginated list of all active HR user identities for the specified custom HRIS connection.

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

🔒 Requires user-identities-hris-get permission.

💎 Requires your account have the Custom Connections and Tests feature. Contact your CSM for help upgrading.

Securitybearer
Request
path Parameters
connectionId
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" "name"
sortDir
string (SortDirectionEnum)

The direction to sort the data

Enum: "ASC" "DESC"
Responses
200

Successful

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/custom-connections/{connectionId}/hris-user-identities
Request samples 
Response samples 
application/json
{
  • "data": [
    • {
      • "id": 1001,
      • "identityId": "emp-001",
      • "email": "[email protected]",
      • "secondaryEmail": null,
      • "firstName": "Jane",
      • "lastName": "Doe",
      • "jobTitle": "Software Engineer",
      • "managerId": "emp-050",
      • "managerName": "Bob Manager",
      • "startedAt": "2022-03-01T00:00:00.000Z",
      • "separatedAt": null,
      • "isContractor": false,
      • "createdAt": "2026-03-26T10:00:00.000Z",
      • "updatedAt": "2026-03-26T10:00:00.000Z"
      }
    ],
  • "pagination": {
    • "cursor": "string"
    }
}
Batch Upsert HRIS User Identities 🧪
Submit one or more HR user identities for a custom HRIS connection. Each record is keyed by the customer-defined identityId. If a record with that identityId already exists for this connection, it is updated; otherwise a new record is created.


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


🔒 Requires user-identity-hris-post permission.


💎 Requires your account have the Custom Connections and Tests feature. Contact your CSM for help upgrading.


Securitybearer 
Request 
path Parameters
connectionId
required
number
 
Request Body schema: application/json
required
required
Array of objects (CustomUserIdentityRecordPublicV2Dto)   [ 1 .. 300 ] items 
List of HR user identity records to upsert. All identityId values within a single batch must be unique.


 
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


500
Internal server error


post/custom-connections/{connectionId}/hris-user-identities
Request samples 
application/json
{
  • "identities": [
    • {
      • "identityId": "emp-001",
      • "email": "[email protected]",
      • "secondaryEmail": "[email protected]",
      • "firstName": "Jane",
      • "lastName": "Doe",
      • "jobTitle": "Software Engineer",
      • "managerId": "emp-050",
      • "managerName": "Bob Manager",
      • "startedAt": "2022-03-01T00:00:00.000Z",
      • "separatedAt": "2024-12-31T00:00:00.000Z",
      • "isContractor": false
      }
    ]
}
Response samples 
application/json
[
  • {
    • "id": 1001,
    • "identityId": "emp-001",
    • "email": "[email protected]",
    • "secondaryEmail": null,
    • "firstName": "Jane",
    • "lastName": "Doe",
    • "jobTitle": "Software Engineer",
    • "managerId": "emp-050",
    • "managerName": "Bob Manager",
    • "startedAt": "2022-03-01T00:00:00.000Z",
    • "separatedAt": null,
    • "isContractor": false,
    • "createdAt": "2026-03-26T10:00:00.000Z",
    • "updatedAt": "2026-03-26T10:00:00.000Z"
    }
]
Get HRIS User Identity 🧪
Returns a single HR user identity by the Drata-assigned internal ID.


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


🔒 Requires user-identity-hris-get permission.


💎 Requires your account have the Custom Connections and Tests feature. Contact your CSM for help upgrading.


Securitybearer 
Request 
path Parameters
connectionId
required
number
 
userIdentityId
required
number
 
Responses 
200
Successful


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/custom-connections/{connectionId}/hris-user-identities/{userIdentityId}
Request samples 
Response samples 
application/json
{
  • "id": 1001,
  • "identityId": "emp-001",
  • "email": "[email protected]",
  • "secondaryEmail": null,
  • "firstName": "Jane",
  • "lastName": "Doe",
  • "jobTitle": "Software Engineer",
  • "managerId": "emp-050",
  • "managerName": "Bob Manager",
  • "startedAt": "2022-03-01T00:00:00.000Z",
  • "separatedAt": null,
  • "isContractor": false,
  • "createdAt": "2026-03-26T10:00:00.000Z",
  • "updatedAt": "2026-03-26T10:00:00.000Z"
}
Update HRIS User Identity 🧪
Updates an existing HR user identity. Only fields included in the request body are updated; omitted fields retain their current values.


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


🔒 Requires user-identity-hris-put permission.


💎 Requires your account have the Custom Connections and Tests feature. Contact your CSM for help upgrading.


Securitybearer 
Request 
path Parameters
connectionId
required
number
 
userIdentityId
required
number
 
Request Body schema: application/json
required
email
string or null <email>   <= 191 characters 
Primary email address. Used to match this record to an existing Drata user during identity sync.


 
secondaryEmail
string or null <email>   <= 191 characters 
Secondary email address.


 
firstName
string or null  <= 191 characters 
First name.


 
lastName
string or null  <= 191 characters 
Last name.


 
jobTitle
string or null  <= 191 characters 
Job title.


 
managerId
string or null  <= 191 characters 
The customer's own identifier for this person's manager. Not a Drata User ID.


 
managerName
string or null  <= 191 characters 
Manager's full name.


 
startedAt
string or null <date-time> 
Employment start date.


 
separatedAt
string or null <date-time> 
Employment end date. Set separatedAt to indicate the employee has left rather than deleting the record.


 
isContractor
boolean or null
If true, this person is a CURRENT_CONTRACTOR; false means CURRENT_EMPLOYEE. null means employment type is UNKNOWN — the person will appear as UNKNOWN in Drata until an explicit value is provided.


 
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


put/custom-connections/{connectionId}/hris-user-identities/{userIdentityId}
Request samples 
application/json
{
  • "email": "[email protected]",
  • "secondaryEmail": "[email protected]",
  • "firstName": "Jane",
  • "lastName": "Doe",
  • "jobTitle": "Senior Software Engineer",
  • "managerId": "emp-050",
  • "managerName": "Bob Manager",
  • "startedAt": "2022-03-01T00:00:00.000Z",
  • "separatedAt": "2024-12-31T00:00:00.000Z",
  • "isContractor": false
}
Response samples 
application/json
{
  • "id": 1001,
  • "identityId": "emp-001",
  • "email": "[email protected]",
  • "secondaryEmail": null,
  • "firstName": "Jane",
  • "lastName": "Doe",
  • "jobTitle": "Software Engineer",
  • "managerId": "emp-050",
  • "managerName": "Bob Manager",
  • "startedAt": "2022-03-01T00:00:00.000Z",
  • "separatedAt": null,
  • "isContractor": false,
  • "createdAt": "2026-03-26T10:00:00.000Z",
  • "updatedAt": "2026-03-26T10:00:00.000Z"
}
Delete HRIS User Identity 🧪
Soft-deletes an HR user identity. This endpoint is intended for removing records submitted in error (e.g. test data, duplicates, or employees who should never have been included). To indicate that an employee has left, use the PUT endpoint to set the separatedAt field instead — this preserves employment history and allows identity sync to correctly classify the person as FORMER_EMPLOYEE or FORMER_CONTRACTOR. If the deleted record was previously matched to a Drata user, that user's employment status will move to UNKNOWN at the next identity sync. A deleted record can be restored by re-submitting it via the batch upsert endpoint with the same identityId.


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


🔒 Requires user-identity-hris-delete permission.


💎 Requires your account have the Custom Connections and Tests feature. Contact your CSM for help upgrading.


Securitybearer 
Request 
path Parameters
connectionId
required
number
 
userIdentityId
required
number
 
Responses 
204
No Content


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/custom-connections/{connectionId}/hris-user-identities/{userIdentityId}
Request samples 
Response samples 
application/json
{
  • "statusCode": 0,
  • "message": "string",
  • "code": 0,
  • "debugInfo": {
    • "name": "string",
    • "message": "string",
    • "stack": "string"
    }
}