NAV
shell

Overview

Introduction

Welcome to Rollee, the secure API for employment data.

Rollee makes it easy for your users to grant you access to their employment accounts.

Once one of your users grants access, your application can access his or her employment and income data.

Post Connection User Flow

Rollee API is built on RESTful principles. All requests and responses are encoded in JSON. For security purposes, all requests must be sent via HTTPS.

You can choose among several programming languages.

For any questions, please contact us: contact@getrollee.com

Overview Rollee Connect

Rollee provides your company with user permission data. We provide various endpoints with relevant information such as Income, Identity, Activity, and Employment. With Rollee you can empower your users to use your service in just a few clicks. Rollee enables you to start making more informed decisions based on standardized and reliable data.

How and Where to use Rollee Connect

The Rollee Connect allows users to easily 'connect' their accounts in order to provide you with the necessary data. A demo can be seen on our website.

What is Connect

It is important for you to know where Connect fits into your workflow and how best to integrate it in order to have the best user experience. We are happy to work closely with you to ensure the best conversion and ease of use for your users.

Full Connect Flow

Getting Set Up

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.

What do we need from you?

What do you need from us?

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

All the information you need will be provided during the onboarding:

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)

All the information you need will be provided during the onboarding:

API Testing

Test the API and get user data with the following URLs which we will provide during the onboarding

Customization

We understand how important it is to have a cohesive user experience, so we’ve made Connect customizable according to your needs. The following are currently available customizations:

Connect Customization

Full Customization v.1

Conventions

Some conventions used throughout our API and documentation are:

API 0.2

Get Partner

curl -H "x-api-key: <your-api-key>" "https://connect.getrollee.com/api/0.2/partner/<partner-id>"
Request URL
HTML https://connect.getrollee.com/ptr/0.2/partner/<partner-id>
API https://connect.getrollee.com/api/0.2/partner/<partner-id>
{
    "partner": {
        "id": uuid string,
        "name": string,
        "url": url string,
        "title": string,
        "logo": url string,
        "email": email string,
        "users": [
            {
                "id": uuid string,
                "api-url": url string,
                "created-at": datetime string
            },
            ...
        ]
    }
}

The partner is your entry point to the API. The id that you need to use as your <partner-id> would have been given to you by Rollee. It takes the form of a UUID.

The api-key is a secret value that gives you access to all your data as a partner, and to all the data of your users.

Feel free to request a change of your key at anytime, as it takes only a second and it immediately secures your account again, as every new request on the API will immediately need the new key.

Get partner query allows you to list all the users associated to one partner.

Get User

curl -H "x-api-key: <your-api-key>" "https://connect.getrollee.com/api/0.2/user/<user-id>"
Request URL
HTML https://connect.getrollee.com/ptr/0.2/user/<user-id>
API https://connect.getrollee.com/api/0.2/user/<user-id>
{
    "user": {
        "id": uuid string,
        "created-at": datetime string,
        "attrs": {
            "abc": "def",
            "ghi": "jkl",
            ...
        },
        "fetchs": [
            {
                "id": uuid string,
                "api-url": url string,
                "created-at": datetime string
            },
            ...
        ]
    }
}

A partner contains many users.

A user is a physical person. In one user there can be one or more fetchs.

Get user query allows you to list all the fetchs associated to one user.

Get Fetch

curl -H "x-api-key: <your-api-key>" "https://connect.getrollee.com/api/0.2/fetch/<fetch-id>"
Request URL
HTML https://connect.getrollee.com/ptr/0.2/fetch/<fetch-id>
API https://connect.getrollee.com/api/0.2/fetch/<fetch-id>
{
    "fetch": {
        "id": uuid string,
        "initiated-at": datetime string,
        "connected-at": datetime string,
        "completed-at": datetime string,
        "status": "complete" || "connected" || "error" || "code" || "",
        "attrs": {
            "abc": "def",
            "ghi": "jkl",
            ...
        }
    },
    "datas": [
        {
            "id": uuid string,
            "name": string,
            "attrs": {
                "abc": "def",
                "ghi": "jkl",
                ...
            }
        },
        ...
    ],
    "standard-datas": [
        {
            "endpoint": string
            "datas": [
                {
                    "abc": "def",
                    "ghi": "jkl",
                    ...
                },
                ...
            ]
        },
        ...
    ]
}

A fetch is the process of authenticating a user on a datasource, and fetching all the data that will be of interest. The fetch is generated, when the user gives his consent to doing it.

A fetch contains relevant data, each containing data points, depending on the data type.

Get fetch query allows you to list all the datas associated to one fetch.

Search All Users

curl -H "x-api-key: <your-api-key>" "https://connect.getrollee.com/api/0.2/users/?partner=<partner-id>"
Request URL
API https://connect.getrollee.com/api/0.2/users/?partner=<partner-id>
{
    "users": [
        {
            "id": uuid string,
            "created-at": datetime string,
            "attrs": {
                "abc": "def",
                "ghi": "jkl",
                ...
            },
            "fetchs": [
                {
                    "id": uuid string,
                    "api-url": url string,
                    "created-at": datetime string
                },
                ...
            ]
        },
        ...
    ]
}

Unlike the get partner query, which will only list all the contained users ids, the get all users query will:

Optional parameters

Search All Fetchs

curl -H "x-api-key: <your-api-key>" "https://connect.getrollee.com/api/0.2/fetchs/?user=<user-id>"
Request URL
API https://connect.getrollee.com/api/0.2/fetchs/?user=<user-id>
{
    "fetchs": [
        {
            "id": uuid string,
            "initiated-at": datetime string,
            "connected-at": datetime string,
            "completed-at": datetime string,
            "status": "complete" || "connected" || "error" || "code" || "",
            "attrs": {
                "abc": "def",
                "ghi": "jkl",
                ...
            }
        },
        ...
    ]
}

Unlike the get user query, which will list all the contained fetchs ids only, the get fetchs query will:

Optional parameters

Search All Datas

curl -H "x-api-key: <your-api-key>" "https://connect.getrollee.com/api/0.2/datas/?fetch=<fetch-id>"
Request URL
API https://connect.getrollee.com/api/0.2/datas/?fetch=<fetch-id>
{
    "datas": [
        {
            "id": uuid string,
            "name": string,
            "attrs": {
                "abc": "def",
                "ghi": "jkl",
                ...
            }
        },
        ...
    ]
}

Search All Standard Datas

curl -H "x-api-key: <your-api-key>" "https://connect.getrollee.com/api/0.2/standard-datas/?fetch=<fetch-id>"
Request URL
API https://connect.getrollee.com/api/0.2/standard-datas/?fetch=<fetch-id>
{
    "standard-datas": [
        {
            "endpoint": string,
            "datas": {
                "abc": "def",
                "ghi": "jkl",
                ...
            }
        },
        ...
    ]
}

New User

curl -H "x-api-key: <your-api-key>" "https://connect.getrollee.com/api/0.2/user/new?partner=<partner-id>&abc=def"
Request Method URL
API POST https://connect.getrollee.com/api/0.2/user/new?partner=<partner-id>&abc=def
{
    "user": {
        "id": uuid string,
        "created-at": datetime string,
        "attrs": {
            "abc": "def",
            ...
        },
        "fetchs": null
    }
}

Create a new user allows you to be sure that all the data from one user will be stored in the same user.

To easily identify your users you can add custom fields (the abc=def part).

Those fields will be inserted inside the user and presented on each API call on users, so that you will always know which user is which.

You can add as many custom fields as you want:

1) To create a new user you can first create a user on Rollee from the API (with custom fields if you want):

Then give the user his own user link for accessing the Rollee Connect:

That way the user won't see the data you associated with him (and won't be able to change it as well).

2) An alternative technique is to directly add these custom fields on the new user link of the Rollee Connect:

New Fetch

curl -H "x-api-key: <your-api-key>" "https://connect.getrollee.com/api/0.2/fetch/new?from-fetch=<fetch-id>"
Request Method URL
API POST https://connect.getrollee.com/api/0.2/fetch/new?from-fetch=<fetch-id>
{
    "fetch": {
        "id": uuid string,
        "initiated-at": datetime string,
        "connected-at": datetime string,
        "completed-at": datetime string,
        "status": "complete" || "connected" || "error" || "code" || "",
        "attrs": null
    }
}

When a user has successfully connected an account through the Rollee Connect, a fetch is automatically generated and contains all the fetched data from that account.

Each time you need to refresh that data, a new fetch needs to be generated.

The Create New Fetch query allows to refresh the data from an existing fetch. A new fetch will be created, and automatically associated to the same user.

Del Fetch

curl -H "x-api-key: <your-api-key>" -X DELETE "https://connect.getrollee.com/api/0.2/fetch/<fetch-id>"
Request Method URL
API DELETE https://connect.getrollee.com/api/0.2/fetch/<fetch-id>
{
    "success": "done"
}

Delete a fetch

Endpoints

An endpoint is a standardized data that was transformed by Rollee from the raw data that the datasource was presenting. In a way, it's an intersection of what all the datasources have on a topic.

Request URL
API https://connect.getrollee.com/api/0.2/endpoints/
API https://connect.getrollee.com/api/0.2/endpoints/?render=yaml
{
  "endpoints":[
    {"name":"activity"},
    {"name":"document"},
    {"name":"employment"},
    {"name":"identity"},
    {"name":"income"},
    {"name":"payout"},
    {"name":"trip"},
    {"name":"vehicle"}
  ]
}

Instances

An instance is a subset of the endpoints that you want the fetch to contain, in order to optimize the fetching time. The default is to let all the endpoints to load and for that, no instance need to be specified.

New instance or Set instance

Request Method URL
API POST https://connect.getrollee.com/api/0.2/instance/<instance-name>?partner=<partner-id>&endpoint=abc&endpoint=def&...

abc and def in this example would be the available endpoints from the /endpoints/ query, like endpoint=activity or endpoint=document

Get instance

Request Method URL
API GET https://connect.getrollee.com/api/0.2/instance/<instance-name>?partner=<partner-id>

Del instance

Request Method URL
API DELETE https://connect.getrollee.com/api/0.2/instance/<instance-name>?partner=<partner-id>

Webhooks

A webhook is a link between an event that happens on the Rollee platform, and an action that is initiated from the Rollee platform in order to reach your platform. The action can take multiple forms:

The complete list of events is available at this endpoint:

Request URL
API https://connect.getrollee.com/api/0.2/events/
API https://connect.getrollee.com/api/0.2/events/?render=yaml

The complete list of actions is available at this endpoint:

Request URL
API https://connect.getrollee.com/api/0.2/actions/
API https://connect.getrollee.com/api/0.2/actions/?render=yaml

New action

Request Method URL
API POST https://connect.getrollee.com/api/0.2/action/new?partner=<partner-id>&event=<event-name>&action=<action-name>&url=<url>&mail-to=<mail-to>&mail-title=<mail-title>

Optional parameters:

Get action

Request Method URL
API GET https://connect.getrollee.com/api/0.2/action/<action-id>?partner=<partner-id>

Del action

Request Method URL
API DELETE https://connect.getrollee.com/api/0.2/action/<action-id>?partner=<partner-id>

Errors

Code Message
400 Bad Request
401 Unauthorized
403 Forbidden
404 Not Found
405 Method Not Allowed
406 Not Acceptable
410 Gone
429 Too Many Requests
500 Internal Server Error
503 Service Unavailable