This document intends to detail how to retrieve and update the Address record details 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
With the desired User System ID (and subdomain) to hand - the following allows for retrieving, and then adding or updating property data against the user account within MyWorkPal. Address details are multiple records delivered and sent as an array. A newly created user will have a default empty record, and the GET end point will send down this as a 1 item array with empty values. The internal ID for the address detail record is seen, which needs to remain to ensure update operation.
Critically, the natural response only contains the array of address data and no direct user identifiers, please see the details about how the request to POST and update is built - creating a wrapper with the reference to the User + Tenant.
Full response structure, for a brand new user with zero address:
[
{
"userAccountId":0,
"id":1234,
"name":null,
"line1":null,
"line2":null,
"line3":null,
"town":null,
"county":null,
"postcode":null,
"country":"GB",
"lastUpdated":"2025-08-22T16:17:49.357",
"dateCreated":"0001-01-01T00:00:00",
"deleteMark":false,
"isPrimary":true,
"saved":true
}
]
Should the user have previous record, or records, then the array will contain the other instances. Maximum address count is controlled by the tenant configuration. To denote which Address is seen as primary, the IsPrimary flag exists. This needs supplying as true to ensure the desired record is hooked when an Export of the users (1 row per user) is used or inbuilt MWP expressions for showing Address detail.
Short list of values that can be added, altered or given:
"requestDTO" primary properties and objects (Json camelcase)
| Name | string | Non mandatory |
Line1 | string | Non mandatory |
Line2 | boolstring | Non mandatory |
Line3 | string | Non mandatory |
| Town | string | Non mandatory |
| County | string | Non mandatory |
| Postcode | string | Mandatory |
| Country | string | Mandatory, ISO country code value |
| IsPrimary | bool | Mandatory |
Extra detail for collections:
Country will be a defined choice from standard ISO identifiers for known countries, the full list is available from a separate end point. A value of "GB" is expected in most cases.
POST
With the appropriate Write permission, and a payload of JSON data born from the previously detailed GET, the following request object structure needs to be created for successful operation.
{
"userAccountId": {{system_id}},
"tenantId": {{tenant_id}},
"addresses": [
{
"userAccountId": 0,
"id": 1234,
"name": "ADDNAME",
"line1": "ADDLINE1",
"line2": null,
"line3": null,
"town": "ADDTOWN",
"county": null,
"postcode": "A11AA",
"country": "GB",
"lastUpdated": "2025-08-22T16:17:49.357",
"dateCreated": "0001-01-01T00:00:00",
"deleteMark": false,
"isPrimary": true,
"saved": true
}
]
}Essentially, a fresh object is created which provides "UserAccountId" as the SystemID for the user, along with the TenantId. One then needs to provide an "Addresses" array, and populate it with a representation of the original array as returned from the GET
Note in this example, the original record ID 1234 is kept - ensuring an update operation of this existing default record. In this worked example case, it was supplied empty, and has gained NAME, LINE1, TOWN, POSTCODE. IsPrimary remains true as the sole data item.
If one wishes to explore multiple record management, the API supports this via the following rules:
If each Address has a defined ID - this is expected to be existing data and will be an update operation when found (and validated as belonging to the user)
If an Address array item is supplied with ID = 0, this is instruction to attempt a fresh add of the data as new address. Ensure the IsPrimary flag = true exists once within the request.
If an Address is sent down within a GET that is then removed/erased from a subsequent SET post, this is taken as instruction for deletion. Ensure if modification to a record is not needed, then it is not lost between retrieval and submission.