Skip to content

Contributions Upload

The Contributions Upload API endpoint enables employers to submit the necessary contribution details for employees enroled in the YIP scheme. This API follows a format similar to that of the States of Guernsey's requirements.

(Please see Sovereign OpenAPI documentation for detailed schema)

Example Requests

Visit spcm.gov.gg for additional information about the States of Guernsey contributions upload specification.

Monthly Contributions

In matching our contributions schema with the States of Guernsey's requirements, we have optimized the process by eliminating unnecessary fields. While these fields can still be included in submissions, they are disregarded. Key distinctions include:

  1. Employer ID: Our system does not require an explicit ID for the employer since it is automatically obtained from the API key generated during the upload portal registration process.

  2. Employee ID: Similarly, we don't need an additional ID for the employee, as the socialSecurityNo serves as the unique identifier for each individual.

  3. Unused Fields: The following are some of fields not required by our system: spcmMessageVersion, senderEmail, senderName, softwareAgent, type, test. (The sender information is obtained automatically from the uniquely generated API key linked to your account)

By eliminating these redundant fields, we aim to simplify contribution processes and enhance data management efficiency. Feel free to include these fields in the submissions if you prefer, but rest assured they will not impact the processing of your contributions.

To submit payroll contributions, utilise the POST request with the following URL:

POST Request URL
https://api.yip.services/v1.0/payroll
And provide the necessary JSON payload as follows:

application/json
{
  "effective": "2022-03-22T15:19:02Z",
  "purposes": [
    "PensionProvider"
  ],
  "coverage": [
    {
      "year": 2022,
      "frequency": "Monthly",
      "period": 2
    }
  ],
  "employers": [
    {
      "employees": [
        {
          "dateOfBirth": "1980-01-01",
          "socialSecurityNo": "GY123456",
          "lastName": "Bob",
          "purposes": [
            "PensionProvider"
          ],
          "pay": [
            {
              "year": 2022,
              "frequency": "Monthly",
              "period": 2,
              "pensionEmployerAmount": 123.45,
              "pensionEmployeeRegularAmount": 23.00,
              "pensionEmployeeAdditionalAmount": 0.00
            }
          ]
        }
      ]
    }
  ]
}

A successful request returns the number of employees the contributions were applied to and their social security numbers:

application/json
{
  "success": true,
  "numAffected": 1,
  "membersAffected": [
    "GY123456"
  ]
}

Validate before committing

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