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 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 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)
}

Sage Business Cloud Payroll calculates the total compensation for the employee based on the product of total_amount and total_hours.

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

The gender is specified via an integer with 2 supported values:

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

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

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