Create Onboard¶

Endpoint: POST /api/personnel-events/onboard

Description: Creates a new onboarding personnel event with identity metadata for the person being onboarded.

Request Body¶

Field	Type	Required	Description
`identity`	object	Yes	Identity metadata for the person being onboarded.
`identity.firstName`	string	Yes	First name. Max length: 256.
`identity.lastName`	string	Yes	Last name. Max length: 256.
`identity.email`	string	No	Email address. Max length: 256.
`identity.supervisorId`	string (GUID)	No	Supervisor identity ID. Must reference an existing identity.
`identity.company`	string	No	Company name. Max length: 256.
`identity.division`	string	No	Division name. Max length: 256.
`identity.department`	string	No	Department name. Max length: 128.
`identity.office`	string	No	Office location. Max length: 256.
`identity.title`	string	No	Job title. Max length: 256.
`identity.identityType`	string	No	Identity type. Max length: 50. Valid values: `Employee`, `ServiceAccount`, `Vendor`, `Shared`, `Mailbox`, `Client`, `Temporary`, `Administrator`, `Auditor`, `Unknown`. Default: `Employee`.
`identity.customField1`	string	No	Custom field 1. Max length: 2048. Only accepted if the custom field is enabled in system settings.
`identity.customField2`	string	No	Custom field 2. Max length: 2048. Only accepted if the custom field is enabled in system settings.
`identity.customField3`	string	No	Custom field 3. Max length: 2048. Only accepted if the custom field is enabled in system settings.
`identity.customField4`	string	No	Custom field 4. Max length: 2048. Only accepted if the custom field is enabled in system settings.
`identity.customField5`	string	No	Custom field 5. Max length: 2048. Only accepted if the custom field is enabled in system settings.
`identity.customField6`	string	No	Custom field 6. Max length: 2048. Only accepted if the custom field is enabled in system settings.
`identity.customField7`	string	No	Custom field 7. Max length: 2048. Only accepted if the custom field is enabled in system settings.
`identity.customField8`	string	No	Custom field 8. Max length: 2048. Only accepted if the custom field is enabled in system settings.
`identity.customField9`	string	No	Custom field 9. Max length: 2048. Only accepted if the custom field is enabled in system settings.
`effectiveDate`	string (ISO 8601)	Yes	The date the onboarding takes effect. Must be today or later.
`comment`	string	No	Optional comment added to the event.

Sample Request¶

{
  "identity": {
    "firstName": "Sarah",
    "lastName": "Chen",
    "email": "schen@firstbankofvalkyrie.com",
    "supervisorId": "f7a8b9c0-d1e2-3456-7890-abcdef012345",
    "company": "First Bank of Valkyrie",
    "division": "Commercial Lending",
    "department": "Business Loans",
    "office": "Fargo Main",
    "title": "Senior Loan Officer",
    "identityType": "Employee"
  },
  "effectiveDate": "2026-04-01T00:00:00Z",
  "comment": "New hire starting in 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 `Onboard` 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 created for the onboarded person. Full identity representation.
`neededOn`	string (ISO 8601)	Effective date.
`neededUntil`	string (ISO 8601)	End date. `null` for onboarding events.
`completedOn`	string (ISO 8601)	Completion date. `null` when newly created.
`stages`	array[object]	Milestone stages (Approval, Provision, Verification).
`activity`	array[object]	Activity log entries.
`comments`	array[object]	Comments on this event.

Sample Response (201)¶

{
  "id": "e5f6a7b8-c9d0-1234-5678-9abcdef01234",
  "kind": "Personnel Event",
  "number": 313,
  "type": "Onboard",
  "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": "2026-03-25T14:00:00Z",
    "updatedDate": "2026-03-25T14:00:00Z",
    "firstSeenDate": "2026-03-25T14: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": "Provision",
      "status": "Scheduled",
      "startedOn": null,
      "scheduledStart": "2026-04-01T00:00:00Z",
      "completedOn": null,
      "completedBy": null,
      "accessRequests": []
    },
    {
      "name": "Verification",
      "status": "Scheduled",
      "startedOn": null,
      "scheduledStart": null,
      "completedOn": null,
      "completedBy": null,
      "accessRequests": []
    }
  ],
  "activity": [
    {
      "createdDate": "2026-03-25T14:00:00Z",
      "author": "API Token - HR Integration",
      "action": "Created",
      "content": "Onboard event created via API"
    }
  ],
  "comments": [
    {
      "createdDate": "2026-03-25T14:00:00Z",
      "author": "API Token - HR Integration",
      "content": "New hire starting in Commercial Lending"
    }
  ]
}

Error Response (400)¶

{
  "error": "validation_error",
  "message": "One or more validation errors occurred",
  "correlationId": "a1b2c3d4e5f6789012345678abcdef01",
  "errors": [
    {
      "field": "identity.firstName",
      "message": "First name is required"
    },
    {
      "field": "effectiveDate",
      "message": "Effective date must be today or later"
    }
  ]
}