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.

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.

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.

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.

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:

Conventions

Some conventions used throughout our API and documentation are:

Data Sources

We currently focus on gig workers to help them having access to more services, from credit to rentals. Gig workers usually work for different platforms at the same time. By allowing them to share securely their employment data through Rollee, we allow businesses to get a complete view of their professional situation and be fairer in their selection criteria. We will extend our coverage to other workers categories, from freelancers to permanent workers.

Gig platforms:

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. So: be very careful when storing it.

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 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, but also is an aggregate of fetches.

A fetch is the process of authenticating a user on a datasource, and fetching all the interesting data that will be of interest. The fetch happens only once, when the user gives access to doing it.

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",
            ...
        },
        "pages": null
    },
    "datas": [
        {
            "id": uuid string,
            "name": string,
            "attrs": {
                "abc": "def",
                "ghi": "jkl",
                ...
            }
        },
        ...
    ]
}

A user contains many fetches.

A fetch is the process of authenticating a user on a datasource, and fetching all the interesting data that will be of interest. The fetch happens only once, when the user gives access to doing it.

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

Endpoint

curl -H "x-api-key: <your-api-key>" "https://connect.getrollee.com/api/0.2/endpoint/<endpoint>?fetch=<fetch-id>"
Request URL
API https://connect.getrollee.com/api/0.2/endpoint/<endpoint>?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",
            ...
        },
        "pages": null
    },
    "<endpoint>s": [
        {
            "abc": "def",
            "ghi": "jkl",
            ...
        },
        ...
    ]
}

An endpoint is a filter on the data of the fetch.

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",
                ...
            }
        },
        ...
    ]
}

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",
                ...
            },
            "pages": null
        },
        ...
    ]
}

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",
                ...
            }
        },
        ...
    ]
}

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 URL
HTML https://connect.getrollee.com/ptr/0.2/user/new?partner=<partner-id>&abc=def
API 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
    }
}

New Fetch

curl -H "x-api-key: <your-api-key>" "https://connect.getrollee.com/api/0.2/fetch/new?user=<user-id>&source=<source>&auth-user=<...>&auth-password=<...>"
Request URL
HTML https://connect.getrollee.com/ptr/0.2/fetch/new?user=<user-id>&source=<source>&auth-user=<...>&auth-password=<...>
API https://connect.getrollee.com/api/0.2/fetch/new?user=<user-id>&source=<source>&auth-user=<...>&auth-password=<...>
{
    "fetch": {
        "id": uuid string,
        "initiated-at": datetime string,
        "connected-at": datetime string,
        "completed-at": datetime string,
        "status": "complete" || "connected" || "error" || "code" || "",
        "attrs": null,
        "pages": null
    }
}

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