Getting Started

This page will help you get started with your new API.

Introduction

Welcome to the Rollee Company API here you will find information on the process as well as all the calls that you can make and need to be made in order to retrieve data from your users.

Getting Started

Rollee provides you with two environments to test and go live with the solution. The first test can be done on the sandbox with fake credentials returning anonymized data to allow you to see more details on what data points are available per data source. Production can then be used first to trial with specific users and then to go live with all users. This environment requires real credentials and returns real data.

Environments

We provide you with two different environments. The first is Sandbox in order to allow you to test our API without needing real credentials. The second is the Production environment where you will need real credentials in order to request data.

1. Sandbox

The first environment we provide is based entirely on fake credentials and data. This is to get a feel for how the system works and the data you get back.

In Sandbox mode, you can build and test your integration. You must use test credentials to authenticate with payroll and gig platforms
All API endpoints return mock data which is static and updated periodically; Meaning a deeper understanding of the up-to-date data should be done on a test environment with real credentials and real data. Name and Logo show on Connect.

On Sandbox:

  1. Fake credentials only
  2. No error testing
  3. Static data returned

2. Production

This environment is live with your users. Analytics will be running and available in this environment.

API endpoints return real data and platforms are kept up to date.

On Production:

  1. Real credentials only
  2. Real data returned
  3. Logo and customizations (required)
  4. Custom list of data sources in search (optional)

Authentication

The rollee's API is protected with JWT authentification. The initial token is provided by rollee with a certain validity time period.
You can create a new valid token, when the previous one is closed to expire, using the API.

Examples using curl:

  • Get list of companies
curl -X GET -H "Authorization: Bearer <YOUR_TOKEN>" https://api.getrollee.com/api/company/v0.1/companies
  • Refresh token
curl -X GET -H "Authorization: Bearer <YOUR_TOKEN>" https://api.getrollee.com/api/company/v0.1/token/refresh

json response:

{
    "token": "YOUR_NEW_TOKEN"
}

In case of wrong usage of the token, API's call will return a 401 Unauthorized response.

Conventions

Here is a list of conventions about some terminology used by Rollee products regarding the usage of the API.

Datasources or Platforms

Datasources are what we call the various sources of incomes users may have. This may be payroll platforms, driving and delivery platforms as well as freelance platforms. Rollee will collect and process data and service this data to our customers. (contact rollee support to have the list of supported datasources).

Companies

As a client that manages one or several companies, you register these companies in the API and then you can connect accounts (from a datasource) for each of them. This will allow you to request data from the users later.

Company accounts

Company Accounts represent the links between a company and a datasource. Companies can have multiple company accounts if they exist in multiple datasources . Each account is also identified with a UUID.

Users

Users are members (employees, drivers, etc) of a particular company. Each user represents a physical person and has a unique UUID which will be used in the API's responses.

User Accounts

User Accounts represent the links between a user and a datasource. A user can have multiple accounts if he exists in multiple datasources . Each user account is also identified with a UUID.

Endpoints

Endpoints are business entities under which sets of data are organized and served by the API.
For example, the profile endpoint serves data about the identity of users.

Dates and IDs

Some conventions used throughout our API and documentation are:

  • All date-times are returned as strings in RFC 3339 order in UTC Timezone, like: 2021-06-30 14:30:00 UTC
  • All IDs are represented as UUIDs, e.g., 01234567-89ab-cdef-0123-456789abcdef