February 8, 2023

Introducing tru.ID's Analytics API

Greg Holmes
Developer Advocate
Curious?

Discover how SIM-based authentication can help you with a free 30 min consultation

Follow us on

What is the Analytics API?

The Analytics API is a new feature released by tru.ID. This feature has been created to allow those with access to the tru.ID Workspace to export analytics and reporting data directly.

tru.ID APIs confirm the ownership of a mobile phone number by verifying the possession of an active SIM card with the same number, working as proof of possession for multi-factor authentication (MFA).

The new Analytics API primarily provides data to determine the rate of successful and failed checks.

Where can I see the API in action?

The Analytics API has been implemented into your Developer Console for ease of access if you do not wish to make use of the API itself. However, all functionality shown in the Developer Console and more is available to you with the API.

Below is an example of the Analytics API integrated into your Developer Console. This allows those with access to the workspace to see statistics on the Product of their choice (PhoneCheck, SubscriberCheck, or SIMCheck), with the layout of their choice (Hourly, Daily, or Monthly), and over the time period of their choice.

Below the Analytics graph in the Developer Console, you’ll find a table outputting a little more information on the breakdown of the statistics of the PhoneCheck. This is grouped by Project, and outputs one of 4 possible results for each project:

  • COMPLETED (Phone number is a match)
  • COMPLETED (Phone number is not a match)
  • EXPIRED (The unique check URL was triggered but never completed)
  • ERROR (This could be because the Mobile Network Operator (MNO) is not supported, or the device is not on a mobile IP address)

An example of API results

How can I use the API?

The Analytics API can be found under the API specifications within the tru.ID Developer Documentation Portal.

There are three separate endpoints for this API. Each endpoint has the same parameters available to them. The last part of the endpoint URL specifies which one you wish to use:

  • Hourly (`/hourly`)
  • Daily (`/daily`)
  • Monthly (`/monthly`)

An example Analytics request is shown in the URL below. This checks for monthly Analytics on PhoneCheck (`pck`), where `match` is true, and the results are grouped by `project_id`.

https://{DATA_RESIDENCY}.api.tru.id/console/v0.2/workspaces/{YOUR_WORKSPACE_ID}/analytics/pck/monthly?search=match%3E%3Dtrue&group_by=project_id

{
    "_embedded": {
        "analytics": [
            {
                "product_id": "PCK",
                "workspace_id": "{WORKSPACE_ID}",
                "project_id": "{PROJECT_ID}",
                "status": "COMPLETED",
                "match": true,
                "counter": 2,
                "date": "2023-01"
            },
            {
                "product_id": "PCK",
                "workspace_id": "{WORKSPACE_ID}",
                "project_id": "{PROJECT_ID}",
                "status": "COMPLETED",
                "match": true,
                "counter": 7,
                "date": "2023-01"
            },
            {
                "product_id": "PCK",
                "workspace_id": "{WORKSPACE_ID}",
                "project_id": "{PROJECT_ID}",
                "status": "COMPLETED",
                "match": true,
                "counter": 2,
                "date": "2023-01"
            },
            {
                "product_id": "PCK",
                "workspace_id": "{WORKSPACE_ID}",
                "project_id": "{PROJECT_ID}",
                "status": "COMPLETED",
                "match": true,
                "counter": 1,
                "date": "2022-12"
            },
        ]
    },
    "_links": {
        "self": {
            "href": "https://{DATA_RESIDENCY}.api.tru.id/console/v0.2/workspaces/{WORKSPACE_ID}/analytics/pck/monthly?search=match%3E=true&group_by=project_id&page=1&size=20&sort=date,desc"
        }
    },
    "page": {
        "size": 20,
        "total_elements": 4,
        "total_pages": 1,
        "number": 1
    }
}

Accessing Analytics API via CLI

The Analytics API can be also accessed from the tru.ID Command Line Interface. The detailed overview can be found under the Command Line Interface (CLI) Reference within the tru.ID Developer Documentation Portal.

Similarly to the API, to access the analytics data, there are two parameters — a product and a time bucket — that need to be specified after the `analytics:` command’s prefix:

tru analytics:PRODUCT:TIME-BUCKET

where

  • PRODUCT = `pck | sck |suk`
  • TIME-BUCKET = `hourly | daily | monthly`

An example of accessing analytics from the tru.ID CLI is shown in the command below. This checks for monthly Analytics on PhoneCheck (`pck`), where `match` is true, and the results are grouped by `project_id`.

tru analytics:pck:monthly --search='match==true' --group-by=project_id

product_id workspace_id   project_id   status    match counter date
────────── ────────────── ──────────── ───────── ───── ─────── ───────
PCK        {WORKSPACE_ID} {PROJECT_ID} COMPLETED true  2       2023-01
PCK        {WORKSPACE_ID} {PROJECT_ID} COMPLETED true  7       2023-01
PCK        {WORKSPACE_ID} {PROJECT_ID} COMPLETED true  2       2023-01
PCK        {WORKSPACE_ID} {PROJECT_ID} COMPLETED true  1       2022-12

That’s all you need to know to get started with the Analytics API and start analysing your tru.ID data effectively.

If you have any questions, feel free to contact help@tru.id or get involved in our dedicated Slack group.