Holistics API (2.0)

Download OpenAPI specification:Download

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": {"description": "string",
"docs": "string"
}
}

Record Error:

object _RecordError Recursive

{"type": "BaseError",
"record": {"base": ["string"
],
"property1": ["string"
],
"property2": ["string"
]
},
"message": "string",
"details": {"description": "string",
"docs": "string"
}
}

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:

ApiKeyAuthentication

path Parameters

id

required

integer

Resource id

Responses

Response samples

200

Content type

application/json

{"job": {"id": 0,
"user_id": 0,
"start_time": "string",
"end_time": "string",
"cancellable": true,
"status": "created"
}
}

Get a Job's logs

Authorizations:

ApiKeyAuthentication

path Parameters

id

required

integer

Resource id

Responses

Response samples

200

Content type

application/json

{"job_logs": [{"level": "ERROR",
"message": "string",
"timestamp": "2019-08-24T14:15:22Z"
}
]
}

Dashboards

Reporting Dashboards

Get a Dashboard

Authorizations:

ApiKeyAuthentication

path Parameters

id

required

integer

Resource id

Responses

Response samples

200

Content type

application/json

{"dashboard": {"id": 0,
"title": "string",
"category_id": 0,
"version": 1,
"dynamic_filters": [{"id": 0,
"order": 0,
"uname": "string",
"permissions": {"read": true,
"crud": true,
"use": true
},
"definition": {"id": 0,
"label": "string",
"default_condition": {"operator": "string",
"values": ["string"
]
},
"filter_type": "number",
"is_sharable": true,
"filter_source": {"manual_options": [{"value": "string"
}
],
"source_type": "ManualFilterSource"
}
},
"drillthrough_enabled": true,
"mappings": [{"id": 0,
"viz_conditionable_id": 0,
"viz_conditionable_type": "DashboardWidget",
"field_path": {"field_name": "string",
"model_id": 0,
"data_set_id": 0
},
"aggregation": "string",
"permissions": {"crud": true
}
}
]
}
],
"widgets": [{"id": 0,
"source_id": 0,
"source_type": "QueryReport",
"source_title": "string",
"permissions": {"explore": true,
"export": true,
"export_data": true
}
}
]
}
}

Dashboard Widgets

Reporting Dashboard Widgets

Export a Dashboard Widget

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

Authorizations:

ApiKeyAuthentication

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

Payload

Content type

application/json

{"dashboard_filter_conditions": [{"dynamic_filter_id": 0,
"condition": {"operator": "string",
"values": ["string"
]
}
}
]
}

Response samples

200

Content type

application/json

{"job": {"id": 0,
"status": "created"
}
}

Data Schedules

Data delivery using automated schedules

List Data Schedules

Authorizations:

ApiKeyAuthentication

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

200
401

Content type

application/json

{"data_schedules": [{"id": 0,
"source_type": "Dashboard",
"source_id": 0,
"schedule": {"repeat": "string",
"paused": true
},
"dynamic_filter_presets": [{"id": 0,
"dynamic_filter_id": 0,
"preset_condition": {"operator": "string",
"values": ["string"
]
},
"public_hidden": false
}
],
"dest": {"title": "string",
"recipients": ["[email protected]"
],
"options": {"preview": true,
"include_header": true,
"include_report_link": true,
"include_filters": true,
"dont_send_when_empty": true,
"body_text": "string",
"attachment_formats": ["csv"
]
},
"type": "EmailDest"
}
}
],
"cursors": {"previous": "string",
"next": "string"
}
}

Create Data Schedule

Authorizations:

ApiKeyAuthentication

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

Payload

Content type

application/json

Example

{"data_schedule": {"id": 1,
"source_type": "Dashboard",
"source_id": 1,
"schedule": {"repeat": "* * * * *",
"paused": false
},
"dynamic_filter_presets": [{"id": 1,
"dynamic_filter_id": 1,
"public_hidden": true,
"preset_condition": {"modifier": null,
"operator": "is",
"values": ["alice"
]
}
}
],
"dest": {"type": "EmailDest",
"title": "Sale report for {{$today}}",
"recipients": ["[email protected]",
"[email protected]"
],
"options": {"preview": true,
"include_header": true,
"include_report_link": true,
"include_filters": false,
"dont_send_when_empty": true,
"body_text": "Report",
"attachment_formats": ["pdf",
"csv"
]
}
}
}
}

Response samples

201
403
422

Content type

application/json

{"data_schedule": {"id": 0,
"source_type": "Dashboard",
"source_id": 0,
"schedule": {"repeat": "string",
"paused": true
},
"dynamic_filter_presets": [{"id": 0,
"dynamic_filter_id": 0,
"preset_condition": {"operator": "string",
"values": ["string"
]
},
"public_hidden": false
}
],
"dest": {"title": "string",
"recipients": ["[email protected]"
],
"options": {"preview": true,
"include_header": true,
"include_report_link": true,
"include_filters": true,
"dont_send_when_empty": true,
"body_text": "string",
"attachment_formats": ["csv"
]
},
"type": "EmailDest"
}
}
}

Get a Data Schedule

Authorizations:

ApiKeyAuthentication

path Parameters

id

required

integer

Resource id

Responses

Response samples

200
403
404

Content type

application/json

{"data_schedule": {"id": 0,
"source_type": "Dashboard",
"source_id": 0,
"schedule": {"repeat": "string",
"paused": true
},
"dynamic_filter_presets": [{"id": 0,
"dynamic_filter_id": 0,
"preset_condition": {"operator": "string",
"values": ["string"
]
},
"public_hidden": false
}
],
"dest": {"title": "string",
"recipients": ["[email protected]"
],
"options": {"preview": true,
"include_header": true,
"include_report_link": true,
"include_filters": true,
"dont_send_when_empty": true,
"body_text": "string",
"attachment_formats": ["csv"
]
},
"type": "EmailDest"
}
}
}

Update a Data Schedule

Authorizations:

ApiKeyAuthentication

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

Payload

Content type

application/json

{"data_schedule": {"id": 0,
"source_type": "Dashboard",
"source_id": 0,
"schedule": {"repeat": "string",
"paused": true
},
"dynamic_filter_presets": [{"id": 0,
"dynamic_filter_id": 0,
"preset_condition": {"operator": "string",
"values": ["string"
]
},
"public_hidden": false
}
],
"dest": {"title": "string",
"recipients": ["[email protected]"
],
"options": {"preview": true,
"include_header": true,
"include_report_link": true,
"include_filters": true,
"dont_send_when_empty": true,
"body_text": "string",
"attachment_formats": ["csv"
]
},
"type": "EmailDest"
}
}
}

Response samples

200

Content type

application/json

{"data_schedule": {"id": 0,
"source_type": "Dashboard",
"source_id": 0,
"schedule": {"repeat": "string",
"paused": true
},
"dynamic_filter_presets": [{"id": 0,
"dynamic_filter_id": 0,
"preset_condition": {"operator": "string",
"values": ["string"
]
},
"public_hidden": false
}
],
"dest": {"title": "string",
"recipients": ["[email protected]"
],
"options": {"preview": true,
"include_header": true,
"include_report_link": true,
"include_filters": true,
"dont_send_when_empty": true,
"body_text": "string",
"attachment_formats": ["csv"
]
},
"type": "EmailDest"
}
}
}

Delete a Data Schedule

Authorizations:

ApiKeyAuthentication

path Parameters

id

required

integer

Resource id

Responses

Execute a Data Schedule

Authorizations:

ApiKeyAuthentication

path Parameters

id

required

integer

Resource id

Responses

Response samples

200

Content type

application/json

{"job": {"id": 0,
"status": "created"
}
}

Exports

Download an exported file

Authorizations:

ApiKeyAuthentication

query Parameters

job_id

required

integer

ID of the Job that has done the exporting

Responses

Response samples

422

Content type

application/json

{"type": "BaseError",
"message": "string",
"details": {"description": "string",
"docs": "string"
}
}

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": ["string"
]
}