Get started

Less than 10 minutes to read

This page contains all the information and steps required to get started using the Sage Business Cloud Payroll API.

Once you have done all the heavy-lifting with registration and authentication setup, the guides show how to actually make it work and invoke a first set of API calls.

Please note that currently, as mentioned in the API overview, this API is only supported in the German product version, but you can still use it from anywhere (albeit the actual UI pages in the product are in German).

The API was initially designed for integration with partner products that would benefit from exchanging data with Sage Business Cloud Payroll. It can be used for other use cases of course, for example for developers interested in getting experience with the API and the product to come up with new ideas that do not yet exist as a product to integrate with. So, for simplicity, this document refers to your application as the client integrating with the Sage Business Cloud Payroll API.

The steps described will allow you to get up and running with the Sage Business Cloud Payroll API.

Prerequisites

The following prerequisites must be met in order to be able to use the API of Sage Business Cloud Payroll:

Your application must use encrypted connections (HTTPS) to ensure confidentiality
Your application must be registered with Sage (see below)
A customer who wants to use the integration of your application and Sage Business Cloud Payroll must be registered both in your application as well as in Sage Business Cloud Payroll

Registration of your application

To integrate the Sage Business Cloud Payroll API into your application, the product must first be registered with Sage:

Send an email to [email protected]

The following data is required for registration:

The name of the accountable company or person (as a individual developer, pick yourself)
The name of your application (pick one if you’re working on a test client integration)
The URL under which your application can be reached (if available)

Sage then assigns the product-specific API credentials:

Client ID
Client Secret

The Client Secret is to be treated confidentially and is known only to you and to Sage. In combination with the Client ID, the unique identification of your application takes place.

Authentication

This section explains how to use OAuth 2.0 to allow users to authorize your application (the client) to access their data without sharing their actual login details.

With every API request, you must supply a valid access token within the authorization header:

Authorization: Bearer ‹Access Token›

Obtaining an Access Token

The steps outlined here explain how to obtain the access token.

Authorization request

Redirect the user to the authorization endpoint, https://lohnabrechnung.sage.com/api/auth, with the relevant URL query parameters:

Parameter	Description
`client_id`	Partner product-specific client ID (see registering your application)
`response_type`	The type of response. This is always code.
`redirect_uri`	Your application callback URL. This is where your users will be sent after authorizing.
`state`	A string used to protect against CSRF attacks. Although state is optional, we recommend including this. This should be a string that cannot be guessed. Note: If the value of the state parameter returned in the response does not match the state that was provided in the original request, it does not originate from the original request and you must not continue.

Example redirect URL:

https://lohnabrechnung.sage.com/api/auth
    ?client_id=4b64axxxxxxxxxx00710
    &state=4Whsv35d82bdbay6
    &redirect_uri=https://myapp.com/auth/callback

When this endpoint is hit, the user is prompted to sign in to Sage Business Cloud Payroll and then is redirected to the callback URL along with an authorization code which can be read from the response:

GET /auth/callback
    ?code=12a0f9c12cxxxxxxxxxxxxxxx92a48cc1f237ead
    &state=...
    &error_description=...
    &error_uri=...

code is the authorization code
state is the state value, unchanged, sent during the authorization request

Error handling:

GET /auth/callback
    ?error=...
    &state=...
    &error_description=...
    &error_uri=...

error_description is optional and a human-friendly error (as much as friendly can be an error).
error_uri is optional too and URI zu einer Internetseite mit Fehlerdetails
state is the state value, unchanged, sent during the authorization request

Possible errors:

Error code	Description
`access_denied`	This error occurs when the user chooses not to authorise your application.
`invalid_request`	This error occurs when a required parameter is missing, invalid or provided more than once.
`server_error`	This generic error occurs when the authorization server encounters something unexpected that prevents it from fulfilling the request.
`temporarily_unavailable`	This error occurs when the authorization server is unavailable. We recommend waiting for 10 minutes before retrying.
`unauthorized_client`	This error occurs when the client is not authorized to perform this action. This may be due to an incorrect client_id value.
`unsupported_response_type`	This error occurs when the authorization server does not support the method being used to request the code. You should ensure that the `response_type` in your request is code.

Exchange the authorization code for the access token

To exchange the authorization code for an access token, you should now make a POST request to the token endpoint:

https://lohnabrechnung.sage.com/api/token

Required parameters:

Name	description
`code`	The authorization code provided in the response from the previous step.
`client_id`	Partner product-specific Client ID (see registering your application)
`client_secret`	Partner product-specific Client Secret (see registering your application)
`redirect_uri`	Your application callback URL. This is where your users will be sent after authorizing.
`grant_type`	This must be `authorization_code`

Example request:

POST https://lohnabrechnung.sage.com/api/v1/token
    ?code=...
    &client_id=...
    &client_secret=...
    &grant_type=authorization_code
    &redirect_uri=...

Example response :

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

{
    "access_token": "...",
    "token_type": "Bearer"
}

The OAuth implementation in Sage Business Cloud Payroll uses JSON-Web-Token (JWT).

The access token (access_token) and the token type (token_type) need to be securely stored within your application in connection with the customer account.

Please note that the token information is a piece of confidential information between Sage and your application. It must not be divulged to any third party as this does compromise the confidentiality and integrity of customer data.

Error Handling

Errors can occur when requesting an access token. Possible causes are:

Invalid data (parameters) in the request
Invalid client data (client ID, client secret)
Invalid authorization code

The HTTP response sent by Sage Business Cloud Payroll is structured like this:

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

{
    "error": "...",
    "error_description": "...",
    "error_uri": "..."
}

error is always provided (see below for error codes)
error_description is optional and a human-friendly error
error_uri is optional, too, and (if available) points to a web page with more information and details

Possible error codes:

Error code	Description
`access_denied`	This error occurs when the user chooses not to authorise your application.
`invalid_request`	This error occurs when a required parameter is missing, invalid or provided more than once.
`server_error`	This generic error occurs when the authorization server encounters something unexpected that prevents it from fulfilling the request.
`temporarily_unavailable`	This error occurs when the authorization server is unavailable. We recommend waiting for 10 minutes before retrying.
`unauthorized_client`	This error occurs when the client is not authorized to perform this action. This may be due to an incorrect client_id value.
`unsupported_response_type`	This error occurs when the authorization server does not support the method being used to request the code. You should ensure that the `response_type` in your request is code.