Skip to main content

Holistics API (2.0)

Download OpenAPI specification:Download

Holistics Support: [email protected]

Introduction

Using these APIs, you are able to programmatically work with Holistics. For example:

  • You can programmatically retrieve CSV, XLSX and JSON data from any Holistics report.
  • You can use our API to trigger execution of an data schedule, transform or data import. etc...

This is useful especially if you need to pass live data to your other applications. For example, you may want to feed a live CSV endpoint of your user segmentation list into your email marketing application so that you can always get fresh data upon retrieving them.

NOTE: Please note that Holistics API version does not correlate with Holistics feature version. For example, Holistics API v2 can support operations on all Holistics 2.0, 2.7 and 3.0.

Authentication

ApiKeyAuthentication

Security Scheme Type API Key
Header parameter name: X-Holistics-Key

Allow user API access

In order for a user to use API key, they must be allowed to use API access in User Management. Edit the User and tick the checkbox Allow API access:

API Key

The allowed user can then visit user settings and generate a new API key.

Retrieve API key

Then you can set the API key in the request header when calling our APIs.

API Request Authorization

Set the custom X-Holistics-Key header to your API key. Example:

curl -X POST \
  -H "Accept:application/json" \
  -H "Content-Type:application/json" \
  -H "X-Holistics-Key:api_key" \
  https://secure.holistics.io/api/v2/data_schedules/1/execute.yml

Errors

HTTP Code Description
200 - OK Everything worked as expected.
400 - Bad Request The request was unacceptable due to missing request parameter or wrong request structure.
401 - Unauthorized No valid API key provided.
403 - Forbidden The API Key owner does not have permission to perform the request.
404 - Not Found The requested resource does not exist or cannot found.
422 - Unprocessable Entity Cannot process the request parameter due to semantic errors. See the message for more detail.
429 - Too Many Requests Too many requests were sent.
500 - Internal Holistics Error Something went wrong on Holistics side (rarely).
Error type Description
BaseError Base schema for all types of errors.
RecordError Error when saving a record.
InvalidParameterError One or more parameters are missing or do not satisfy the endpoint's requirements.
AuthError Could not authorize current user, typically due to missing or expired authentication token.
MaintenanceError Your admins has set Holistics to Maintenance mode
TrialExpiredError Your Holistics trial has expired
PermissionDeniedError The API Key owner does not have permission to access a resource.
InternalHolisticsError Internal Holistics error. Please provide us the debug id in error message so we can investigate further.

Base Error (All errors inherit from this):

object _BaseError Recursive
{
  • "type": "BaseError",
  • "message": "string",
  • "details": {
    }
}

Record Error:

object _RecordError Recursive
{
  • "type": "BaseError",
  • "record": {
    },
  • "message": "string",
  • "details": {
    }
}

Jobs

Async (asynchronous) operations are operations that are executed within a background Job.
If an API endpoint triggers an async operation, it will return an AsyncResult response containing the background Job info.
You can use the bellow APIs to poll for the updated Job status.

Get a Job

Authorizations:
path Parameters
id
required
integer

Resource id

Responses

Response samples

Content type
application/json
{
  • "job": {
    }
}

Get a Job's logs

Authorizations:
path Parameters
id
required
integer

Resource id

Responses

Response samples

Content type
application/json
{
  • "job_logs": [
    ]
}

Dashboards

Reporting Dashboards

Get a Dashboard

Authorizations:
path Parameters
id
required
integer

Resource id

Responses

Response samples

Content type
application/json
{
  • "dashboard": {
    }
}

Dashboard Widgets

Reporting Dashboard Widgets

Export a Dashboard Widget

When the Job is finished, you can download the exported file using this API.

Authorizations:
path Parameters
id
required
integer

Resource id

query Parameters
output
required
string
Enum: "csv" "xlsx"

Output file type

Request Body schema: application/json
Array of objects (DynamicFilterCondition) [ items ]
Array
dynamic_filter_id
required
integer
required
object (DataModelingCondition)

Condition that can be applied on the Data Modeling layer to filter your data.

Examples

Responses

Request samples

Content type
application/json
{
  • "dashboard_filter_conditions": [
    ]
}

Response samples

Content type
application/json
{
  • "job": {
    }
}

Data Schedules

Data delivery using automated schedules

List Data Schedules

Authorizations:
query Parameters
before
string

Only get records before this cursor.

after
string

Only get records after this cursor.

limit
integer [ 1 .. 100 ]
Default: 20

Limit number of records per page

dest_type
string
Enum: "EmailDest" "SlackDest" "Adls2Dest" "SftpDest"

Filter by destination type

source_type
string
Enum: "QueryReport" "Dashboard"

Filter by source type

source_id
integer

Filter by source id

Responses

Response samples

Content type
application/json
{
  • "data_schedules": [
    ],
  • "cursors": {
    }
}

Create Data Schedule

Authorizations:
Request Body schema: application/json
required
object (DataSchedule)
id
integer

Unique data schedule identifier

source_type
required
string
Enum: "Dashboard" "QueryReport"
source_id
required
integer
required
object (Schedule)
Array of objects (DynamicFilterPreset) [ items ]
required
object

Responses

Request samples

Content type
application/json
Example
{
  • "data_schedule": {
    }
}

Response samples

Content type
application/json
{
  • "data_schedule": {
    }
}

Get a Data Schedule

Authorizations:
path Parameters
id
required
integer

Resource id

Responses

Response samples

Content type
application/json
{
  • "data_schedule": {
    }
}

Update a Data Schedule

Authorizations:
path Parameters
id
required
integer

Resource id

Request Body schema: application/json
required
object (DataSchedule)
id
integer

Unique data schedule identifier

source_type
required
string
Enum: "Dashboard" "QueryReport"
source_id
required
integer
required
object (Schedule)
Array of objects (DynamicFilterPreset) [ items ]
required
object

Responses

Request samples

Content type
application/json
{
  • "data_schedule": {
    }
}

Response samples

Content type
application/json
{
  • "data_schedule": {
    }
}

Delete a Data Schedule

Authorizations:
path Parameters
id
required
integer

Resource id

Responses

Execute a Data Schedule

Authorizations:
path Parameters
id
required
integer

Resource id

Responses

Response samples

Content type
application/json
{
  • "job": {
    }
}

Exports

Download an exported file

Authorizations:
query Parameters
job_id
required
integer

ID of the Job that has done the exporting

Responses

Response samples

Content type
application/json
{
  • "type": "BaseError",
  • "message": "string",
  • "details": {
    }
}

Data Modeling

DataModelingCondition

Condition that can be applied on the Data Modeling layer to filter your data. See the examples in the Example panel.

object DataModelingCondition Recursive
{
  • "operator": "string",
  • "values": [
    ]
}