Create Role Transition¶

Endpoint: POST /api/personnel-events/role-transition

Description: Creates a new role transition personnel event for an existing identity, optionally including updated identity metadata.

Request Body¶

Field	Type	Required	Description
`identityId`	string (GUID)	Yes	The unique identifier of the identity transitioning roles. Must reference an existing identity.
`effectiveDate`	string (ISO 8601)	Yes	The date the role transition takes effect. Must be today or later.
`endDate`	string (ISO 8601)	No	The end date for the transition period. Must be after `effectiveDate` if provided.
`identity`	object	No	Updated identity metadata for the new role. Only provided fields are updated; omitted fields retain their current values.
`identity.firstName`	string	No	Updated first name. Max length: 256.
`identity.lastName`	string	No	Updated last name. Max length: 256.
`identity.email`	string	No	Updated email address. Max length: 256.
`identity.supervisorId`	string (GUID)	No	Updated supervisor identity ID. Must reference an existing identity.
`identity.company`	string	No	Updated company name. Max length: 256.
`identity.division`	string	No	Updated division name. Max length: 256.
`identity.department`	string	No	Updated department name. Max length: 128.
`identity.office`	string	No	Updated office location. Max length: 256.
`identity.title`	string	No	Updated job title. Max length: 256.
`identity.identityType`	string	No	Updated identity type. Max length: 50.
`identity.customField1`	string	No	Updated custom field 1. Max length: 2048. Only accepted if the custom field is enabled in system settings.
`identity.customField2`	string	No	Updated custom field 2. Max length: 2048. Only accepted if the custom field is enabled in system settings.
`identity.customField3`	string	No	Updated custom field 3. Max length: 2048. Only accepted if the custom field is enabled in system settings.
`identity.customField4`	string	No	Updated custom field 4. Max length: 2048. Only accepted if the custom field is enabled in system settings.
`identity.customField5`	string	No	Updated custom field 5. Max length: 2048. Only accepted if the custom field is enabled in system settings.
`identity.customField6`	string	No	Updated custom field 6. Max length: 2048. Only accepted if the custom field is enabled in system settings.
`identity.customField7`	string	No	Updated custom field 7. Max length: 2048. Only accepted if the custom field is enabled in system settings.
`identity.customField8`	string	No	Updated custom field 8. Max length: 2048. Only accepted if the custom field is enabled in system settings.
`identity.customField9`	string	No	Updated custom field 9. Max length: 2048. Only accepted if the custom field is enabled in system settings.
`comment`	string	No	Optional comment added to the event.

Sample Request¶

{
  "identityId": "d4a7e2b1-3f5c-4a8d-9e6b-1c2d3e4f5a6b",
  "effectiveDate": "2026-04-01T00:00:00Z",
  "identity": {
    "title": "Vice President, Commercial Lending",
    "department": "Executive Lending",
    "supervisorId": "a8b9c0d1-e2f3-4567-8901-abcdef012345"
  },
  "comment": "Promotion to VP of Commercial Lending"
}

Response Attributes¶

Field	Type	Description
`id`	string (GUID)	Unique identifier of the created personnel event.
`kind`	string	Resource type. Always `Personnel Event`.
`number`	integer	Sequential personnel event number.
`type`	string	Event type. Always `Role Transition` for this endpoint.
`status`	string	Current status.
`reporter`	object	The API token that created the event.
`reporter.id`	string (GUID)	Reporter identity ID.
`reporter.name`	string	Reporter display name.
`assignee`	object	The identity assigned to manage the event. `null` if unassigned.
`assignee.id`	string (GUID)	Assignee identity ID.
`assignee.name`	string	Assignee display name.
`affectedIdentity`	object	The identity transitioning roles. Full identity representation.
`neededOn`	string (ISO 8601)	Effective date.
`neededUntil`	string (ISO 8601)	End date. `null` if no end date was provided.
`completedOn`	string (ISO 8601)	Completion date. `null` when newly created.
`stages`	array[object]	Milestone stages (Approval, Transition).
`activity`	array[object]	Activity log entries.
`comments`	array[object]	Comments on this event.

Sample Response (201)¶

{
  "id": "b8c9d0e1-f2a3-4567-8901-abcdef012345",
  "kind": "Personnel Event",
  "number": 316,
  "type": "Role Transition",
  "status": "Scheduled",
  "reporter": {
    "id": "c4d5e6f7-a8b9-0123-4567-89abcdef0123",
    "name": "API Token - HR Integration"
  },
  "assignee": null,
  "affectedIdentity": {
    "id": "d4a7e2b1-3f5c-4a8d-9e6b-1c2d3e4f5a6b",
    "kind": "Identity",
    "firstName": "Sarah",
    "lastName": "Chen",
    "emailAddress": "schen@firstbankofvalkyrie.com",
    "type": "Employee",
    "title": "Senior Loan Officer",
    "company": "First Bank of Valkyrie",
    "division": "Commercial Lending",
    "department": "Business Loans",
    "office": "Fargo Main",
    "supervisorName": "Martinez, Robert",
    "createdDate": "2023-03-15T14:30:00Z",
    "updatedDate": "2025-11-20T09:15:00Z",
    "firstSeenDate": "2023-03-16T02:00:00Z",
    "inactivatedDate": null,
    "status": "Active"
  },
  "neededOn": "2026-04-01T00:00:00Z",
  "neededUntil": null,
  "completedOn": null,
  "stages": [
    {
      "name": "Approval",
      "status": "Scheduled",
      "startedOn": null,
      "scheduledStart": "2026-03-25T00:00:00Z",
      "completedOn": null,
      "completedBy": null,
      "accessRequests": []
    },
    {
      "name": "Transition",
      "status": "Scheduled",
      "startedOn": null,
      "scheduledStart": "2026-04-01T00:00:00Z",
      "completedOn": null,
      "completedBy": null,
      "accessRequests": []
    }
  ],
  "activity": [
    {
      "createdDate": "2026-03-25T14:00:00Z",
      "author": "API Token - HR Integration",
      "action": "Created",
      "content": "Role Transition event created via API"
    }
  ],
  "comments": [
    {
      "createdDate": "2026-03-25T14:00:00Z",
      "author": "API Token - HR Integration",
      "content": "Promotion to VP of Commercial Lending"
    }
  ]
}

Error Response (400)¶

{
  "error": "validation_error",
  "message": "One or more validation errors occurred",
  "correlationId": "a1b2c3d4e5f6789012345678abcdef01",
  "errors": [
    {
      "field": "identityId",
      "message": "Identity ID is required"
    },
    {
      "field": "effectiveDate",
      "message": "Effective date is required"
    }
  ]
}