API Calls

This section describes the API calls provided by the Sage Business Cloud Payroll API. All API calls require a valid access token.

Response Structure

If an API invocation was successful, the response contains HTTP status 200 OK and a JSON response object:

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

{
    "success": true,
    "state": null,
    "error": null,
    "data": ...
}

If an API call was not successful, the response contains an HTTP status other than 200 OK and a JSON response object with an error description in the errorattribute:

HTTP/1.1 ...
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

{
    "success": false,
    "state": "ERROR",
    "error": { ... },
    "data": null
}

Company List

Sage Business Cloud Payroll supports multiple companies to be managed by one customer. This API call retrieves a list of all companies set up for a given customer:

GET /api/v1/companies HTTP/1.1
Host: lohnabrechnung.sage.com
Accept: application/json
Authorization: ...

The response object (JSON) contains a list of CompanyBase objects in the data field.

Employee List

Employees are a core concept in all products / applications involved here. Therefore, it is likely that employees already exist if a partner wants to integrate with Sage Business Cloud Payroll via the API. The client is expected to handle the mapping of employees, and this api call allows for retrieving a list of employees for a given company as they are stored in Sage Business Cloud Payroll:

GET /api/v1/companies/company_id/employees HTTP/1.1
Host: lohnabrechnung.sage.com
Accept: application/json
Authorization: ...

The parameter company_id in the route must be replaced here by the concrete ID of the company to use. Note that a customer can have more than one company.

The response object (JSON) contains a list of EmployeeBase objects in the data field.

Creating new Employees

To import employees from the client side into an existing company for a customer in Sage Business Cloud Payroll a dedicated API route is provided. This call expects a NewEmployee object as paylode, and Sage Business Cloud Payroll creates a new employee for this company internally. This new employee can then of course be retrieved via the company list API call.

Note that a separate call is required for each employee to create.

POST /api/v1/companies/company_id/employees HTTP/1.1
Host: lohnabrechnung.sage.com
Accept: application/json
Content-Type: application/json
Content-Length: ...
Authorization: ...

The parameter company_id in the route must be replaced here by the concrete ID of the company to use. Note that a customer can have more than one company.

The new employee is assigned the ID specified in the id attribute in the POST data. If this ID is already in use, an error is flagged in the response provided.

Transfer Payroll Data

Input data for the hours worked by the employees of a given company can be transferred into Sage Business Cloud Payroll via this API call:

POST /api/v1/companies/company_id/hourly_compensations HTTP/1.1
Host: lohnabrechnung.sage.com
Accept: application/json
Content-Type: application/json
Content-Length: ...  Authorization: ...

The HTTP request contains a JSON array of HourlyCompensation objects.

The parameter company_id in the route must be replaced here by the concrete ID of the company to use. Note that a customer can have more than one company.

Note that this data can be transferred any number of times during a pay period, but only before the actual pay run is effected. when transferring this data for a given company, any previous data for the current pay period is overwritten.

Sage Business Cloud Payroll validates all data before storing them and does prevent storing erroneous data. In that case, the response sent to the client contains information on the validation issues encountered.

Transfer Extra Payments and Deductions

Similarly, extra payment and deduction information can be transferred for the current pay period via individual FurtherPayment objects as paylod to this API call. The different types are captured in the data type FurtherPaymentType:

POST /api/v1/companies/company_id/further_payments HTTP/1.1
Host: lohnabrechnung.sage.com
Accept: application/json
Content-Type: application/json
Content-Length: ...
Authorization: ...

The parameter company_id in the route must be replaced here by the concrete ID of the company to use. Note that a customer can have more than one company.

Should a pay run be in progress, Sage Business Cloud Payroll will respond with an error message.