Breadcrumbs

Read a dashboard's data

A dashboard is a predefined set of figures — documents by state, transactions per user, consumption over time. The API hands them over as plain numbers, ready to plot in whatever your own interface uses. This guide lists them and runs two, in three calls.

Before you begin

  • A key that belongs to an account inside an organization. A dashboard counts the whole organization's activity, so running one with an account that sits in no organization is refused with 403.

Step 1: List the dashboards you can run

Start with what is available to you:

GET /dashboards
Authorization: Bearer YOUR_API_KEY

HTTP/2 200

{
    "pagination": null,
    "results": [
        {
            "name": "trans_status"
        },
        {
            "name": "trans_success_per_date"
        },
        {
            "name": "trans_per_date"
        },
        {
            "name": "docs_per_user"
        },
        {
            "name": "trans_consumption"
        },
        {
            "name": "trans_per_user"
        },
        {
            "name": "docs_consumption"
        },
        {
            "name": "docs_per_state"
        },
        {
            "name": "trans_per_avg"
        }
    ],
    "total": 9
}

Each entry is an identifier, and that identifier is what you run. The available dashboards are part of the instance's configuration, so the list can differ between installations and can be empty. Read it rather than hard-coding names into your integration.

The collection is small and bounded, which is why it arrives whole with pagination: null instead of a page.

Step 2: Run a dashboard

Running one computes it and returns its figures:

GET /dashboards/docs_per_state
Authorization: Bearer YOUR_API_KEY

HTTP/2 200

{
    "name": "docs_per_state",
    "series": [
        {
            "label": "inactive",
            "points": [
                {
                    "label": "inactive",
                    "value": 2
                }
            ]
        },
        {
            "label": "inprogress",
            "points": [
                {
                    "label": "inprogress",
                    "value": 0
                }
            ]
        },
        {
            "label": "completed",
            "points": [
                {
                    "label": "completed",
                    "value": 1
                }
            ]
        }
    ],
    ...
}

The answer is always the same two levels. A series is one labeled dataset — here one per document state, with the rest of the states following the same way. Its points are the values of that dataset, one per category, each with a label to put on the axis and a numeric value to plot. That is the whole contract: hand series to a charting library and you have a chart.

This dashboard counts documents rather than breaking them down by anything, so each of its series holds a single point named after the series itself. inactive counts the two documents whose transaction has not started, and completed the one that has been signed.

Labels are meant for display, and they come from the dashboard's own definition rather than from the API's vocabulary — the states counted here are not the transaction statuses of Signing & Approvals, even where the two read alike. Identify a dashboard by its name, and treat every label as text to put on a chart rather than as a value to branch on.

Step 3: Run a dashboard that breaks its figures down

A dashboard with a category axis fills in the points, and nothing else about the shape changes:

GET /dashboards/docs_per_user
Authorization: Bearer YOUR_API_KEY

HTTP/2 200

{
    "name": "docs_per_user",
    "series": [
        {
            "label": "total_created",
            "points": [
                {
                    "label": "Emma Wilson",
                    "value": 3
                }
            ]
        },
        {
            "label": "inactive",
            "points": [
                {
                    "label": "Emma Wilson",
                    "value": 2
                }
            ]
        },
        {
            "label": "transactions",
            "points": [
                {
                    "label": "Emma Wilson",
                    "value": 1
                }
            ]
        }
    ],
    ...
}

Here every series is a measure — how many documents the person created, how many are sitting untouched, how many went into a transaction — and the points name the people. A second colleague would add a second point to each series, not a second series.

Because the shape never varies, one piece of code renders every dashboard, including any that appear after your integration ships.

Complete example

Refreshing every dashboard your account can run, as a Node.js script. Error handling is minimal for brevity — in production, inspect the error envelope of non-2xx responses.

JavaScript
const BASE_URL = "https://sandbox.circularo.com/api/v1/public"; // your instance's base URL
const API_KEY = "YOUR_API_KEY";
const AUTH_HEADER = { "Authorization": `Bearer ${API_KEY}` };

const listed = await fetch(`${BASE_URL}/dashboards`, { headers: AUTH_HEADER });
if (!listed.ok) throw new Error(`Listing failed: ${listed.status}`); // error handling kept minimal for brevity

const charts = {};
for (const { name } of (await listed.json()).results) {
    const res = await fetch(`${BASE_URL}/dashboards/${name}`, { headers: AUTH_HEADER });
    if (!res.ok) continue; // a dashboard withdrawn between the two calls answers 404

    const dashboard = await res.json();
    charts[dashboard.name] = dashboard.series.map((series) => ({
        name: series.label,
        data: series.points.map((point) => ({ x: point.label, y: point.value }))
    }));
}

console.log(`${Object.keys(charts).length} dashboards refreshed`);

Next steps