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.
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.
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
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):
{- "type": "BaseError",
- "message": "string",
- "details": {
- "description": "string",
- "docs": "string"
}
}
Record Error:
{- "type": "BaseError",
- "record": {
- "base": [
- "string"
], - "property1": [
- "string"
], - "property2": [
- "string"
]
}, - "message": "string",
- "details": {
- "description": "string",
- "docs": "string"
}
}
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.
Response samples
- 200
{- "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
}
}
]
}
}
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
|
Responses
Request samples
- Payload
{- "dashboard_filter_conditions": [
- {
- "dynamic_filter_id": 0,
- "condition": {
- "operator": "string",
- "values": [
- "string"
]
}
}
]
}
Response samples
- 200
{- "job": {
- "id": 0,
- "status": "created"
}
}
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
- 200
- 401
{- "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",
- "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:
Request Body schema: application/json
required | object (DataSchedule) | ||||||||||||
|
Responses
Request samples
- Payload
{- "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}}",
- "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
{- "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",
- "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
- 403
- 404
{- "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",
- "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:
path Parameters
id required | integer Resource id |
Request Body schema: application/json
required | object (DataSchedule) | ||||||||||||
|
Responses
Request samples
- Payload
{- "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",
- "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
{- "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",
- "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"
}
}
}