Payroll API V1.0 Methods

Below is a list of the currently supported API methods within the Payroll API. The Payroll API will integrate with the BrightPay Cloud application.

Note there is also a swagger interface available that supports testing of Authentication and Integration: https://external.brightpay.com/index.html

Get Current User Summary

Returns limited details of the user that the current access token belongs to. As customers may have more than one account on BrightPay it can be useful to display who is logged in.

get
Authorizations
Responses
200
Success
application/json
get
GET /api/v1/Payroll/GetCurrentUserSummary HTTP/1.1
Host: external.brightpay.com
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

{
  "isSuccess": true,
  "apiErrors": [
    {
      "errorCode": "A code such as USERHASNOACCESSTOEMPLOYER",
      "financialYear": "This represents the financial year that the error occurred in e.g. '24/25' or '25/26' etc",
      "errorId": "83ce3515-f1b2-48f0-95de-6d0d325efc12",
      "errorHint": "The user account you are connecting with does not have access to the Employer."
    }
  ],
  "name": "Jane Doe",
  "emailAddress": "[email protected]"
}

Get Organisations\Employers

Gets the Organisations\Employers that a user has access to.

get
Authorizations
Responses
200
Success
application/json
get
GET /api/v1/Payroll/GetEmployers HTTP/1.1
Host: external.brightpay.com
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

{
  "isSuccess": true,
  "apiErrors": [
    {
      "errorCode": "A code such as USERHASNOACCESSTOEMPLOYER",
      "financialYear": "This represents the financial year that the error occurred in e.g. '24/25' or '25/26' etc",
      "errorId": "83ce3515-f1b2-48f0-95de-6d0d325efc12",
      "errorHint": "The user account you are connecting with does not have access to the Employer."
    }
  ],
  "employers": [
    {
      "organisationId": "a45272c5-14e0-42a3-833d-c30804dec81b",
      "organisationName": "Local Shop Holdings Ltd",
      "employerId": "ad8dbe0e-3023-49a2-9fdc-0703a408c445",
      "employerName": "Your Local Shop",
      "employerNameWithHint": " ‘Your Local Shop, 'Your Local Shop 24/25’ etc",
      "financialYears": [
        "24/25",
        "25/26"
      ]
    }
  ]
}

Get Hourly Rates

Gets the Hourly Rates connected to an Organisations\Employer combination.

get
Authorizations
Query parameters
organisationIdstring · uuidOptional

The OrganisationId of the Organisation

employerIdstring · uuidOptional

The EmployerId of the Employer

Responses
200
Success
application/json
get
GET /api/v1/Payroll/GetEmployerHourlyRates HTTP/1.1
Host: external.brightpay.com
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

{
  "isSuccess": true,
  "apiErrors": [
    {
      "errorCode": "A code such as USERHASNOACCESSTOEMPLOYER",
      "financialYear": "This represents the financial year that the error occurred in e.g. '24/25' or '25/26' etc",
      "errorId": "83ce3515-f1b2-48f0-95de-6d0d325efc12",
      "errorHint": "The user account you are connecting with does not have access to the Employer."
    }
  ],
  "hourlyRates": [
    {
      "rateName": "'Standard rate', 'Saturday Overtime' etc",
      "rateNameWithHint": "'Saturday Overtime', 'Saturday Overtime 24/25’ etc",
      "financialYears": [
        "24/25",
        "25/26"
      ]
    }
  ]
}

Get Employees

Gets the Employees connected to an Organisations\Employer combination.

get
Authorizations
Query parameters
organisationIdstring · uuidOptional

The OrganisationId of the Organisation

employerIdstring · uuidOptional

The EmployerId of the Employer

Responses
200
Success
application/json
get
GET /api/v1/Payroll/GetEmployees HTTP/1.1
Host: external.brightpay.com
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

{
  "isSuccess": true,
  "apiErrors": [
    {
      "errorCode": "A code such as USERHASNOACCESSTOEMPLOYER",
      "financialYear": "This represents the financial year that the error occurred in e.g. '24/25' or '25/26' etc",
      "errorId": "83ce3515-f1b2-48f0-95de-6d0d325efc12",
      "errorHint": "The user account you are connecting with does not have access to the Employer."
    }
  ],
  "employees": [
    {
      "employeeId": "7f6db8ee-0234-4f4d-b9df-755013e7bd52",
      "firstName": "Jane",
      "lastName": "Doe",
      "fullName": "Jane Doe",
      "fullNameWithHint": "‘Jane Doe’, ' Jane Doe 24/25’ etc",
      "worksNumber": "A1232",
      "email": "[email protected]",
      "phoneNo": "07891234567",
      "financialYears": [
        "24/25",
        "25/26"
      ]
    }
  ]
}

Create Employee Hourly Payments

Creates hourly payments on the current open payslip of an Employee.

post
Authorizations
Body

EmployeeHourlyPaymentsRequest contains employee information, validation settings and details of payments.

organisationIdstring · uuidRequired

The Organisation's Id. This field is mandatory

Example: a45272c5-14e0-42a3-833d-c30804dec81b
employerIdstring · uuidRequired

The Employer's Id. This field is mandatory.

Example: ad8dbe0e-3023-49a2-9fdc-0703a408c445
employeeIdstring · uuidRequired

The Employee's Id. This field is mandatory

Example: d41eadf5-ac9b-47bd-8384-e0fd62cfd32d
isRunValidationOnlybooleanRequired

The field IsRunValidationOnly controls if the system should just run validation (if set to true) or validate and load (if set to false). This field is mandatory.

Example: true
isRemoveExistingHourlyPaymentsbooleanRequired

The field IsRemoveExistingHourlyPayments controls if the system should remove existing hourly payments in the current open payslip (if set to true) or add the hourly payments into the current open payslip alongside existing hourly payments (if set to false). This field is mandatory.

Example: true
Responses
200
Success
application/json
post
POST /api/v1/Payroll/CreateEmployeeHourlyPayments HTTP/1.1
Host: external.brightpay.com
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 371

{
  "organisationId": "a45272c5-14e0-42a3-833d-c30804dec81b",
  "employerId": "ad8dbe0e-3023-49a2-9fdc-0703a408c445",
  "employeeId": "d41eadf5-ac9b-47bd-8384-e0fd62cfd32d",
  "isRunValidationOnly": true,
  "isRemoveExistingHourlyPayments": true,
  "hourlyPayments": [
    {
      "rateName": "'Standard rate', 'Saturday overtime' etc ",
      "multiplier": 1,
      "dateOfEntry": "2024-04-13T00:00:00",
      "hoursWorked": 7.5
    }
  ]
}
{
  "isSuccess": true,
  "apiErrors": [
    {
      "errorCode": "A code such as USERHASNOACCESSTOEMPLOYER",
      "financialYear": "This represents the financial year that the error occurred in e.g. '24/25' or '25/26' etc",
      "errorId": "83ce3515-f1b2-48f0-95de-6d0d325efc12",
      "errorHint": "The user account you are connecting with does not have access to the Employer."
    }
  ]
}

PreviousAvailable APIsNextPostman Import

Last updated