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

oauth2

OAuth2authorizationCodeRequired

Authorization URL: Token URL:

Available scopes:

• : BrightPay API Access

Responses

200

Success

application/json

400

Bad Request

application/json

409

Conflict

application/json

get

/api/v1/Payroll/GetCurrentUserSummary

HTTPcURLJavaScriptPython

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

oauth2

OAuth2authorizationCodeRequired

Authorization URL: Token URL:

Available scopes:

• : BrightPay API Access

Responses

200

Success

application/json

400

Bad Request

application/json

409

Conflict

application/json

get

/api/v1/Payroll/GetEmployers

HTTPcURLJavaScriptPython

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

oauth2

OAuth2authorizationCodeRequired

Authorization URL: Token URL:

Available scopes:

• : BrightPay API Access

Query parameters

organisationIdstring · uuidOptional

The OrganisationId of the Organisation

employerIdstring · uuidOptional

The EmployerId of the Employer

Responses

200

Success

application/json

400

Bad Request

application/json

409

Conflict

application/json

get

/api/v1/Payroll/GetEmployerHourlyRates

HTTPcURLJavaScriptPython

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

oauth2

OAuth2authorizationCodeRequired

Authorization URL: Token URL:

Available scopes:

• : BrightPay API Access

Query parameters

organisationIdstring · uuidOptional

The OrganisationId of the Organisation

employerIdstring · uuidOptional

The EmployerId of the Employer

Responses

200

Success

application/json

400

Bad Request

application/json

409

Conflict

application/json

get

/api/v1/Payroll/GetEmployees

HTTPcURLJavaScriptPython

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

oauth2

OAuth2authorizationCodeRequired

Authorization URL: Token URL:

Available scopes:

• : BrightPay API Access

Body

application/jsontext/jsonapplication/*+json

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

400

Bad Request

application/json

409

Conflict

application/json

post

/api/v1/Payroll/CreateEmployeeHourlyPayments

HTTPcURLJavaScriptPython

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
    }
  ]
}

application/jsontext/jsonapplication/*+json

{
  "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."
    }
  ]
}