This guide discusses the initial set up of an admin account with The People’s Pension within a payroll application. You would take the customer through this set up process when they have payroll set up for a company and they want to use the Payroll Integration API to make contributions to a The People’s Pension admin account when the payroll run is done.

Key concepts

Our Payroll Integration API exposes two main entities to describe an admin account. One is the account itself, and the other is the ‘Worker Group’. You’ll need to decide how these concepts relate to those in your payroll application when you design your integration with our API.

The admin account is the employer’s account within The People’s Pension and is used for day-to-day administration, including submitting employee data and paying money into the scheme. An admin account:

  • Is identified by the admin account number.
  • Can accept contributions on a single payroll frequency.
  • Must receive all contributions in a single request, as described in the Payroll Run guide. In the future we intend to relax this restriction to make the API more flexible.

The simplest set up is where a single payroll is aligned with a single admin account and all employees are potential members of the pension scheme. However, it is possible for a single employer to have multiple payroll runs with different frequencies and separate admin accounts for each. It is also possible for a single payroll to have employees who are members in different pension schemes. You should align your admin account entity with an entity in your application that allows this.

Within an admin account the employer can set up a number of worker groups. A worker group is a group of employees who have the same pension contribution level. We require each employee to belong to a worker group, and expect the worker group to set their employer and employee contribution levels. In your application you should align the admin account’s worker groups with an equivalent entity that applies contribution levels to groups of employees, if one exists.

For employers who use our Simply Comply sign up route we create a single worker group based on the minimum contribution levels under the automatic enrolment legislation. Those who use the Simply Tailor sign up route can create worker groups to suit their requirements as part of that process.

Regardless of the initial sign up route, the employer can subsequently alter and create worker groups as necessary using employer Online Services. You should use the API to retrieve worker group information periodically (at least once per payroll run) and apply any changes to the employees that belong to the worker group.

Exclusions and restrictions

The Payroll Integration API does not yet support all the types of account that B&CE offers, or has offered in the past. Specifically the Payroll Integration API does not currently support:

  • Contractual enrolment accounts, where the employer is contributing to the pension outside of their auto-enrolment duties.
  • Accounts that have Employee Accident Cover and/or Employee Life Cover.
  • The People’s Pension accounts that follow the Construction Industry Joint Council (CIJC) Working Rule Agreement.
  • EasyBuild accounts: these are an older B&CE pension product, separate from The People’s Pension. EasyBuild accounts were closed to contributions on 1 September 2017.
  • Accounts for which your application would need The People’s Pension to perform assessment.

We will review the exclusions as part of our ongoing Payroll Integration API development.

In addition, once an account has received contributions using the Payroll Integration API, subsequent contributions must also be submitted using the API. The customer will need to contact The People’s Pension Support Team if they want to use the employer Online Services file upload process after they have submitted contributions using the Payroll Integration API.

Before you start

There are a few prerequisites before your application can be set up to integrate with an admin account:

  • The customer must have registered with employer Online Services and have their login details. They will need these to authorise your application to use the API on their behalf, as explained in the Authentication guide
  • The admin account should already have been created using employer Online Services, as the Payroll Integration API does not support creating new accounts.
  • The customer will need to know the admin account number.
  • The customer must either be the account owner, or have been given access to the account by the account owner.
  • The customer must authorise your application to use the Payroll Integration API on their behalf.

To make the customer’s experience as seamless as possible, we suggest that you include a link to a web page that we provide giving a brief explanation of how to create a new admin account and where to find the account id once the account has been created. Our suggested text is included below.

It’s possible that the payroll has already been linked with an admin account so that your application can generate files for the customer to upload through employer Online Services. In this case all the prerequisites will have been established, and your application will already have the admin account number configured: Switching to use the Payroll Integration API should not require any further information.

The customer must authorise your application to use the Payroll Integration API on their behalf, if they haven’t done so already. Bear in mind that this authorisation extends to all the admin accounts that the customer can access: if your application already has an access token for the customer then that can be used to set up additional admin accounts.

Suggested steps

If the payroll account has already been linked with an admin account for manual file upload through employer Online Services, then your application will already have the admin account number you’ll need to use with the Payroll Integration API.

Otherwise you should ask the user to provide the admin account number that they want to use with this payroll. In the near future we will provide an API that returns a list of the admin account numbers and account names that the user has access to, so they can select one from a list. This will also indicate which accounts can be used with the Payroll Integration API, as there are currently some account types that are excluded. In the meantime you should prompt the user to enter the admin account number by hand.

At this point in your user interface you should also include some explanatory text with a link to a page on our web site where the customer will find more information about how to set up an account for use with the API. Our suggested text is:

There we will provide information about setting up an admin account, how to find the admin account number, and what kinds of admin account can be used with the Payroll Integration API.

Once your application has the admin account number it can get the account information. For example:

GET /api/v2/accounts/855969 HTTP/1.1
Authorization: Bearer SlAV32hkKG

(Substituting a valid admin account number and access token.)

In response you get a document like this:

HTTP/1.1 200 OK
Content-Type: application/vnd.api+json

  "data": {
    "type": "account",
    "id": "855969",
    "attributes": {
      "accountName": "Franecki Group Weekly",
      "prpFrequency": "Weekly",
      "payrollFrequency": "Weekly",
      "nextPayReferencePeriod": {
        "start": "2017-07-08",
        "end": "2017-07-14"
      "companyName": "Franecki Group",
      "stagingDate": "2014-04-01",
      "taxBasis": "Net",
      "workerGroups": [
          "id": "S",
          "description": "Staff",
          "effective": {
            "start": "2014-04-01"
          "earningsBasis": "Qualifying Earnings",
          "employeeContributionAmount": 0,
          "employeeContributionPercent": 1.5,
          "employerContributionAmount": 0,
          "employerContributionPercent": 1.5
          "id": "D",
          "description": "Directors",
          "effective": {
            "start": "2014-04-01"
          "earningsBasis": "Fixed Amount",
          "employeeContributionAmount": 1000,
          "employeeContributionPercent": 0,
          "employerContributionAmount": 1000,
          "employerContributionPercent": 0
  "links": {
    "self": "",
    "opt-outs": ""

A detailed description of the response document can be found in the API reference.

Your application should use the data returned to set up the pension contributions from the payroll run. Where appropriate you should confirm that the information we hold for the admin account matches what your application holds for the payroll. Pay particular attention to the fields that describe the pay reference period frequency and the dates of the next pay reference period that we expect: we require each set of contributions to match our expected next pay reference period.

The response also includes a collection of links to other resources related to the current one: for example, the ‘opt-outs’ link gives the URL for the account opt-outs operation for the account. You should use these links in preference to building URLs manually based on those given in the API reference as it allows us the flexibility to change the location of resources without you needing to update your software.

The account information can change over time, so you should retrieve it prior to each payroll run and make sure any changes are acted on. This is part of the Payroll Run.