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

OAuth2authorizationCodeRequired

Authorization URL: Token URL:

Responses

200

Success

application/json

The UserSummaryResponse contains basic user details.

isSuccessbooleanOptional

The IsSuccess field indicates if the request was successful or not. This field will always be populated.

namestring · nullableOptional

The user's name. This field will always be populated.

Example: Jane Doe

emailAddressstring · nullableOptional

The user's email address. This field will always be populated.

Example: [email protected]

400

Bad Request

application/json

409

Conflict

application/json

get

/api/v1/Payroll/GetCurrentUserSummary

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

OAuth2authorizationCodeRequired

Authorization URL: Token URL:

Responses

200

Success

application/json

EmployersResponse contains a list of Employers.

isSuccessbooleanOptional

The IsSuccess field indicates if the request was successful or not. This field will always be populated.

400

Bad Request

application/json

409

Conflict

application/json

get

/api/v1/Payroll/GetEmployers

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

OAuth2authorizationCodeRequired

Authorization URL: Token URL:

Query parameters

organisationIdstring · uuidOptional

The OrganisationId of the Organisation

employerIdstring · uuidOptional

The EmployerId of the Employer

Responses

200

Success

application/json

HourlyRatesResponse contains a list of Hourly Payment Rates.

isSuccessbooleanOptional

The IsSuccess field indicates if the request was successful or not. This field will always be populated.

400

Bad Request

application/json

409

Conflict

application/json

get

/api/v1/Payroll/GetEmployerHourlyRates

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

OAuth2authorizationCodeRequired

Authorization URL: Token URL:

Query parameters

organisationIdstring · uuidOptional

The OrganisationId of the Organisation

employerIdstring · uuidOptional

The EmployerId of the Employer

Responses

200

Success

application/json

EmployeesResponse contains a list of Employees.

isSuccessbooleanOptional

The IsSuccess field indicates if the request was successful or not. This field will always be populated.

400

Bad Request

application/json

409

Conflict

application/json

get

/api/v1/Payroll/GetEmployees

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

OAuth2authorizationCodeRequired

Authorization URL: Token URL:

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

EmployeeHourlyPaymentsResponse is a basic success/failure response.

isSuccessbooleanOptional

The IsSuccess field indicates if the request was successful or not. This field will always be populated.

400

Bad Request

application/json

409

Conflict

application/json

post

/api/v1/Payroll/CreateEmployeeHourlyPayments

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 APIs NextPostman Import

Last updated 1 year ago

hashtagGet Current User Summary

hashtagReturns 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.

hashtagGet Organisations\Employers

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

hashtagGet Hourly Rates

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

hashtagGet Employees

hashtagGets the Employees connected to an Organisations\Employer combination.

hashtagCreate Employee Hourly Payments

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

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 Organisations\Employers

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

Get Hourly Rates

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

Get Employees

Gets the Employees connected to an Organisations\Employer combination.

Create Employee Hourly Payments

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