The Unveel API is a hypermedia-driven REST API. It embraces JSON for Linked Data (JSON-LD) and Hydra Core Vocabulary. Accepts JSON-encoded bodies and uses standard HTTP response codes, authentication, and verbs.

You can use API in sandbox and production mode. Each of the environments has separate credentials and URLs.

Authentication to the API is performed via HTTP Basic Auth. Provide your client id as the basic auth username value and client_secret as a password. Your API keys carry many privileges, so be sure to keep them secure! Do not share your client_secret in publicly accessible areas such as GitHub, client-side code, and so forth. All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

Unveel API uses HTTP response codes to indicate the success or failure of an API request. Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided. Codes in the 5xx range indicate an error with servers. 404 code means that requested data is missing or the URL not exists. The difference is that missing data returns hydra description "Not Found" and invalid URL returns hydra description "URL Not Exists."

Endpoints that return a collection of data contain more context information about the collection:

• "hydra:totalItems" - number of items in the collection,
• "hydra:view" - information about first, last, next, and previous page of pagination,
• "hydra:search" - with information about filters that you might use in the endpoint. Currently, API doesn't support changing the limit of items returned by the endpoint.

In response headers you can find three headers:

• X-RateLimit-Remaining - number of available requests in the current minute
• X-RateLimit-RetryAfter - this header contains information about when next request will be acceptable
• X-RateLimit-Limit - maximum number of requests per minute

You can configure webhook endpoints via the API to be notified about events that happen in your client Unveel account or connected accounts.

Unveel uses webhooks to notify your application when an event happens in your client account. Data from your user's accounts are imported asynchronously, which makes webhooks very handy. Instead of making requests to check if something new was imported, we encourage you to use webhooks.

For each event occurrence, Unveel POSTs the webhook data to your endpoint in JSON format. Each webhook request includes a URL that you can use to fetch data from the API. Requests don't have data. The webhook endpoint needs to: Return a 200 status code. Any other code is considered a failure, and the webhook will be repeated. Return quickly. The endpoint has to return a response within 5 seconds. If it takes more time, it will be considered a failure and repeated.

Each webhook request consists X-Unveel-Signature header. You can use this header to validate the request. The header consists of keyed hash values using the HMAC method with the sha512 algorithm.

Pattern:

echo -n "webhook request data" | openssl sha512 -hmac "webhook secret"

• "webhook request data" is a JSON body that is sent to your address
• "webhook secret" is your secret provided by Unveel

Example:

echo -n "{"webhookId":"3d00a0e2-9a84-4366-b1f2-4bd5014199aa","name":"Account-Sync","type":"account-synced","url":"https://api.unveel.io/accounts/4aaf3216-1305-43d8-af6b-61441a48d6ba","payload":{"id":"4aaf3216-1305-43d8-af6b-61441a48d6ba"}}" | openssl sha512 -hmac "WEBHOOK_SECRET"

returns:

SHA512(stdin)= 35da6b6c1f4364f9339e835fdb2396e2fc8fb8f0f4836db051240e6ad05f1a166eb7729a3502e5035b2707a1cdc9c49dfb5724029ebfb771bfba8817f8769029

The Unveel API doesn't provide a list of API address from where API will send requests.

Each repeated request has headers:

• X-Unveel-Date - date of the first attempt of the delivery
• X-Unveel-Try - which attempt is it Each request is retried three times with a delay of 2 seconds.

The Unveel doesn't ensure that webhooks will be sent in any order.

There are several types of webhooks:

• account-connected - triggered when authentication was finished successfully.
• account-created - triggered when profile data from partner are imported.
• account-updated - triggered when new data is imported for the account.
• account-removed - triggered when the account was removed.
• account-synced - triggered when scan is finished. This webhook has two additional optional properties in payload: "payoutTimeLimit" and "workTimeLimit" which can be used as filters in work and payout endpoints.
• account-partially-synced - triggered when scan for work data reached particular point in time configured in params type ("days" key)
• work-created - triggered every time new work data item was imported for the first time
• work-updated - triggered every time single work data was updated
• payout-created - triggered every time new payout data item was imported for the first time
• payout-updated - triggered every time single payout data was updated
• payment-account-changed - triggered when payment account was changed for the account
• payment-account-change-failed - triggered when payment account change failed for the account. Payload has details about fail reason.
• payment-account-verification-failed - triggered when payment account in partner platform is different than changed by Unveel API

You can register a webhook endpoint by using the "/webhooks" endpoint.

To register webhook for e.g "account-created" you need to provide the name, type, and URL where we will send data.

• name - name of your webhook
• type - one of the types from the list above
• url - a destination where we should send data. Have to be an HTTPS address

POST /webhooks
{
  "name": "account-created example",
  "type": "account-created",
  "url": "https://youraddress.com/created",
}

For "account-partially-synced" webhook you can specify the params property with an object containing the "days" property. Every time we will import data older than x days webhook will be triggered.

POST /webhooks
{
  "name": "account-partially-synced example",
  "type": "account-partially-synced",
  "url": "https://youraddress.com/account-partially-synced",
  "params": {
    "days": 180
  }
}

Validation by Unveel side

Each address which you defined during the webhook registration is validated before it will be used. For validation, we send a GET request to the provided URL with the "challenge" parameter, and your endpoint should respond with 200 status code and return challenge code in json body.

Validation from Unveel side should be triggered just after webhook registration.

Example:

we send GET request to your address:

GET https://youraddress.com/account-partially-synced?challenge=CODE

your address should respond us json body

{
  "challenge": "CODE"
}

All webhooks have the same structure of the body which is send via the POST method for defined url (from registration webhook process)

{
  "webhookId": "3d00a0e2-9a84-4366-b1f2-4bd5014199aa",
  "name": "Account-Sync",
  "type": "account-created",
  "url": "https:\/\/api.unveel.io\/accounts\/4aaf3216-1305-43d8-af6b-61441a48d6ba",
  "payload": {
    "id": "4aaf3216-1305-43d8-af6b-61441a48d6ba"
  }
}

However "account-synced" webhook has two additional properties arrive in the payload. These two properties (workTimeLimit and payoutTimeLimit) are dates but can be also nullable. If these values are null means that the full scan was triggered

{
  "webhookId": "3d00a0e2-9a84-4366-b1f2-4bd5014199aa",
  "name": "Account-Sync",
  "type": "account-synced",
  "url": "https:\/\/api.unveel.io\/accounts\/4aaf3216-1305-43d8-af6b-61441a48d6ba",
  "payload": {
    "id": "4aaf3216-1305-43d8-af6b-61441a48d6ba",
    "workTimeLimit": "2022-11-05 03:00:21",
    "payoutTimeLimit": "2022-11-05 03:00:21"
  }
}

After a user successfully connects an account for a partner, we import account data and all historical work data. Account data usually are imported within seconds after connection, but importing work data may take several hours to finish. Work data is imported in order, which means that recently finished work is imported first. After the first initial import was finished, Unveel re-imports the account and the last two weeks of work data every four hours. Uber has a hard limit of 212 weeks of last work data that is imported.

An account might have different statuses:

• connecting - means that a user started the authentication process, but it was not finished yet.
• connected - means user finished authentication process and credentials are still valid.
• authenticationError - means user credentials were revoked and requires users to reauthenticate in UnveelConnect.
• error - means last import failed for an unknown reason, doesn't require user interaction and will be resolved by Unveel crew.

A work income might have different types:

• bonus - the amount of money which is a bonus
• cash - the amount of money earned by cash
• cashReceived - the amount of cash which gig-worker get from customer
• donation - amount of money donated for some cause by the customer from given work earnings (platform specific)
• fees - the amount of money which is a fee
• guaranteed - the amount of money which is guaranteed if gig-worker works a defined number of hours, earns defined amount per day, or arrives at work (specific for some platforms)
• incentive - used only for work type incentive to different from other income types. Incentive work type is not paid for a single activity, but rather a series of activities, for example, 5 rides per day. It is not included in total.
• tax - VAT tax deducted from gig-worker earning for given work
• tips - the amount of money which is a tip
• total - it's a total amount which was earned (including bonuses, tips etc.) - does not include income with type incentives
• totalCharge - it's a total amount which was charged (total amount + fees)

All time-related data is returned in UTC-0 timezone. Work data for some partners might return user timezone, which may be used to recalculate time from a user perspective.

Unveel SDK is the javascript SDK that can be used to connect users accounts with Unveel and allow you to access their data via the Unveel API. Unveel SDK handles credential validation, multi-factor authentication, and error handling for each partner platform. Unveel SDK is utilizing iframe to show user Unveel Link page.

Unveel SDK methods:

start(options)

This method render Unveel Link page inside iframe and connect callbacks.

Required options:

• htmlElement - HTML Element which will be used as parent to display Unveel Link
• pluginKey - your Unveel SDK plugin key created for you during onboarding

Optional:

• jwtToken - token which identifies your user. If user use Unveel SDK for the first time SDK will create user and call userCreated callback with his userId and token. More information
• sandbox - boolean value. Set to true if you want to connect to sandbox environment.
• partners - array of partners ids to show in the Unveel SDK. Passing one partner will disable the partners list and display only selected partner.
• features - array of selected features to show in the Unveel SDK. Passing array of features will filter out partners which don't support desired features.
  • Supported values:
    • scan - Full scan partners
    • authentication - Authorization partners
    • change_bank_account - payment account details change feature
  • By default, only full scan partners are enabled with default value: ['scan'].
• accountRequest - encrypted payment account details change request data. Data can be obtained from Unveel API to encrypt payment
• hideClose - boolean flag to hide close button if you prefer to handle closing. By default, set to false.
• language - language used by Unveel SDK, english is default choice.
  • Supported values:
    • en - English
    • pl - Polish
• country - two-letter country code for default country set for user. By default, set to US.

destroy()

Method removes event listeners

Should be called when SDK is no longer used to detach event listeners and form.

Callbacks

List of callbacks to hook into flow:

• close - called when the Unveel SDK component is closed.
• accountConnected - called when user successfully authenticates with partner platform
• accountCreated - called when user starts authentication process
• accountRemoved - called when user removes partner account
• userCreated - called when component was initialized without token and new user was created. Store token and user id in backend database to reuse it next time user will interact with the Unveel SDK.
• tokenExpired - called when passed token is expired. You should use Unveel API to refresh token
• onError - called when SDK displays error to a user, for more details check SDK Error codes referece

How to use

HTML/VanillaJS

<head>
    <!-- ... -->
    <script src="https://sdk.unveel.io/sdk.js"></script>
    <!-- ... -->
</head>
<body>
<!-- ... -->
<div id="root">
    <div id="mount-element"></div>
</div>
<script>
    window.Unveel.start({
        htmlElement: document.getElementById('mount-element'),
        sandbox: true,
        pluginKey: 'plugin_key',
        hideClose: false,
        language: 'en',
        country: 'US',
        features: ['scan'],
        close: () => {
            window.Unveel.destroy();
        },
        accountConnected: (userId, accountId) => {
            /* Handle account connection */
        },
        accountCreated: (userId, accountId) => {
            /* Handle account creation */
        },
        accountRemoved: (userId, accountId) => {
            /* Handle account removal */
        },
        tokenExpired: (userId) => {
            /* Handle token expiration */
        },
        userCreated: (userId, jwtToken) => {
            /* Handle user creation */
        }
        onError: (error) => {
          /* Handle user error */
        }
    });
</script>
<!-- ... -->
</body>

React

Easiest way to use SDK with React is to add SDK script to page head section and run SDK from inside of React component.

<head>
    <!-- ... -->
    <script src="https://sdk.unveel.io/sdk.js"></script>
    <!-- ... -->
</head>

import React, { useRef, useEffect } from "react";

export const UnveelConnect = () => {
  const unveelFormElement = useRef(null);
  useEffect(() => {
    window.Unveel.start({
      htmlElement: unveelFormElement.current,
      sandbox: true,
      pluginKey: "plugin_key",
      hideClose: false,
      close: () => {
        window.Unveel.destroy();
      },
      accountConnected: (userId, accountId) => {
        /* Handle account connection */
      },
      accountCreated: (userId, accountId) => {
        /* Handle account creation */
      },
      accountRemoved: (userId, accountId) => {
        /* Handle account removal */
      },
      tokenExpired: (userId) => {
        /* Handle token expiration */
      },
      userCreated: (userId, jwtToken) => {
        /* Handle user creation */
      },
    });
    return () => {
      window.Unveel.destroy();
    };
  }, []);

  return <div id="unveel-sdk" ref={unveelFormElement} />;
};

React Native

Because SDK is using iframe element, it has to be run inside WebView. Below we are presenting example HTML code for WebView to use in React Native application.

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1, maximum-scale=1, user-scalable=no">
    <script src="https://sdk.unveel.io/sdk.js"></script>
    <title>Integration test</title>
    <style>
        body {
            margin: 0;
        }
        #root {
            width: 100%;
            height: 100vh;
            display: flex;
            justify-content: center;
            align-content: center;
        }
        #sdk-mount-element {
            flex-grow: 1;
        }
        iframe {
            border: none;
            width: 100%;
            height: 100%;
        }
    </style>
</head>
<body>
<div id="root">
    <div id="sdk-mount-element"></div>
</div>
<script>
try {
    window.Unveel.start({
        // ... Rest of SDK parameters
        accountConnected: (userId, accountId) => {
          // Connecting to WebView events
          window.ReactNativeWebView.postMessage(JSON.stringify({
            message: 'accountConnected',
            data: {userId, accountId}
          }));
        },
        // ...
    });
} catch (e) {
  document.getElementById('error').innerHTML = e.message;
}
</script>
</body>
</html>

Initialize single integration

In this mode SDK will omit initial integration select list and redirect user to desired integration. This way user path can be shortened. To enable this mode pass single partner id in partners parameter.

    window.Unveel.start({
        // ... Rest of SDK parameters
        partners: ['uber'],
        // ...
    });

In the Unveel SDK users are identified by JWT Tokens. When the Unveel SDK component is initialized without JWT token, new user is created and userCreated callback is called. As a parameters, you will receive user id and JWT Token. You should store those values in your database, and pass token next time user interacts with the component. Tokens expire after 30 days of its creation.

Structure

Each token is in a form of JWT Token. Payload:

{
    "sub": "user id",
    "iss": "your client id",
    "exp": "timestamp when token will expire"
}

Each Token is signed with RS256 algorithm.

Verification

In your onboarding you were provided with public key that can be used to verify token. In order to do it you can use one of the libraries listed here

Expired tokens

When expired token is passed to the component or token expire while user interacts with component the tokenExpired callback is called, and you are responsible for refreshing it by making a call to refresh user token endpoint from backend of your application. You can refresh tokens every time users starts interacting with the Unveel SDK component.

On sandbox you can use following test data:

• username: test@unveel.io or +48555123456
• password: password1
• code: 1234
• phone number: +48555123456
• security question: What is your favourite color? blue

If you want to have static hashedExternalId for each partner and user combination please yes those credentials:

• username: test-static@unveel.io or +48555123458
• password: password1
• code: 1234
• phone number: +48555123456
• security question: What is your favourite color? blue

Errors in onError callback are objects containing key and message:

• key - is a unique value used to determine error. It is optional value if key is missing this means that unknown error occurred.
• message - Description of error

Example:

{
  "key": "apiErrors.authentication.credentialsRevoked",
  "message": "Your credentials were revoked please provide them again"
}

List of error codes:

• apiErrors.authentication.generic - Unknown authentication error.
• apiErrors.authentication.credentialsRevoked - Credentials of the user were revoked and need to be updated.
• apiErrors.authentication.invalidCredentials - User used invalid credentials
• apiErrors.authentication.passwordResetRequired - User need to reset password first
• apiErrors.authentication.unsupportedMfaOption - User used unsupported MFA option
• apiErrors.authentication.userAlreadyRegistered - User tried to create account which already exists
• apiErrors.authentication.tooManyAttempts - User performed too many login attempts
• apiErrors.authentication.incorrectSMSPasscode - User used invalid SMS code

By API

In order to change payment account by our API send a request to the endpoint providing all necessary details described in Account details section. The request is handled asynchronously, which means that actual change will happen after you receive a response. In the response, you will receive requestId which you can use to get the current status by passing it to the endpoint. There are 4 different statuses:

• init - request was accepted by our system and it is waiting for processing
• processed - the process of changing payment account is in progress
• succeed - the process was finished with success
• failed - Unveel failed to change the payment account
• client-action-required - the process is on the client side

You can also register a webhook payment-account-changed or payment-account-change-failed which will be sent to you when the process is finished.

By SDK

To change payment account by our SDK first you have to encrypt account details by using endpoint. All necessary details are described in Account details section. Encryption is required to never expose account details on the SDK. The next step is to pass the encrypted request as the accountRequest option in the SDK. After use will successfully authenticate for the partner, Unveel will change payment account details. If you want to be notified about the status of the process you can register webhooks payment-account-changed or payment-account-change-failed which will be sent to you when the process is finished.

Each country and partner requires different account details to be provided.

Uber UK

{
  "beneficiary": {
    "name": "Name of the beneficiary",
    "city": "City of the beneficiary",
    "address": "Other details about address including street and street number",
    "postCode": "Postal code",
    "dateOfBirth": "Date of birth of the beneficiary"
  },
  "bank": {
    "iban": "Account number in IBAN format",
    "swift": "Optional swift code of the bank"
  }
}

After each scan, we are verifying if the account in the partner platform is equal to the account number changed by your request. You can register for payment-account-verification-failed webhook to be informed every time we detect the account number changed. If we fail to perform a scan, an account verification process will not be triggered and we won't be able to detect if the account number was not changed.