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 HRIS User Identities: List HRIS User Identities 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"
    }
}
Create or Update 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. Invalid items are reported per-item and do not prevent valid items from being processed.


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


🔒 Requires HRIS User Identities: Create or Update HRIS User Identities 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
List of HR user identity records to upsert. Duplicate identityId values within a batch are reported as per-item errors.


 Array ([ 1 .. 1000 ] items)
identityId
required
string
Customer-defined stable identifier for this record (e.g. employee ID, HRIS record ID). Used as the upsert key for batch submissions.


 
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 (e.g. the manager's identityId in the customer's HRIS system). 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
At least one record was updated (mix of creates and updates).


201
All records were newly created.


207
Some records succeeded and some failed. Per-item statusCode indicates each outcome.


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
[
  • {
    • "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
[
  • {
    • "statusCode": 201,
    • "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"
      },
    • "error": {
      • "message": "string"
      }
    }
]
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 HRIS User Identities: Get HRIS User Identity 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"
}
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, re-submit the record via the batch upsert endpoint with the separatedAt field set — 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 HRIS User Identities: Delete HRIS User Identity 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"
    }
}