Employee Alterations

The Employee Alterations API endpoint allows employers to modify employees details, such as changes of address and other relevant information.

(Please see Sovereign OpenAPI documentation for detailed schema)

Changing employee details

To modify details for employees, utilise the PATCH request with the following URL:

PATCH Request URL

https://api.yip.services/v1.0/employees

Each employee is matched on their socialSecurityNo and dateOfBirth, and only the fields you include under update are changed. Provide the necessary JSON payload as follows:

application/json

{
  "employees": [
    {
      "socialSecurityNo": "GY333369",
      "dateOfBirth": "1978-08-31",
      "update": {
        "addressLine1": "93 Wartnaby Road",
        "city": "Acton",
        "postcode": "CW5 3NB",
        "country": "United Kingdom"
      }
    },
    {
      "socialSecurityNo": "GY338673",
      "dateOfBirth": "1968-08-31",
      "update": {
        "title": "Mr",
        "firstName": "Bob"
      }
    }
  ]
}

A successful request returns the number of employees updated and their social security numbers:

application/json

{
  "success": true,
  "numAltered": 2,
  "membersAltered": [
    "GY333369",
    "GY338673"
  ]
}

Validate before committing

Append ?validate=true to the request URL to check your payload without changing any records. The response is the same as a live request but includes "isValidate": true, and nothing is saved.

---

Last update: July 30, 2026
Created: February 11, 2025