MyWorkPal

This document intends to detail how to retrieve and update the main Personal Detail record for a user within "MyWorkPal". It is already assumed the User is known and their MyWorkPal System ID stored/ready to use with all end points.

Pre-requisites:

API Client access

See How to create API Clients to see how to obtain API Client IDs and secrets

Permissions

The API Client requires all the base permissions to read tenants, users, and then permissions for read/write of the main Employee record details. Only tenants that the API client has access to will be returned.

Environment "variables"

Within all examples:

{{url}} would be a full HTTPS URI such as https://webapi.myworkpal.co.uk

{{tenant_id}} is the unique tenant ID for the target user account

{{sub_domain_name}} is the unique tenant subdomain (lowercase text) for the target user account

{{system_id}} the unique SystemID for the target user 

GET    /api/person/tenant/{{sub_domain_name}}/get/{{system_id}}

With the desired User System ID (and subdomain) to hand - the following allows for retrieving, and then adding or update property data against the user account within MyWorkPal. Employee details holds some important values such as NI Number and Start Date. Access is of course needed to the corresponding tenant, as well as user.

Our API implementation allows delivery and then modification to all properties. It is obligatory to start with the GET to ensure all JSON values are present. One may then modify existing, or supply new values, and submit back the original JSON structure to ensure a successful POST via the Set.

Full response structure:

{

    "userAccountId": {{system_id}},

    "tenantName": {{sub_domain_name}},

    "salutationId": null,

    "salutation": null,

    "displayName": null,

    "forenames": "",

    "middlenames": "",

    "surname": "",

    "secondSurname": "",

    "dateOfBirth": null,

    "genderId": null,

    "gender": null,

    "niNumber": "",

    "nationality": "",

    "alternateEmailAddress": "",

    "ccToAlternateEmailAddress": false,

    "preferredName": "",

    "lastUpdated": "2025-08-22T16:17:49.337",

    "dateCreated": "2025-08-22T16:17:49.337",

    "owner": false

}

At present, this is the full scope of the main Personal Detail data. Blue items are for display or related to multiple choice options. Grey items are present but are extended/optional system features and will not be part of the scope of this document at this time. Both Salutation and Gender require provision of a valid value as provided via separate end-points.

List of values that can be added, altered or reset:

"requestDTO" primary properties and objects (Json camelcase)

Extra detail for IDs, at present - MyWorkPal has just implemented Tenant level Gender and Salutation assignment. The list of valid IDs are available from a separate end point. Forename and Surname are key mandatory properties needed for a valid create or update operation.

POST    /api/admin/person/post

With the appropriate Write permission, and a payload of JSON data born from the previously detailed GET, simply POST the data and await a response. If validation is successful and the request can be fulfilled, a simple empty 200 success status is sent back. If the request is invalid, a 400 bad request is returned.

An example for supplying Salutation ("1"), Gender ("1") + FORENAME + SURNAME + DOB ("01/01/197%") for the target user:

{
   "alternateEmailAddress":"",
   "ccToAlternateEmailAddress":false,
   "dateCreated":"2025-08-22T16:17:49.337",
   "dateOfBirth":"1975-01-01T00:00:00",
   "displayName":null,
   "forenames":"FORENAME",
   "gender":null,
   "genderId":1,
   "lastUpdated":"22/08/2025",
   "middlenames":"",
   "nationality":"",
   "niNumber":"",
   "originalDisplayName":" ",
   "owner":false,
   "preferredName":"",
   "salutation":null,
   "salutationId":1,
   "secondSurname":"",
   "surname":"SURNAME",
   "tenantName": {{sub_domain_name}},
   "uniqueNi":true,
   "uniqueNiCheckRequired":false,
   "uniqueNiChecking":false,
   "userAccountId": {{system_id}}
}