Skip to content
Developer home

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 NewEmployeeis 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 and cost_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.