Create a personnel event¶

This page explains how to create a Personnel Event in Permission Assist through the API. Each event type has its own endpoint and requires different data fields.

Before you begin¶

Make sure you have the following:

API credentials (refer to Getting started)
For Onboarding: the new employee's identity information (name, department, title, and so on)
For all other event types: the identityId of an existing identity in Permission Assist
The event-specific data required for the type of event you are creating

Send the request¶

To create a Personnel Event, send a POST request to the endpoint for the event type you want to create. Each event type has a dedicated endpoint.

Onboarding¶

Send a POST request to /api/personnel-events/onboard with the new employee's identity metadata inside an identity object. Permission Assist creates the identity during the Approve milestone of the Personnel Event workflow, matching the same process as a manually created Onboarding event.

curlPowerShell

curl -X POST https://[your-pa-server]/api/personnel-events/onboard \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer [your-token]" \
  -d '{
    "identity": {
      "firstName": "Jane",
      "lastName": "Smith",
      "email": "jane.smith@valkyriecu.com",
      "company": "Valkyrie Credit Union",
      "division": "Operations",
      "department": "Lending",
      "office": "Main Branch",
      "title": "Loan Officer",
      "supervisorId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
    },
    "effectiveDate": "2026-03-15",
    "comment": "New hire starting in Lending department"
  }'

$headers = @{
    "Content-Type"  = "application/json"
    "Authorization" = "Bearer [your-token]"
}

$body = @{
    identity = @{
        firstName    = "Jane"
        lastName     = "Smith"
        email        = "jane.smith@valkyriecu.com"
        company      = "Valkyrie Credit Union"
        division     = "Operations"
        department   = "Lending"
        office       = "Main Branch"
        title        = "Loan Officer"
        supervisorId = "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
    }
    effectiveDate = "2026-03-15"
    comment       = "New hire starting in Lending department"
} | ConvertTo-Json -Depth 3

Invoke-RestMethod `
    -Uri "https://[your-pa-server]/api/personnel-events/onboard" `
    -Method POST `
    -Headers $headers `
    -Body $body

Offboarding¶

Send a POST request to /api/personnel-events/offboard with the identity of the departing employee.

curl -X POST https://[your-pa-server]/api/personnel-events/offboard \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer [your-token]" \
  -d '{
    "identityId": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "effectiveDate": "2026-03-15",
    "comment": "Voluntary resignation"
  }'

Role transition/position change¶

Send a POST request to /api/personnel-events/role-transition with the identity and the new role details. Include only the fields that are changing inside the identity object — fields set to null or omitted retain their existing values.

curl -X POST https://[your-pa-server]/api/personnel-events/role-transition \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer [your-token]" \
  -d '{
    "identityId": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "effectiveDate": "2026-04-01",
    "identity": {
      "title": "Senior Loan Officer",
      "department": "Commercial Lending",
      "supervisorId": "c3d4e5f6-a7b8-9012-cdef-123456789012"
    },
    "comment": "Promotion to Senior Loan Officer"
  }'

Leave of absence¶

Send a POST request to /api/personnel-events/leave-of-absence with the identity and leave dates.

curl -X POST https://[your-pa-server]/api/personnel-events/leave-of-absence \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer [your-token]" \
  -d '{
    "identityId": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "effectiveDate": "2026-05-01",
    "endDate": "2026-08-01",
    "comment": "FMLA leave"
  }'

Required fields by event type¶

Each event type requires a different set of fields. The following tables list the required and optional fields for each type.

Onboarding¶

Note

Onboarding events accept identity metadata because the identity does not yet exist in Permission Assist. The identity is created during the Approve milestone of the event workflow.

Field	Required	Description
`identity`	Yes	An object containing the new employee's identity metadata
`identity.firstName`	Yes	The employee's first name. Maximum 256 characters
`identity.lastName`	Yes	The employee's last name. Maximum 256 characters
`effectiveDate`	Yes	The employee's start date. Use `YYYY-MM-DD` format. Must be today or later
`identity.email`	No	The employee's email address. Maximum 256 characters
`identity.company`	No	The employee's company or organization name. Maximum 256 characters
`identity.division`	No	The employee's division. Maximum 256 characters
`identity.department`	No	The employee's department. Maximum 128 characters
`identity.office`	No	The employee's office or location. Maximum 256 characters
`identity.title`	No	The employee's job title. Maximum 256 characters
`identity.identityType`	No	The type of identity. Valid values: `Employee`, `ServiceAccount`, `Vendor`, `Shared`, `Mailbox`, `Client`, `Temporary`, `Administrator`, `Auditor`, `Unknown`. Default: `Employee`
`identity.supervisorId`	No	The Permission Assist identity ID of the employee's supervisor. Must be a valid identity GUID
`identity.customField1` through `identity.customField9`	No	Custom identity field values, if your organization has enabled custom fields. Maximum 2048 characters each
`comment`	No	A comment to include on the Personnel Event

Offboarding¶

Field	Required	Description
`identityId`	Yes	The Permission Assist identity ID of the departing employee
`effectiveDate`	Yes	The employee's last day. Use `YYYY-MM-DD` format. Must be today or later
`comment`	No	A comment to include on the Personnel Event

Role transition/position change¶

Field	Required	Description
`identityId`	Yes	The Permission Assist identity ID of the employee
`effectiveDate`	Yes	The date the role change takes effect. Use `YYYY-MM-DD` format. Must be today or later
`endDate`	No	The end date for the transition period, if applicable. Use `YYYY-MM-DD` format. Must be after `effectiveDate`
`identity`	No	An object containing the new identity metadata. Omitted or `null` fields retain their existing values
`identity.firstName`	No	The employee's new first name. Maximum 256 characters
`identity.lastName`	No	The employee's new last name. Maximum 256 characters
`identity.email`	No	The employee's new email address. Maximum 256 characters
`identity.company`	No	The employee's new company. Maximum 256 characters
`identity.division`	No	The employee's new division. Maximum 256 characters
`identity.department`	No	The employee's new department. Maximum 128 characters
`identity.office`	No	The employee's new office or location. Maximum 256 characters
`identity.title`	No	The employee's new job title. Maximum 256 characters
`identity.supervisorId`	No	The identity ID of the employee's new supervisor. Must be a valid identity GUID
`identity.customField1` through `identity.customField9`	No	Custom identity field values. Maximum 2048 characters each
`comment`	No	A comment to include on the Personnel Event

Leave of absence¶

Field	Required	Description
`identityId`	Yes	The Permission Assist identity ID of the employee
`effectiveDate`	Yes	The first day of leave. Use `YYYY-MM-DD` format. Must be today or later
`endDate`	No	The expected return date. Use `YYYY-MM-DD` format. Must be after `effectiveDate`
`comment`	No	A comment to include on the Personnel Event

Understand the response¶

A successful response returns the full Personnel Event object with its current state.

Success (HTTP 201):

{
  "id": "d4e5f6a7-b8c9-0123-def0-123456789abc",
  "kind": "Personnel Event",
  "number": 1042,
  "type": "Onboard",
  "status": "Pending",
  "reporter": {
    "id": "e5f6a7b8-c901-2345-ef01-23456789abcd",
    "name": "HRIS Integration"
  },
  "assignee": null,
  "affectedIdentity": {
    "id": "f6a7b8c9-0123-4567-f012-3456789abcde",
    "kind": "Identity",
    "firstName": "Jane",
    "lastName": "Smith",
    "emailAddress": "jane.smith@valkyriecu.com",
    "type": "Employee",
    "title": "Loan Officer",
    "company": "Valkyrie Credit Union",
    "division": "Operations",
    "department": "Lending",
    "office": "Main Branch",
    "supervisorName": "Robert Chen",
    "createdDate": "2026-03-15T14:30:00",
    "updatedDate": "2026-03-15T14:30:00",
    "firstSeenDate": "2026-03-15T14:30:00",
    "inactivatedDate": null,
    "status": "Active"
  },
  "neededOn": "2026-03-15T00:00:00",
  "neededUntil": null,
  "completedOn": null,
  "stages": [
    {
      "name": "Approval",
      "status": "Pending",
      "startedOn": null,
      "scheduledStart": "2026-03-08T00:00:00",
      "completedOn": null,
      "completedBy": null,
      "accessRequests": []
    },
    {
      "name": "Provision",
      "status": "Scheduled",
      "startedOn": null,
      "scheduledStart": null,
      "completedOn": null,
      "completedBy": null,
      "accessRequests": []
    },
    {
      "name": "Verification",
      "status": "Scheduled",
      "startedOn": null,
      "scheduledStart": null,
      "completedOn": null,
      "completedBy": null,
      "accessRequests": []
    }
  ],
  "activity": [],
  "comments": []
}

The reporter.name field displays the name of the API token that created the event. The number field is the human-readable event reference visible in the Permission Assist interface.

Error responses:

HTTP Status	Meaning
`400`	Missing or invalid required fields. The response body includes an `errors` array with details about each field that failed validation
`401`	Invalid or missing API credentials
`500`	The event could not be created due to a server-side error

For a complete list, refer to Error codes.

Example validation error (HTTP 400):

{
  "error": "validation_error",
  "message": "One or more validation errors occurred",
  "correlationId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "errors": [
    {
      "field": "identity.firstName",
      "message": "First name is required"
    },
    {
      "field": "effectiveDate",
      "message": "Effective date is required"
    }
  ]
}

Verify the event¶

After creating a Personnel Event through the API, you can verify it in Permission Assist.

To verify the event, complete the following steps:

Log in to Permission Assist.
Go to the Personnel Events taskboard.
Locate the event by its number (returned in the API response as number).

The audit trail records the name of the API token that created the event, so you can distinguish API-created events from manually created events.

Related topics:

Personnel Event API — Overview of the API, supported event types, and common use cases
API Reference — Complete request and response schemas for all Personnel Event endpoints