API reference for Sage Business Cloud Payroll
Data Types
When communicating with the Sage Business Cloud Payroll API, data is transferred in JSON format. Below you can find the types which are being used in the JSON data packages which are exchanged:
Address
Addresses are represented via the type Address
:
class Address {
string street_address, // Street and number
string postal_code, // Area code
string location // City
}
Example:
{
"street_address": "Karl-Heine-Straße 109-111",
"postal_code": "04229",
"location": "Leipzig"
}
Month
The type Month
is used for example to represent payroll calculation periods. The format is a string with the pattern YYYY-MM
for year
in 4 digits) and month (2 digits).
Example: 2018-10
CompanyBase
Basic information for companies is represented using the type CompanyBase
:
class CompanyBase {
int id, // Client ID
string name1, // Company name (row 1)
string name2, // Company name (row 1)
Address address // Company address
}
Example:
{
"id": 196753,
"name1": "Sage HR Solutions AG",
"name2": "",
"address": {
"street_address": "Karl-Heine-Straße 109-111",
"postal_code": "04229",
"location": "Leipzig"
}
}
Company
Companies are represented by the type Company
which extends the type CompanyBase
:
class Company : CompanyBase {
Month current_month // Current payroll calculation month
}
Example:
{
"id": 196753,
"name1": "Sage HR Solutions AG",
"name2": "",
"address": {
"street_address": "Karl-Heine-Straße 109-111",
"postal_code": "04229",
"location": "Leipzig"
},
"current_month": "2015-05"
}
Date
The type Date
is used to represent calendar dates. The format is a string with the pattern YYYY-MM-DD
for year
in 4 digits), month (2 digits) and day (2 digits).
Example: 2018-10-17
EmployeeBase
Basic information for employees is represented using the type EmployeeBase
:
class EmployeeBase {
int company_id, // Company ID
int id, // Employee ID
string first_name, // First name
string last_name, // Last name
Address address // Address
}
Example:
{
"company_id": 196753,
"id": 42,
"first_name": "Max",
"last_name": "Mustermann",
"address": {
"street_address": "Musterstraße 1a",
"postal_code": "04325",
"location": "Leipzig"
}
}
NewEmployee
The type NewEmployee
is used for the initial creation of new employees. It extends the type EmployeeBase
:
class NewEmployee : EmployeeBase
{
int sex, // Gender (-1 or 0)
Date entry, // Optional: entry date
string email, // Optional: email address
string health_insurance, // The ID of the health insurance for the employee
string insurance_number, // Optional: social security number
string birth_name, // Optional: name at birth
string birth_place, // Optional: place of birth
int country // Optional: country code ** Which one??**
}
See here for details on supported values for the sex
attribute.
Example:
{
"company_id": 196753,
"id": 42,
"first_name": "Max",
"last_name": "Mustermann",
"address": {
"street_address": "Musterstraße 1a",
"postal_code": "04325",
"location": "Leipzig"
},
"sex": 0,
"health_insurance": "05174740",
"entry": "2015-05-01",
"insurance_number": "13120680D891",
"email": "[email protected]"
}
HourlyCompensationType
The type HourlyCompensationType
captures all compensation types. Sage Business Cloud Payroll maps these to internal supported compensation types
Due to that simplifacation, there is no need to agree on or align compensation types between Sage Business Cloud Payroll and your application:
enum HourlyCompensationType {
// Hourly wage
HOURLY_WAGE = "HOURLY_WAGE",
// Holiday premium pay 125%
HOLIDAY_SURCHARGE_125 = "HOLIDAY_SURCHARGE_125",
// Holiday premium pay 150%
HOLIDAY_SURCHARGE_150 = "HOLIDAY_SURCHARGE_150",
// Shift premium 25%
NIGHT_SUPPLEMENT_25 = "NIGHT_SUPPLEMENT_25",
// Shift premium 40%
NIGHT_SUPPLEMENT_40 = "NIGHT_SUPPLEMENT_40",
// Sunday premium pay
SUNDAY_PREMIUM = "SUNDAY_PREMIUM",
// Additional overtime pay
ADDITIONAL_OVERTIME = "ADDITIONAL_OVERTIME",
// Shift premium (variable)
NIGHT_SUPPLEMENT = "NIGHT_SUPPLEMENT",
// Holiday premium pay (variable)
HOLIDAY_SURCHARGE = "HOLIDAY_SURCHARGE"
}
JSON uses strings to represent enumerations of values.
HourlyCompensation
The type HourlyCompensation
represents the time / hours worked by an employee and the applicable compensation:
class HourlyCompensation {
int company_id, // Customer ID
int employee_id, // Employee ID
HourlyCompensationType type, // Compensation type
float total_amount, // Gross wage / salary (optional)
float total_hours, // Hours worked (optional)
float surcharge, // Free extra amount percentage (optional)
Date date, // Day worked (optional)
string cost_center_id, // Cost center (optional)
string cost_object_id // Cost unit / object (optional)
}
- In case no hours worked (
total_hours
) information is provided, 1 hour is assumed. - In case no day worked (
date
) is provided, Sage Business Cloud Payroll uses the first of the month or, for new employees that joined during the month, the day of entry - In case no gross wage / salary (
total_amount
) is provided, the hourly rate stored in Sage Business Cloud Payroll for the employee is used
Sage Business Cloud Payroll calculates the total compensation for the employee based on the product of total_amount
and total_hours
.
- If the associated company in Sage Business Cloud Payroll is configured for cost accounting, then your application
can also transmit cost center and cost unit / object information (
cost_center_id
andcost_object_id
) which will then be respected in Sage Business Cloud Payroll. If this is not the case, any such data transmitted by your application is simply ignored. - The compensation type named
HOLIDAY_SURCHARGE
allows for entering of holiday premium payments with percentages other than the ones supported out of the box. - Similarly, the compensation type
NIGHT_SUPPLEMENT
allows for providing additional payment information for work during the night, compensated by other percentages. - If either one of these is selected, the
surcharge
needs to provide the actual percentage value to be applied - which obviously needs to be a valid percentage (larger than 0).
Example:
[
{
"company_id": 196753,
"employee_id": 42,
"type": "HOURLY_WAGE",
"total_amount": 53.30,
"total_hours": 5.33,
"date": "2015-04-28",
"cost_center_id": "042",
"cost_object_id": "03"
}
]
Example with a surcharge of 15.5%:
[
{
"company_id": 196753,
"employee_id": 42,
"type": "HOLIDAY_SURCHARGE",
"total_amount": 53.30,
"total_hours": 5.33,
"date": "2015-04-28",
"surcharge": 15.5
}
]
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.
FurtherPaymentType
The type FurtherPaymentType
identifies extra payments and deductions. These are then mapped within Sage Business Cloud Payroll
to internal salary types
enum FurtherPaymentType {
// Travel costs
TRAVEL_COSTS = "TRAVEL_COSTS",
// Food allowance
FOOD_ALLOWANCE = "FOOD_ALLOWANCE",
// Bonus payments
BONUS_PAYMENT = "BONUS_PAYMENT"
}
JSON uses strings to represent enumerations of values.
FurtherPayment
The type FurtherPayment
represents extra payments and deductions such as travel expenses, food allowances, or bonus payments.
class FurtherPayment {
int company_id, // Company ID
int employee_id, // Employee ID
FurtherPaymentType type, // Type of payment
float count, // Number of such payments / factor to be applied (optional)
float amount // Amount of payment
}
To represent such a payment, the type is provided as string via type
and the actual amount via amount
.
Additionally, a multiplication factor can be provided via count
(which defaults to 1.0).
Example:
[
{
"company_id": 196753,
"employee_id": 42,
"type": "BONUS_PAYMENT",
"amount": 450.50,
"count": 1
}
]
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.
Creating a New Employee
Creating a new employee requires different parameters, dependent on the actual case. Details are described here.
The data is provided via a NewEmployee
object.
The gender is specified via an integer with 2 supported values:
-1
for a male employee0
for a female employee
If no concrete entry data is provided, the first of the current payroll calculation month of the company is assumed.
To determine the Betriebsnummer (company registration number) of the health insurance, Sage Business Cloud Payroll provides a separate route. The next steps and the data required depend on whether a social security number does exist for the new employee or not
- If a social security number is available for the new employee it needs to bbe provided via a dedicated attribute:
string insurance_number; // Social security number
- If the social security number is not available, some other attributes needs to be provided as they are required
for notification purposes:
string birth_name, // Name at birth string birth_place, // Place of birth Date birth_date, // Date of birth int country, // Country of birth
To correctly represent the place of birth of a new employee, a list is provided with supported standardized country codes.
Example #1:
{
"company_id": 196753,
"id": 42,
"last_name": "Flintstone",
"first_name": "Fred",
"address": {
"street_address": "Karl-Heine-Straße 109",
"postal_code": "04229",
"location": "Leipzig"
},
"entry": "2015-04-28",
"sex": -1,
"email": "[email protected]",
"health_insurance": "67450665",
"insurance_number": "13120680D891"
}
Example #2:
{
"company_id": 196753,
"id": 43,
"last_name": "Rubble",
"first_name": "Barney",
"address": {
"street_address": "Karl-Heine-Straße 109",
"postal_code": "04229",
"location": "Leipzig"
},
"entry": "2015-04-28",
"sex": 0,
"email": "[email protected]",
"health_insurance": "01083422",
"insurance_number": "",
"birth_name": "AnotherLastName",
"birth_place": "Leipzig",
"birth_date": "1985-09-13",
"country": 0
}
Administrative Data
Health Insurance Information
The Sage Business Cloud Payroll API provides call to retrieve a list of all health insurances in Germany starting January 1st, 2015. The list can be retrieved as a CSV file:
GET /api/v1/healthinsurances.csv
Host: lohnabrechnung.sage.com
Accept: text/csv
The .csv
file contains entries in the following format (5 values per health insurance, separated by a semicolon):
Field name | Description |
---|---|
AvailableFrom (may be empty) |
The first day as of which this health insurance was operating (if after 01-01-2015) |
AvailableFrom (may be empty) |
The last day until which this health insurance was operating |
CompanyName |
The name of the health insurance |
CompanyNumber |
Company registration number (“Betriebsnummer”) |
Replacement (may be empty) |
If a health insurance is not operating any longer, there may be a legal successor, for example if insurances merge. In this case, the company registration number of that successor can be provided here |
- If none of the dates is specified, then it is assumed that the health insurance is operating today and has started at least before January 1st, 2015. The health insurance specified for a new employee needs to be operating at the time of entry of the new employee.
- Data entries in the list use the ISO 8601 format (yyyy-mm-ddThh:mm:ss)
Example:
Health insurance “BKK GS ehemalig BKK BJB” has the following list entry:
CompanyNumber;CompanyName;AvailableFrom;AvailableTo;Replacement
41690170;"BKK GS ehemalig BKK BJB";;2015-09-30T00:00:00;31323802
So this health insurance operated until September 30, 2015. Afterwards, the health insurance with the company
registration number 31323802
took over operations.
An employee assigned to this health insurance needs to be assigned a different health insurance after September 2015, else the payroll run in Sage Business Cloud Payroll reports an error for runs starting October 2015. As a default, the employee is assigned automatically to the successor health insurance.
It is recommended to download the list of health insurances once a month to identify and changes.
Country Information
The Sage Business Cloud Payroll API provides call to retrieve a list of all supported countries and the codes to be used for them. The list can be retrieved as a CSV file:
GET /api/v1/countries.csv
Host: lohnabrechnung.sage.com
Accept: text/csv
The .csv
file contains entries in the following format (3 values per country, separated by a semicolon):
Field name | Description |
---|---|
ID |
Country code |
Country |
Name of country |
Nationality |
Nationality for the country to use as text in communication (e. g. “deutsch” for “Deutschland”) |
Account Owner
To retrieve the account owner, a separate API invocation is provided which returns the name of the account owner. This is the name provided when registering your application:
GET /api/v1/username
Host: lohnabrechnung.sage.com
Accept: application/json
The name of the account owner is returned in the data
field. Note that authentication credentials
need to have been established.
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 error
attribute:
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
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
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
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
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
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.
Appendix
Acronyms
Acronym | Stands for |
---|---|
API | Application Programming Interface |
ASCII | American Standard Code for Information Interchange |
HTTP | Hypertext Transfer Protocol |
JSON | JavaScript Object Notation |
TLS | Transport Layer Security |
URI | Uniform Resource Identifier |
URL | Uniform Resource Locator |