Employee Onboarding¶

The Employee Onboarding API endpoint allows employers to seamlessly enrol employees into the YIP scheme. This process ensures that all eligible employees are correctly registered with the pension scheme.

(Please see Sovereign OpenAPI documentation for detailed schema)

Request onboarding two employees¶

To onboard multiple employees, utilise the POST request with the following URL:

POST Request URL

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

And provide the necessary JSON payload as follows:

application/json

{
  "employees": [
    {
      "socialSecurityNo": "GY502564",
      "dateOfBirth": "1978-08-31",
      "firstName": "Gerald",
      "lastName": "Palmer",
      "title": "Mr",
      "gender": "Male",
      "schemeRegistrationDate": "2018-11-13",
      "companyJoinedDate": "2018-11-13",
      "emailAddress": "gerald@contoso.com",
      "passportNumber": "Y82220084",
      "nationality": "United Kingdom",
      "countryOfBirth": "United Kingdom",
      "addressDetails": {
        "addressLine1": "93 Wartnaby Road",
        "city": "Acton",
        "postcode": "CW5 3NB",
        "country": "United Kingdom"
      }
    },
    {
      "socialSecurityNo": "GY338669",
      "dateOfBirth": "1964-06-29",
      "firstName": "Judy",
      "lastName": "Haley",
      "title": "Ms",
      "gender": "Female",
      "schemeRegistrationDate": "2020-01-22",
      "companyJoinedDate": "2020-01-22",
      "emailAddress": "jhaley@contoso.com",
      "passportNumber": "Y2662435",
      "nationality": "GB",
      "countryOfBirth": "United Kingdom",
      "addressDetails": {
        "addressLine1": "84 Gloucester Road",
        "city": "Cilgwyn",
        "postcode": "SA20 6BU",
        "country": "United Kingdom"
      }
    }
  ]
}

The nationality, countryOfBirth and country values must be recognised country names or ISO 3166-1 alpha-2 codes. The full list of accepted values is available from the Reference Data endpoints.

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

application/json

{
  "success": true,
  "numEnroled": 2,
  "membersEnroled": [
    "GY502564",
    "GY338669"
  ]
}

Validate before committing

Append ?validate=true to the request URL to check your payload without enrolling anyone. 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