Introduction

The Payroll Integration API lets your payroll application manage linked accounts with The People’s Pension on behalf of your customers.

Using the API, your application will be able to:

  • Retrieve the account information that we hold for use in your application.
  • Submit employee details and their contribution amounts at the end of each payroll run.
  • Retrieve information about employees who have opted out of the pension scheme, automating this part of the payroll management.

If you are a developer planning on working with our API, you should read these getting started pages to familiarise yourself with the basics. For further help, use the API reference and Using the API sections of the Developer Hub. If you have any questions, you can contact us.

We continually review and improve our products and services to meet regulatory, market and technical needs. As a result we’ll issue timely API updates and these may have mandatory, time-bound elements in regards to implementing the changes.

Our developer services

This Developer Hub is our primary resource for developers using our Payroll Integration API. You will find detailed documentation explaining what you need to know to integrate with our pension products through the API.

Once you’ve registered for a developer account, you’ll be able to access your developer dashboard to manage the authentication credentials you’ll need to develop and test your application and its use of our API.

Our Payroll Integration API is provided in two completely separate environments: live and sandbox. The live environment is the one that our customers use every day to manage their pension schemes. The sandbox provides a copy of the same API, and it’s this environment that you’ll work with initially.

The sandbox environment has been set up so that some of the read-only API operations can be accessed without needing to go through an authentication process. This means you can get a taste of what the API can offer to you very quickly – we’ll come to that shortly.

The sandbox has also been set up with some sample admin accounts so you can get started quickly. When you access the API without authentication you can use the account numbers in the test data guide. Once you’ve registered for a developer account and you’re accessing the API with authentication, you’ll have your own set of account numbers that are private to you and can be used to test operations that send data to us for processing. We’ll let you know what these account numbers are during the registration process.

Please remember: Any data uploaded to the B&CE sandbox testing environment must not be traceable to any living individual.

When the time comes to deploy your application and its integration with our API, you’ll need to get new authentication credentials for the live environment. You’ll manage these through the Dashboard, just like the sandbox credentials. Our payroll relationship management team will be on hand to help you through this process.

Quick start for experienced developers

If you’re already familiar with developing API applications, you can be up-and-running with the following simple steps:

First requests

Our API is a RESTful API built using the same technology that makes the world-wide web (and the web browser you are currently using) work: the Hypertext Transfer Protocol (HTTP). It also means that beginning to use our API can be as simple as clicking a link: https://api-sandbox.bandce.co.uk/api/v2/accounts/855969

Try that out now: click the link above and your browser should either display or download a plain text document containing information about one of the sample accounts we have in the sandbox environment. Open that file in a text editor and you should see something like this:

{
  "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": "https://api-sandbox.bandce.co.uk/api/v2/accounts/855969",
    "opt-outs": "https://api-sandbox.bandce.co.uk/api/v2/accounts/855969/opt-outs"
  }
}

The text in this file is formatted using JSON, which makes it easy for software to extract information from it. We also use a set of conventions called JSON API to guide how we structure our JSON documents. But within all that structure you should be able to recognise the following information about this pension admin account:

  • the name of the account, and the name of the company that it belongs to
  • the dates of the next pay reference period, which is the period of time over which pension contributions are earned
  • worker groups that show how different groups of employees receive different levels of pension contribution
  • some links to other API operations that are related to this one. In this case there’s a link to an operation from which you can retrieve a list of the employees who have opted-out of the pension scheme.

The links are an important part of what makes our API “RESTful”: your application should be able to navigate the Payroll Integration API by following these links in a similar way to you following links in a web browser. You can try that out too: copy the URL after "opt-outs" in the JSON document you downloaded earlier on (or from the formatted example above, if that’s easier). Paste it into your browser’s URL bar and press enter, and you should receive a second JSON document. This time it will contain a list of opted-out employees, information your application could use to change the status of the employees in the payroll.

Integrating with your application

The previous section showed how you can use the Payroll Integration API to retrieve information about an account, but to keep things simple we skipped over some essential points.

 

Authentication and authorisation

To access real customer’s accounts, your application will need to be authorised to use the API on behalf of the customer. We use an implementation of the OAuth 2.0 specification to manage this authorisation process, and you’ll find much more detail about how it works in our authentication guide. You’ll need to decide what the best way is of integrating the OAuth authorisation flow into your application, but there are numerous client libraries and example projects available to show how this can be done on different technology platforms.

You might also find a tool like Postman useful while doing your development work. It will perform the OAuth authorisation flow for you and then let you make requests to the Payroll Integration API with the correct Authorization header.

 

HTTP status codes

When you access our API your software will need to take different actions based on the HTTP status code that our API returns. We document some of the expected status codes in the API reference, but the status codes we list are not intended to be exhaustive: network infrastructure between your application and our API might introduce additional failure conditions, for example. How to Think About HTTP Status Codes by Mark Nottingham gives some good advice here.

While there may be specific actions that your application will need to take based on recognising a specific status code, your application should also have some fall-back behaviour that handles the broad kinds of HTTP response. In particular:

  • A 4xx (Client error) response indicates that something was wrong with the request that your application generated. This covers things like authorisation failures (401 status code). In this case your application should not submit the same request again without correction, as it will fail every time.
  • A 5xx (Server error) response indicates that something went wrong while processing the request. This covers problems that happen on our end, within the API. We try to minimise these, but if you do receive a 5xx response you should retry the request at a later time.

 

The requests and responses in our API use the JSON format and a set of structural conventions called JSON API. Our main reason for using JSON API is that it gives a tidy way of including links to other operations in our API responses, and this in turn helps to minimise dependencies between your application and our API.

It’s common when writing a client for a RESTful API to look at the API reference and write code to generate URLs that match the patterns documented in the API. This approach is simple, but each URL that you build in your client application is encoding fixed information about the API. It limits our ability to evolve the API in the future, as client software depends on the URL patterns that existed at the time when the software was written. This is a particular concern with packaged software that may be shipped to customers with no upgrade process available.

We have designed our API using JSON API to reduce the number of link URLs that you need to generate. Instead, our API responses include a links object that contain the named URLs of API operations related to the current resource. You can make your application adapt automatically to changes in our API by using these included links in preference to generating them yourself. We hope that this should also reduce your maintenance effort as well.

 

API evolution

Using links from the API responses is one way to help your application cope with changes to the API over time. Another is not being overly strict in validating the responses that you receive, and specifically not rejecting documents with additional fields you don’t understand.

As we expand the capabilities of our API we may add new fields to the requests and responses. Any new fields added to existing requests will be optional, and any new fields added to existing responses will not require processing by clients that pre-date their addition. If we have to make an addition or change that doesn’t meet these criteria we’ll do so by adding a new API operation for the updated request or response.

Next steps

At the moment our Payroll Integration API supports two key business processes between payroll and The People’s Pension:

  • The initial set up of an admin account within your payroll application, which involves comparing our account information with the set up of the payroll within your application. Read more about this in the Account set up guide.
  • The payroll run itself, including how to find out which employees have opted-out of pension scheme contributions since the last payroll run. Read more about this in the Payroll run guide.

We also have extensive documentation on the whole API. This is split across three main areas:

  • The API reference, which lists all the operations that our Payroll Integration API supports along with the request and response formats with examples.
  • Descriptions of all the individual fields used within the JSON documents. Often the same field of information is used in multiple requests and responses so we’ve extracted this detailed documentation into their own pages. The API reference links through to these pages, or you can use the index of all the fields.
  • Descriptions of the errors that can be returned by the Payroll Integration API. These are linked to by the field description that the error relates to, and there’s also an index of all the errors.