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

• You can programmatically retrieve CSV, XLSX, etc. 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.

API data is limited to specific regions. For example, if your want to access data from the US region, you need to use the subdomain https://us.holistics.io. Below is the API subdomain corresponding with data center's region.

Region	URL
Asia-Pacific (APAC)	https://secure.holistics.io/api/v2
Europe (EU)	https://eu.holistics.io/api/v2
United States (US)	https://us.holistics.io/api/v2

If you do not know which data center your Holistics' account is currently on, check out this docs.

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
SubscriptionError	The subscription of the tenant does not have permission to access the resource.
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.
InvalidOperationError	Can not process your action due to system constraints.

Base Error (All errors inherit from this):

Record Error:

To prevent DDoS attacks, every API request should go through our rate limit layer which will throttle the request if a user exceeds limit quotas. The rate limit is based on user and endpoint, quotas (per time frame) which maybe different for each endpoint are divided by levels as the table below:

Level	Quota	Note
Level 1	120	At least every API request is this level
Level 2	60	Request requires a lot of resource
Level 3	20	Request that heavily affect our server's resources

If a request is blocked because of it exceed the limit quota, status code is set to 429: Too Many Requests

Every API request returns header contains the following fields:

RateLimit-Limit: your_limit_quota_of_endpoint
RateLimit-Remaining: remaining_requests_until_reset
RateLimit-Reset: next_reset_time
Retry-After: next_reset_time(only available when status code is 429)

This short tutorial shows you how to use the Holistics APIs to get report data in raw tabular form (CSV, Excel).

This tutorial uses Ruby, but you can easily use any other language for it.

ⓘ INFO

We'll be working on client libraries wrapper around our API. Once done, using the APIs will be simpler by just making a few function calls.

Since Holistics uses a async job queuing system to process job, you can't make a single API call to retrieve the results. We need to submit an 'export request', then wait for the export job to finish, and then make an API call to download the results.

API Endpoints used:

• Export a Dashboard Widget
• Download an exported job

Let's go through the steps here.

1. Setting Up API Key

Please see guide to set up and retrieve your API key.

2. Initial code structure

To make things simple and reusable, we'll wrap our code around a HolisticsAPI class. We'll also use the httprb gem to handle making HTTP calls.

require 'http'
class HolisticsAPI
  def initialize(api_key, host: 'secure.holistics.io')
    @api_key = api_key
    @api_url = "https://#{host}/api/v2"
    @http = HTTP.headers({'X-Holistics-Key' => @api_key})
  end
end

3. (Optional) Get Filters ID for your Dashboard Export

If you want to include Filters in your export, you will need to get their Filter IDs. Please follow these steps to obtain them:

1. Get your Dashboard ID

The Dashboard ID can be retrieved by looking at its URL in the browser. In this sample URL below, the Dashboard ID would be 16076.

2. Get Filter ID

Supposed that your dashboard has a sets of filters like the one below. Let's get the ID of the Date filter to include it in our export.

We will use Get Dashboard API for this purpose. Let's call the API with the Dashboard ID from step 1.

curl --location --request GET 'https://secure.holistics.io/api/v2/dashboards/{your_dashboard_id}' \
--header 'X-Holistics-Key: your_API_key' \
--header 'Content-Type: application/json' \

The response would be quite lengthy, but you just need to find the dynamic_filters field to get the Filter ID.

You can then use this Filter ID in the next step.

4. Submit widget export request

Make sure you have the DashboardWidget ID in hand. The widget ID can be retrieved by opening up the widget in the dashboard, and look at the _e parameter in the URL. For example, 4175 is the widget ID of the below.

https://secure.holistics.io/dashboards/v3/12345-some-dashboard/?_e=4175

ⓘ INFO

(Optional) Include filter conditions in your export If you wish to include a filter condition in your export, first refer to step 3 to get your desired Filter ID.

Then, append dashboard_filter_conditions in your request body.

• dynamic_filter_id is the Filter ID from step 3.
• condition:
  • operator: refer to Data Modeling Condition for all available operators.
  • values: is an array of strings or integers that go with the operator.

For example, assuming that you have completed step 3, to apply a Date Filter that filters data from 2 months ago to the export, simply include this snippet to your request.

{
  "dashboard_filter_conditions": [
    {
      "dynamic_filter_id": 2335,
      "condition": {
        "operator": "matches",
        "values": [
          "2 months ago"
        ]
      }
    }
  ]
}

Then we make the call to submit widget export:

class HolisticsAPI
  # ...

  # output: 'csv' or 'excel'
  def submit_report(widget_id, output: 'csv')
    url = @api_url + "/dashboard_widgets/" + widget_id.to_s + "/submit_export"

    response = @http.post(url, json: {output: output})
    res = JSON.parse(response.to_s)

    if response.code == 200
      res['job']['id']
    else
      raise StandardError.new(res['message'])
    end
  end
end

If successful, this method returns the job ID of the job created.

5. Waiting for job to complete

The job will the go to the queue system waiting to be processed. This method below will continuously poll the job's metadata until it is either success, or failure.

class HolisticsAPI
  # ...

  def wait_for_job_status(job_id)
    url = @api_url + "/jobs/" + job_id.to_s

    while true do
      response = @http.get(url)
      res = JSON.parse(response.to_s)

      raise StandardError.new(res['message']) if response.code != 200

      status = res['job']['status']
      puts "===> status: #{status}"

      unless ['created', 'running', 'queued'].include?(status)
        return status
      end

      # Wait a while before pinging again
      sleep 2
    end
  end
end

6. Downloading the results

Once the job finishes, we make one final API call to

class HolisticsAPI
  # ...

  def download_export(job_id)
    url = @api_url + "/exports/download"
    response = @http.follow.get(url, params: {job_id: job_id})

    raise StandardError.new(JSON.parse(response.to_s['message'])) if response.code != 200

    response.to_s
  end
end

7. Putting things together

Once the above class is defined, let's put in a short code to perform all 3 steps to get the data.

API_KEY = 'your_api_key'
WIDGET_ID = 1234 # your widget

api = HolisticsAPI.new(API_KEY)

job_id = api.submit_report(WIDGET_ID)
puts "===> job_id: #{job_id}"

job_status = api.wait_for_job_status(job_id)
puts "===> job_status: #{job_status}"

if job_status == 'success'
  csv_data = api.download_export(job_id)
  puts csv_data # your CSV-formatted data here!
end

7. Profit!

Save the data into CSV, convert them into array, or feed them to other applications. The potentials are limitless!

---

In Holistics, you can set up a system that sends you automatic notifications when data meets certain criteria, allowing you to make timely and strategic business decisions. This concept is called as Data Alert.

Holistics offers a set of public API endpoints allowing clients to work with Data Alert. This tutorial shows you how to programmatically create these data alerts using the API.

---

Assuming you are an e-commerce company that wants to track the number and status of orders placed on your platform. You can set up data alerts that trigger notifications when certain conditions are met, such as:

1. A number of orders placed in a specific time period exceed a certain threshold.
2. A certain percentage of orders are canceled or marked as "canceled".

You can receive these alerts through email or slack, and they can use this information to quickly respond to any issues or to make informed decisions about adjusting inventory or shipping processes.

Let's walk through how we can create a data alert to track your number of orders using Holistics API.

---

We will use the API to create email data alerts. Specifically, we'll send a POST request to Holistics create data alert API.

Before that, we need to prepare the following:

• A dashboard widget with relevant report
• Holistics API Key: We need to setup the API key. Refer to this guide for more info.

---

Step 1. Preparing the dashboard widget

You will need to create a dashboard widget containing the data of interest to you. In this example, I used this simple report that counts the total number of orders.

Step 2: Making the API Call

We'll be using the following endpoint:

POST https://secure.holistics.io/api/v2/data_alerts

There are some notable configuration options in this request:

• schedule: Specify how frequently the email schedule should be
• viz_conditions: Specify what alert condition should be check on the report result. By configuring this, we can customize the alert for each alerting use case.
• dest: Specify configurations regarding the alert delivery destination, e.g. the recipients' information.
• dynamic_filter_presets: Specify what dynamic filters should be applied to the report. By configuring this, we can customize the report for each recipient.

Below is a sample request body. Refer to Holistics API docs for more information on these fields.

Dest field

• dest: Specify configurations regarding recipients' information
  • title (string): Note that Holistics support dynamic variables in email title. For example, the title Sales report for {{$today}} sent on 29/09/2021 will be rendered as Sales report for 2021-09-29 Wed.
  • type: This tells Holistics you want to receive notification via email: EmailDest or Slack: SlackDest
    • If you choose SlackDest, you will need to get the id and the name of your slack channel for the slack_channels field

Viz conditions

• viz_conditions: Coming to the core of the alert, the condition to set data alert

  • field_path: This is used to extract from a specific data model

    • field_name: field name of the field in the data model you want to apply the condition.
    • model_id: The id of the data model associated with the field_name
    • You can get the field_name and model_id by following these steps
      • From the widget id → Get a dashboard widget (include_report=true) then extract query_report.viz_settings.fields, you can find the field you want to add condition then extract path_hash to get model_id and field_name

  • aggregation: The aggregation that will be applied on the field when processing the condition.

  • transformation: The transformation that will be applied on the field when processing the condition.

  • condition: be applied on the Data Modeling layer to filter your data. Check out our document here for more details.

  • Example: you have a field id and want to check whether the number of it is greater than 35000

    {
      "field_path": {
        "field_name": "id",
        "model_id": 1
      },
      "aggregation": "count",
      "transformation": null,
      "condition": {
        "operator": "greater_than",
        "modifier": null,
        "values": [35000],
      },
    }
    

Schedule

schedule: This field is used to specify the schedule for your email schedule.

repeat (string): You will need to input a crontab expression to let Holistics know how frequently you want your email schedule to run.

Dashboard Filters

dynamic-filter-presets is where you define your filter presets.

dynamic_filter_id: To get your filter_id, send a request to Dashboards#Get API to get the dashboard info.

preset_conditions: Let's go through our example to better illustrate this field.

We want to set a value for the filter by setting a preset condition. A preset condition consists of an operator and a list of values. Holistics supports various operators and provides several examples here.

In this case, we want to use operator is and set values to customer_id. By this, we mean the filter's default value equals exactly to customer_id.

Finally, we also want to set up another dynamic filter preset to filter data to the whole of last week. Fortunately, Holistics allows a list of dynamic filter presets. For the Date Range filter, we similarly want to use operator is and set values to "last 7 days".

Our final dynamic_filter_presets object will look like this.

dynamic_filter_presets = [
  {
    "dynamic_filter_id": MY_CUSTOMER_FILTER_ID,
    "preset_condition": {
      "operator": "is",
      "values": [
        customer_id
      ]
    }
  },
  {
    "dynamic_filter_id": MY_DATE_RANGE_FILTER_ID,
    "preset_condition": {
      "operator": "is",
      "values": [
        "last 7 days"
      ]
    }
  }
]

Step 3: Verify to see if your data alert is created

The request should now be ready. After sending it to Holistics, the server will respond with a HTTP status response code to indicate whether the request was successful / failed.

Lastly, be sure to head over to the Holistics page to see if your data alert is created.

Example script

---

An example script to send requests written in Ruby is available here:

# install the neccessary dependencies for this script to work
require "bundler/inline"
require "net/http"
require "json"

gemfile do
  source "https://rubygems.org"
  gem "net-http"
end

# this the Holisitics API endpoint that we need to send our POST request to
DATA_ALERT_ENDPOINT = URI("https://secure.holistics.io/api/v2/data_alerts")

# Step 1: Create a POST request to the endpoint below
request = Net::HTTP::Post.new(DATA_ALERT_ENDPOINT)

# Step 2: Provide your authentication information
request["X-Holistics-Key"] = "mysecretAPIkey"

# Step 2.1: This line helps the system know that we are sending a JSON request
request.content_type = "application/json"

# Step 3: Provide information for your data alert in the request body
request.body = {
  "data_alert": {
    "title": "Tracking number of orders",
    "source_id": 41,
    "source_type": "DashboardWidget",
    # Conditions for the Alert to be Triggered
    "viz_conditions": [
      {
        "field_path": {
          "field_name": "id",
          "model_id": 12
        },
        "aggregation": "count",
        "transformation": null,
        "condition": {
          "operator": "greater_than",
          "modifier": null,
          "values": [35000]
        }
      }
    ],
    # Destination for the Alert
    "dest": {
      "type": "EmailDest",
      "title": "The number of orders has just exceeded than 35000",
      "recipients": [
        "[email protected]"
      ],
      "options": {
        "body_text": null
      }
    },
    # Schedule for the Alert to be Triggered
    "schedule": {
      # Repeat Everyday at 7:00 AM
      "repeat": "0 7 * * *",
      "paused": false
    },
    # Dynamic Filter Presets for the Alert
    "dynamic_filter_presets": [
      {
        "preset_condition": {
          "operator": "is",
          "modifier": null,
          "values": ["VN", "SG"],
        },
        "dynamic_filter_id": 1
      },
      {
        "preset_condition": {
          "operator": "is",
          "modifier": null,
          "values": [
              "Male"
          ],
        },
        "dynamic_filter_id": 2
      }
    ]
  }
}.to_json

# Step 4: Send the request to Holistics!
response = Net::HTTP.start(
  DATA_ALERT_ENDPOINT.hostname,
  DATA_ALERT_ENDPOINT.port,
  :use_ssl => DATA_ALERT_ENDPOINT.scheme == "https",
) do |https|
  https.request(request)
end

# Optional: Output the result into the terminal
puts [response.code,response.message].join(' ')

In Holistics, you can set up schedules sending reports or dashboards to a group of recipients via email, Slack, SFTP, or Azure Blob. This concept is called Data Schedule.

Holistics offers a set of public API endpoints allowing clients to work with Data Schedule. This tutorial shows you how to use the API to create these data schedules programmatically.

Suppose you are a B2B SaaS company that has a feature to email usage statistics to your customers every week. You want to set it up such that:

• When a new customer onboards to your platform, you want Holistics to send a weekly email report to that customer.
• The weekly email reports should be customised to display information regarding the usage data of that customer only

Let's walk through how we can solve this problem using Holistics API.

We will use the API to create email reports. Specifically, we'll send a POST request to Holistics' create email schedule API.

Before that, we need to prepare the following:

• A dashboard with relevant reports. This dashboard will be emailed to the customer.
• The dashboard should have a "Customer" filter to filter down the data for a particular customer.
• Holistics API Key: We need to setup the API key. Refer to this guide for info.

You will need to create a master dashboard that contains the reports you want to send to the customers. In this example, we have a Customer Usage Data dashboard which showcases the statistics of jobs that Holistics customers execute in our platform. We also have two filters in this dashboard, Date Range and Customer.

• The Customer ID filter accepts a customer ID, then passes it to the report within the dashboard. The report then replaces the ID with its placeholder in a prepared SQL query, reruns the query, and fetches only data that belongs to that customer. In other words, this filter helps filter down to the usage data of that customer only.
• Similarly, the Date Range filter's value accepts "last 7 days", "last 14 days", "last 30 days", or "any time". This filter helps filter usage data by a date range. Note that this filter can be optional.

If you are not sure on how to create dashboards and filters, refer to Dashboard Docs.

We'll be using the following endpoint:

POST https://secure.holistics.io/api/v2/data_schedules

There are some notable configuration options in this request:

• schedule: Specify how frequent the email schedule should be
• dynamic_filter_presets: Specify what dynamic filters should be applied to the reports. By configuring this, we can customise the report for each recipient.
• dest: Specify configurations regarding recipients' information.
  • Remember to set dest.type to "EmailDest"

Below is a sample request body. Refer to Holistics API docs for more information on these fields.

ⓘ INFO

💡 Most of the fields are straightforward which means that you can fill them out by reading our API docs. Refer to this section below for notes on trickier fields.

Common fields

• id (integer): This is used to uniquely identified your object. Holistics automatically generates an id for you if you don't specify this.
• source_id (integer): This tells Holistics which dashboard you want to send email to. To determine this value, view your dashboard link. For example, the link https://secure.holistics.io/dashboards/v3/16076-demo-my-beautiful-dashboard will have the source_id of 16076.
• dest: Specify the information regarding the recipients
  • title (string): Note that Holistics support dynamic variables in email title. For example, the title Sales report for {{$today}} sent on 29/09/2021 will be rendered as Sales report for 2021-09-29 Wed.

Schedule frequency

schedule is used to specify the schedule for your email schedule.

repeat (string): You will need to input a crontab expression here to let Holistics how frequent you want to your email schedule to run.

Dynamic filter values

dynamic-filter-presets is where you define your filter presets here.

dynamic_filter_id (integer): To get your filter_id, send a GET request to Dashboards#Get API to get the dashboard info.

preset_conditions (object): Let's go through our example to better illustrate this field.

We want to set a value for the filter by setting a preset condition. A preset condition consists of an operator and a list of values. Holistics supports various operators and provides several examples here.

In this case, we want to use operator is and set values to customer_id. By this, we mean the filter's default value equals exactly to customer_id.

Finally, we also want to set up another dynamic filter preset to filter data to the whole of last week. Fortunately, Holistics allows a list of dynamic filter presets. For the Date Range filter, we similarly want to use operator is and set values to "last 7 days".

Our final dynamic_filter_presets object will look like this.

dynamic_filter_presets = [
  {
    "dynamic_filter_id": MY_CUSTOMER_FILTER_ID,
      "preset_condition": {
        "operator": "is",
        "values": [
          customer_id
      ]
    }
  },
    {
    "dynamic_filter_id": MY_DATE_RANGE_FILTER_ID,
      "preset_condition": {
        "operator": "is",
        "values": [
          "last 7 days"
      ]
    }
  }
]

Step 3: Double-check to see if your email schedule is created

The request should now be ready. After sending it to Holistics, the server will respond with a HTTP status response code to indicate whether the request was successful / failed.

Lastly, be sure to head over to Holistics page to see if your email schedule is created.

Example script

An example script to send requests written in Ruby is available here:

# install the neccessary dependencies for this script to work
require "bundler/inline"
require "net/http"
require "json"

gemfile do
  source "https://rubygems.org"
  gem "net-http"
end

# this the Holisitics API endpoint that we need to send our POST request to
EMAIL_SCHEDULE_ENDPOINT = URI("https://secure.holistics.io/api/v2/data_schedules")

# Step 1: Create a POST request to the endpoint below
request = Net::HTTP::Post.new(EMAIL_SCHEDULE_ENDPOINT)

# Step 2: Provide your authentication information 
request["X-Holistics-Key"] = "mysecretAPIkey"

# Step 2.1: This line helps the system know that we are sending a JSON request
request.content_type = "application/json"

# Step 3: Provide information for your email schedule in the request body
request.body =
  {
    "data_schedule": {
      "source_type": "Dashboard",
      "source_id": 16076,
      "schedule": {
        "repeat": "* * * * *",
        "paused": false,
      },
      "dest": {
        "type": "EmailDest",
        "title": "Sale report for {{$today}}",
        "recipients": [
          "[email protected]",
        ],
      },
    },
  }.to_json

# Step 4: Send the request to Holistics!
response = Net::HTTP.start(
  EMAIL_SCHEDULE_ENDPOINT.hostname,
  EMAIL_SCHEDULE_ENDPOINT.port,
  :use_ssl => EMAIL_SCHEDULE_ENDPOINT.scheme == "https",
) do |https|
  https.request(request)
end

# Optional: Output the result into the terminal
puts [response.code,response.message].join(' ')

💡 NOTE

The current Holistics CLI version is: 0.4.0.

Requirements:

• Ruby 2.7

Holistics CLI is an interface to Holistics Data Preparation module (like data transport, data transform, import).

Linux/Mac OSX

If you are using Linux/Mac OSX, we suggest you install Ruby with a Ruby Version Manager such as rbenv or asdf.

Please follow the instructions in your RVM of choice to install Ruby 2.7.4:

• rbenv: https://github.com/rbenv/rbenv#installation.
• asdf: https://asdf-vm.com/guide/getting-started.html.

After you have Ruby installed on your computer, run:

gem install holistics -v 0.4.0

Windows

If you are using Windows, head over to: Official Ruby Download Page.

And download Ruby 2.7.4 installer. Remember to select the Devkit option for your installer so that you can run the gem install command in the next step from your command line.

After you have Ruby installed on your computer, run:

gem install holistics -v 0.4.0

The next step is authentication. You first need to be granted permissions to have an API authentication token. If you are not sure how, visit: API Authentication.

Assuming that the above step is successful, you can access your token by going to ⚙️ My Account -> API Key. After that, run this in your command line to authenticate yourself.

$ holistics login <my_authentication_token>
Authenticating token...
Authentication successful. Info:
- ID: 1
- Email: admin@you.com

ⓘ IMPORTANT - INVALID AUTHENTICATION TOKEN ERROR

By default, the CLI connects to the Asia-Pacific servers. If your account is in another server (EU or US), you will have to specify the HOLISTICS_HOST > environment variable in your authentication command.

👉 If you are not sure what server you are on, please follow this guide to find out.

Assuming you are in EU server (https://eu.holistics.io), the command will now become:

HOLISTICS_HOST=https://eu.holistics.io holistics login

You will need to prepend every command with HOLISTICS_HOST=https://eu.holistics.io.

Alternatively, specify it only once as a global variable by running:

export HOLISTICS_HOST=https://eu.holistics.io

And you can run the commands without prepending the host everytime.

Help Command

For general help or a list of command, run:

$ holistics help

Here is a list of some Holistics CLI commands you can run:

This documentation will guide you through the process of transitioning from API V1 to the new API V2. It will also provide information about the migration plan and outline what you can expect in our new API version. Our primary goal is to assist you in achieving a smooth and successful transition to Holistics’s latest API version.

For the past few months, we have considered API V1 as our legacy API. While it is still functional, it is not actively maintained. Meanwhile, we have been developing API V2 as a more powerful, flexible, and well-structured version of V1.

Now that API V2 has surpassed its predecessor in both functionality and experience, we are deprecating V1 and are here to assist you in migrating your applications to V2.

ⓘ INFO

The entire API V1 will cease to function by November 20th, 2023.

This deprecation includes all functionalities available in these two V1 kits:

• Users API
• Group API

Be assured that we have supported all of these functionalities API in V2.

Next steps, you will need to manually update your applications that are utilizing V1 to switch them to V2.

How will the migration affect existing applications that are utilizing API V1?

• We expect no interference in your automation workflow after the migration since all functionalities of V1 are completely covered by V2
• However, since there will be some differences in the data schema (or response structure) between the two versions, you would need to follow our documents to set up precisely

Should I do anything prior to this migration?

We suggest you check which applications will be affected by such an update, and inform your team that they will not be available during that time.

What do I do if I encounter unexpected issues?

We are committed to providing support throughout the migration. If you encounter any problems, please reach out to us at support@holistics.io for assistance.

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.

AML Studio APIs

Reporting Dashboards

Reporting Dashboard Widgets

Data delivery using automated schedules

Send automatic notification to you and your team when the data meets certain conditions