Overview

Secondary Pensions data can be submitted to the States of Guernsey by sending files which conform to a JSON standard format using standard HTTP POST requests. Each file will contain the payroll data for an employer covering one or more pay periods.

There are two API endpoints for submitting this data:

https://spcm.gov.gg/api/v1/revenue/employer-returns

This is the live endpoint. Data submitted to this endpoint is received and processed by the States of Guernsey.
https://spcm.gov.gg/api/v1/test/revenue/employer-returns

This is the test endpoint, which can be used for safely testing your software implementation. The test endpoint gives the same responses as the live endpoint, but the data submitted here is not processed by the States of Guernsey. Instead the data can be viewed via the Message Portal in order to help you understand how it has been interpreted.

You should only submit example data to the test endpoint, and not data about real people.

The JSON schema

The JSON body of the request must conform to the SPCM JSON message schema. This section gives a very quick impression of what a Secondary Pensions return looks like; the full details of the schema are covered in later sections.

Minimal test message

A minimal test message contains information about the source of the message and its intended purpose.:


            {
    "$schema": "https://spcm.gov.gg/schemas/0.3/message.schema.json",
    "effective": "2022-03-16T13:03:01Z",
    "spcmMessageVersion": "0.3",
    "senderEmail": "joe.bloggs@gov.gg",
    "senderName": "Joseph Bloggs",
    "softwareAgent": "Acme Payroll v1.44",
    "type": "Revenue_EmployerReturn",
    "test": true,
    "coverage": [],
    "purposes": [ "SecondaryPensions" ],
    "pensionSchemes": [ … ],
    "employers": [ … ]
}

"type": "Revenue_EmployerReturn" and "purposes": [ "SecondaryPensions" ]: These properties indicate that the message contains Secondary Pensions data using the Employer Return message format defined by the Revenue Service.
"test": This must be set to true if the message contains test data, otherwise it must be specified as false. This provides an additional check that the data has been sent to the correct (test or live) endpoint.
"coverage": Lists the pay periods (weeks and/or months) which are covered by this return
"pensionSchemes": This section will contain basic information about any pension schemes into which contributions are being paid.
"employers": The array is where you can list employers which are included in this return. In the above example the array is empty, which means the return does not report anything. However, most returns will contain one employer:

Employer data

The "employers" array can be populated as follows:


            …
"employers": [{
    "id": "123",
    "name": "Acme Services Ltd",
    "employees": [ … ]
}]
…

"id": This is an identifier for the employer which is generated by the sender - see below for more information.

Employee data

The other required array is the "employees" array, which lists all the employees of this employer who are reportable for Secondary Pensions purposes during the pay periods covered by this return, along with the details of their pay and pension contributions (if any) for those periods:


            …
        "employees": [{
         "id": "12345",
         "dateOfBirth": "1980-01-01",
         "socialSecurityNo": "GY123456",
         "title": "Mr",
         "firstName": "Fred",
         "lastName": "Bloggs",
         …
         "pay": [ … ]
        }]
        …

Many fields have been omitted here (including the "pay" records themselves). Detailed examples can be found in the example files.

Authentication

There is no pre-registration required to submit returns to the API. However, you must include an API key with each submission in an HTTP header called X-API-Key. The API key can be generated by your software. For more information about API keys, including the approach which must be followed when generating them, please refer to the documentation for authentication.

Sender Ids

Employers, employees and pension schemes are identified in returns by an "id" property. This is a string of up to 200 characters and is generated by the sender. It does not matter what identifier you use, but you should use the same Id when referring to the same record in subsequent messages, so it should be immutable.

For employers and pension schemes, the scope of an Id is the API key. This means two messages received by SPCM will only be treated as referring to the same employer or pension scheme if both were sent with the same API key, as well as having the same Id.

For employees, the scope is the employer. This means that, if you are reporting for two or more employers using the same API key, then it is acceptable to have the same Id for two different people where they are employed by different employers.

Within their scope, Ids must be unique. This means the employer Ids within a return must all be different, and the Ids of the employees appearing under each employer in a return must be different.

Ids are compared using a case insensitive comparison, so Ids which differ only in letter case are considered to be the same.

Migrating API keys

Because of the above rules relating the API keys and Ids, you should take care if re-using an API key when migrating from one payroll system to another. It will be necessary in this case to ensure that Ids are migrated as well. If Ids cannot be migrated, it would be better to create a new API key for the new system in order to prevent accidentally reusing an Id from the old system which in fact represents an unrelated entity in the new one.