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

Plan your verification of income & employment integration with Connect.

You can start making better decisions with verified income and employment data from reliable sources. Connect provides you with these verifications in a quick easy to use fashion where simplicity, conversion, and user awareness are key points of focus.

Scoping your project before integrating with Connect in order to determine how you want to use it in your workflow and how/where to present it to your users.

Once you know where Connect fits into your app workflow you are ready to integrate. Below are a few more pointers.

How to get started

  1. Where to use Connect
  2. Best experience and conversion rate
  3. Post Connect workflow
  4. Scope the data you need
  5. Customization

Where to use Connect?

Connect provides you with all the information within a user's account. This can be used at various stages in your application's process:

How to prep users for Connect?

It is important to frame Connect correctly for your users. The goal is for the users to complete the flow necessary for your app to access their data and provide a service. A good implementation of Connect requires the users to understand and have context before going through the connect flow.

  1. Understanding - users need to clearly understand why they are verifying their income & employment and the benefit this will give them. Making it clear that this will allow them to complete their application faster and with more confidence
  2. Context - provide users with context into the process they will go through. Users need to understand that they will connect to their employer in order to complete a flow within your app. If the experience is integrated this can be done seamlessly. If you are planning on redirecting a user make sure they know and understand why

Post Connection user flow?

After a user connects their accounts and they are sent back into your application, it is important to let the users know what will happen next in the process. It is always good to reaffirm the user was successful in their linking of accounts as they continue their journey in your application. Having a dedicated screen for the post connection will provide a better user experience.

Scope the required Data

Connect can give you access to 100+ employment record data points such as:

Refer to the full list of available data points in the Rollee Connect API documentation in order to match your use case to the data Rollee Connect can provide

Customization

We understand how important it is to have a cohesive user experience, so we’ve made Connect customizable according to our customer's standards. Some notable customizations include:

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.

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