Verity API connection

The Verity API allows for standard data push on a dedicated API using a pre-defined data structure. This option has the advantage not to require the implementation of a dedicated data mapper on the Verity side but implies that formatting is applied on the client side to match the Verity standard format.

Verity also allows for custom data push. The mechanism consists in a standard API POST using a dedicated GUID identifier linked to a custom data mapper to a pre-defined Insights data source type.

The API is available on api.opinum.com.

Authentication principles

For the authentication, you will need a client_id and client_secret. You will also need to configure an specific user with Data Pusher access rights.

To push data in a custom format, you will also need a dedicated GUID.

Both the GUID and the client_id/client_secret are provided by Verity upon request. The user is to be created by a manager of your account.

The Verity Insights structure must exist before the data is sent to our API. Every data sent before the creation of Verity Insights cannot be mapped and will be lost. This structure consists of three elements :

• Site
• Source
• Variable

Request token

The Verity Authentication mechanism uses the OAuth2 standard.

The bearer token must be requested using :

• The client_secret and client_id provided by Verity.
• The user credentials

Tip

Contact Verity support to request your client_secret and client_id at support@opinum.com.

This bearer token will be used in every call to the API.

Note that every call also needs the scope information to provide access to the right feature of the API: It is as such mandatory to add in the header of you call, the following information: scope=["datahub-api","push-data"]

• datahub-api = access to the API (api.opinum.com)
• push-data = access to the push endpoint (push.opinum.com)

The token url is https://auth.opinum.com/realms/opinum/protocol/openid-connect/token

Here is a code sample to request this token in command line :

curl --location 'https://auth.opinum.com/realms/opinum/protocol/openid-connect/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=password' \
--data-urlencode 'client_id=MyClientId' \
--data-urlencode 'client_secret=MyClientSecret' \
--data-urlencode 'scope=datahub-api' \
--data-urlencode 'username=MyUsername' \
--data-urlencode 'password=MyPassword' \
--data-urlencode 'account=123'

And another example in Python 3.x using OAuthlib and Requests-OAuthlib packages:

from oauthlib.oauth2 import LegacyApplicationClient
from requests_oauthlib import OAuth2Session

def get_datahub_token(datahub_username: str, datahub_password: str):
    """" Get token from DataHub API """
    datahub_client = LegacyApplicationClient(client_id="your_client_id")
    oauth = OAuth2Session(client=datahub_client)
    datahub_token = oauth.fetch_token(token_url="https://auth.opinum.com/realms/opinum/protocol/openid-connect/token",
                                       client_secret="your_client_secret",
                                       scope=["datahub-api","push-data"],
                                       username=datahub_username,
                                       password=datahub_password,
                                       client_id="your_client_id")
    return "Bearer " + datahub_token["access_token"]

Data push principles

There is two ways to push data through Verity API :

1. Using the standard: you map the data to make it fit in Verity standard format
2. Using a custom format: you push you raw data and the mapping is made by Verity

Tip

Learn more about the standard format

Tip

Learn more about the custom format

Test the API with Swagger

You can visualize and interact with the API thanks to Swagger UI.

• Login to Insights with the user that will use the API
• Go on Verity Swagger UI.
• Click on the button Authorize at the right of the page.
• The connection pop-up opens. Check the check box datahub-api and click on the Authorize button.
• The confirmation pop-up opens. Click on the Close button.
• You are now connected to Swagger and can enjoy the Verity API.
• To log out, click on the Authorize button again, the connection pop-up opens. Then click on the Logout button.

Tip

Learn more about every entry points of the API on the Swagger UI (https://api.opinum.com/swagger/index.html).