Object Types
Less than to read
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 Creating a new employee 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.