Klipfolio API Reference Guide

The Klipfolio API Reference Guide

Welcome to the Klipfolio API Reference Guide. You'll find comprehensive documentation to help you get started with the Klipfolio API. Let's jump right in!

Get Started    
Suggest Edits

Introduction to the Klipfolio API

This page will help you get started with Klipfolio API Reference Guide.

Klipfolio brings your business data to life helping you and your organization understand and track KPIs, metrics and other essential information. The Klipfolio API provides the same functionality as the web app UI for managing assets (clients, dashboards, Klips, data sources). Organized around REST, the Klipfolio API is accessed over HTTPS from the https://app.klipfolio.com/api/1.0/* domain. All responses are returned in JSON.

 

HTTP Methods

The Klipfolio API uses four HTTP methods when accessing API resources: GET, POST, PUT and DELETE.
The HTTP GET method is used to retrieve (or read) a representation of a resource such as client, Klips, and tabs (now called dashboards).
The PUT method is used to update an existing resource.
The POST method is used to create new resources.
The DELETE method is used to delete an existing resource.

Rate limiting

Klipfolio supports up to five API requests per second and requests per day depends on your plan. (restarts at 12:00 am ET). If you exceed either of those limits, any request you send will return a 429 Too Many Requests error with an appropriate message. Limits apply to the company making the request. The usage limit applies to the requesting company. If you require a higher limit than your plans allows, please contact sales@klipfolio.com.

Authentication

The Klipfolio API works with both Basic Authentication and API keys to enable secure authentication. You can generate an API key from the Klipfolio Dashboard app through either the My Profile page or from Users if you are an administrator (you must have the user.manage permission). By default, both the Admin and Editor roles have permission to generate keys.

To use the API key, you must put the following into the header for your query:
kf-api-key:<apikey>

Where <apikey> is replaced with the actual key.

Versioning

The current version of the Klipfolio API is 1.0 (1 is also accepted).

Pagination

When requesting a list of assets (for example, clients, Klips, and so on) using a GET call, use pagination to manage the requests.

Paging is controlled by two URL parameters, "offset" and "limit" as follows:

Offset is the index of the first item in the results. The default is 0.
Limit is the maximum number of results to return. The default is 25. The maximum is 100 (anything over 100 will return a 400 Bad Request error).
In the following example query using pagination, the result will return “page 2” of the list of Klips and each page will show 10 Klips per page:
GET /api/1.0/klips?limit=10&offset=10

Note: If the user does not specify a limit and offset, the first 25 results will be returned.

Permissions

This refers to the permissions required for a particular API request. The permissions are based on your account and your role. The API permissions map directly to the permissions found in the Klipfolio Dashboard user interface.

Parameters

Some API requests include additional parameters that can be used. These are listed with the particular request in the reference guide.

Clients

View, create, update existing clients, and manage clients for all client accounts belonging to the requesting company.

Response codes

The following are examples of HTTP error codes that the API will generate when a correctly authenticated request fails:

400 — The request was formatted incorrectly, or one of the required fields contains invalid.data
401 — Authentication failed or the user does not have permission to access the requested resource.
403 — The user is attempting to perform an action/request that is not allowed.
404 — The requested resource was not found.
405 — The requested method is not supported.
429 — Too many requests.
500 — General error or it is an unexpected error in Klipfolio.

Other response codes include:
200 — Everything worked correctly.
201 — Everything worked correctly and public ID or location of the new resource is returned.
500 — General error or it is an unexpected error in Klipfolio.

Suggest Edits

API Call Examples

This page will help you get started with common API calls.

 

Creating a new Facebook data source

Create a new Facebook data source using the POST /datasources method.

Note: In this instance, you need to find the oauth_user_token from your Facebook account.

curl https://app.klipfolio.com/api/1/datasources -X POST -d "{'name':'<datasource name>', 
'description':'<datasource description>', 'connector':'facebook', 'format':'json',
'refresh_interval':14400,
'properties':{'endpoint_url':
'https:\/\/graph.facebook.com\/me', 'oauth_user_token':'<XXX>',
'oauth_provider_id':'facebook20'}}
" --header "kf-api-key:<apikey>"  -H Content-Type:application/json

Uploading a file to an existing datasource

PUT data to upload a file to an existing datasource using --upload-file. This example is using JSON.

curl https://app.klipfolio.com/api/1/datasource-instances/0123456789abcdef0123456789abcdef/data -X PUT --upload-file  revenue_date.json --header "kf-api-key:01234df230c488e9c5c18862a8967df5ab367c6e" -H Content-Type:application/json

Creating a data source using the REST/URL connector

Create a data source using our REST/URL connector that connects to any service, even if it is not listed as one of our Service Connectors.

curl https://app.klipfolio.com/api/1/datasources -X POST -d 
{
	"name": "TESTPostman POST Klipfolio API",
	"description": "Post man test",
	"connector": "simple_rest",
	"format": "json",
	"refresh_interval": 14400,
	"properties": {
  	"endpoint_url": "https://yourUniqueEndpoint.com/api/values",
  	"method": "get",
  	"parameters": "[{\"name\":\"x-api-		key\",\"value\":\"1aBCDefgHi2JkLmnOpqrs3TuvwX4yZAB5CdE67fg\",\"type\":\"header\"]",
	}
}
Suggest Edits

Beta: Usage Overview

Access an overview of information on client trends, usage and growth.

 

Application Usage Statistics are currently a beta release

Note: Because this is a beta release, some history may not be retained.

Some Application Usage Statistics are available based on your plan

The following Usage Overview endpoints are only available to users on plans Grow and above:

Daily client trend
Monthly client aggregate
Account sign-in trend
User sign-in trend

GET /usage-overview/account-stats

Description

A report of client activity and growth over time.

Resource URL

https://app.klipfolio.com/api/1.0/usage-overview/account-stats

Required permissions

account.api

Required parameters

start_date (Unix time)
end_date (Unix time)

Response codes

200—Success
400—Bad request (missing parameter)
403—Forbidden (missing permissions)
404—Not found

Optional parameters Permissions
company_id (string) client.access

Note: If company_id is not provided, the request will default to the id of the requesting user.

Example Request and Response

{
  "meta": {
    "success": true,
    "status": 200
  },
  "data": {
    "overview": [
      {
        "calendar_date": "2016-09-27",
        "last_login_calendar_date": "2016-09-23",
        "no_of_seats": "3",
        "no_of_users": "2",
        "no_of_klips": "18",
        "no_of_data_sources": "19",
        "no_of_scheduled_emails": "4",
        "no_of_dashboards": "5",
        "no_of_klip_templates": "5",
        "no_of_embeds": "4",
        "data_storage_size": "2991"
      },
      {
        "calendar_date": "2016-09-28",
        "last_login_calendar_date": "2016-09-23",
        "no_of_seats": "3",
        "no_of_users": "2",
        "no_of_klips": "18",
        "no_of_data_sources": "19",
        "no_of_scheduled_emails": "4",
        "no_of_dashboards": "5",
        "no_of_klip_templates": "5",
        "no_of_embeds": "4",
        "data_storage_size": "2885"
      }
    ]
  }
}

Response Fields

last_login_calendar_date: The date the account was last logged into.
calendar_date: The date.
no_of_seats: Number of seats assigned to the company.
no_of_users: Number of users existing in the company.
no_of_klips: Number of Klips existing in the company.
no_of_data_sources: Number of data sources existing in the company.
no_of_scheduled_emails: Number of scheduled emails existing in the company.
no_of_dashboards: Number of dashboards existing in the company.
no_of_klip_templates: Number of Klip templates being used by the company.
no_of_embeds: Number of embeds existing in the company.
data_storage_size: Total data storage size (in bytes).

GET /usage-overview/data-source-stats

Description

The number of data sources and dynamic data source instances by service and account.

Resource URL

https://app.klipfolio.com/api/1.0/usage-overview/data-source-stats

Required permissions

account.api

Required parameters

start_date (Unix time)
end_date (Unix time)

Response codes

200—Success
400—Bad request (missing parameter)
403—Forbidden (missing permissions)
404—Not found

Optional parameters Permissions
company_id (string) client.access

Note: If company_id is not provided, the request will default to the id of the requesting user.

Example Request and Response

{
  "meta": {
    "success": true,
    "status": 200
  },
  "data": {
    "overview": [
    	{
        "company_name": "Acme",
        "calendar_date": "2017-04-01",
        "service_name": "Google Analytics",
        "connector_name": "Website Performance",
        "type_name": "google_analytics",
        "no_of_datasources": "6",
        "no_of_instances": "8"
      },
      {
        "company_name": "Acme",
        "calendar_date": "2017-04-01",
        "service_name": "Google Search Console",
        "connector_name": "Sites",
        "type_name": "simple_rest",
        "no_of_datasources": "2",
        "no_of_instances": "5"
      },
      {
        "company_name": "Acme",
        "calendar_date": "2017-04-02",
        "service_name": "Google Analytics",
        "connector_name": "Website Performance",
        "type_name": "google_analytics",
        "no_of_datasources": "6",
        "no_of_instances": "8"
      },
      {
        "company_name": "Acme",
        "calendar_date": "2017-04-02",
        "service_name": "Not Available",
        "connector_name": "Not Available",
        "type_name": "google_adwords",
        "no_of_datasources": "1",
        "no_of_instances": "1"
      }
    ]
  }
}

Response Fields

company_name: The company name.
calendar_date: The date.
service_name: Service of this data source.
connector_name: Connector service name.
type_name: Type name.
no_of_datasources: Count of datasources for this service/connector/type.
no_of_instances: Count of datasource instances for this service/connector/type.

Note: If service_name or connector_name returns as Not Available, it is referring to a service that is not in the Connector Gallery.

GET/usage-overview/api-usage

Description

A report of API calls and limits reached per day.

Resource URL

https://app.klipfolio.com/api/1.0/usage-overview/api-usage

Required Permissions

account.api

Required Parameters

start_date (Unix time)
end_date (Unix time)

Response codes

200—Success
400—Bad request (missing parameter)
403—Forbidden (missing permissions)
404—Not found

Optional Parameters Permissions
company_id (string) client.access

Note: If company_id is not provided, the request will default to the id of the requesting user.

Example Request and Response

{
  "meta": {
    "success": true,
    "status": 200
  },
  "data": {
    "overview": [
      {
        "calendar_date": "2016-09-01",
        "api_usage": "24",
        "api_limit": "1000"
      },
      {
        "calendar_date": "2016-09-02",
        "api_usage": "12",
        "api_limit": "1000"
      },
      {
        "calendar_date": "2016-09-03",
        "api_usage": "6",
        "api_limit": "1000"
      }
    ]
  }
}

Response Fields

calendar_date: The date.
api_usage: API calls consumed that day.
api_limit: Company limit that day.

GET/usage-overview/published-links

Description

A count on how many views a published link has per hour.

Resource URL

https://app.klipfolio.com/api/1.0/usage-overview/published-links

Required Permissions

account.api

Required Parameters

start_date (Unix time)
end_date (Unix time)

Response Codes

200—Success
400—Bad request (missing parameter)
403—Forbidden (missing permissions)
404—Not found

Optional Parameters Permissions
company_id (string) client.access

Note: If company_id is not provided, the request will default to the id of the requesting user.

Example Request and Response

{
  "meta": {
    "success": true,
    "status": 200
  },
   "data": {
        "overview": [{
            "calendar_date": "2016-09-01",
            "time": "1:0:0",
            "name": "Marketing",
            "is_public": "No",
            "is_disabled": "No",
            "has_password": "No",
            "view_count": "29"
        },
        {
            "calendar_date": "2016-09-01",
            "time": "1:0:0",
            "name": "Sales",
            "is_public": "No",
            "is_disabled": "No",
            "has_password": "No",
            "view_count": "33"
        },
        {
            "calendar_date": "2016-09-01",
            "time": "1:0:0",
            "name": "Social Media",
            "is_public": "No",
            "is_disabled": "No",
            "has_password": "No",
            "view_count": "17"
        },
        {

Response Fields

calendar_date: The date.
time: The time in h: m :s.
name: dashboard name
is_public: Yes or no response indicating whether the link is public.
is_disabled: Yes or no response indicating whether the link is disabled.
has_password: Yes or no response indicating whether the link has a password.
view_count: Number of views that hour.

GET/usage-overview/daily-client-trend

Available for plans: Grow and above

Description

A report of client additions and cancellations per day.

Resource URL

https://app.klipfolio.com/api/1.0/usage-overview/daily-client-trend

Required Permissions

account.api

Required Parameters

start_date (Unix time)
end_date (Unix time)

Response Codes

200—Success
400—Bad request (missing parameter)
403—Forbidden (missing permissions)
404—Not found

Optional Parameters Permissions
company_id (string) client.access

Note: If company_id is not provided, the request will default to the id of the requesting user.

Example Request and Response

{
  "meta": {
    "success": true,
    "status": 200
  },
  "data": {
    "overview": [
      {
        "calendar_date": "2016-09-01",
        "added": "1",
        "cancelled":"0"
      }
      {
       "calendar_date": "2016-09-02",
        "added": "1",
        "cancelled":"1"
      }
     ] 
    }
	}     

Response Fields

calendar_date: The date.
added: Number of clients added that day.
cancelled: Number of clients removed that day.

GET/usage-overview/monthly-client-aggregate

Available for plans: Grow and above

Description

A monthly overview of client trends and activity.

Resource URL

https://app.klipfolio.com/api/1.0/usage-overview/monthly-client-aggregate

Required Permissions

account.api

Required Parameters

start_date (Unix time)
end_date (Unix time)

Response Codes

200—Success
400—Bad request (missing parameter)
403—Forbidden (missing permissions)
404—Not found

Optional Parameters Permissions
company_id (string) client.access

Note: If company_id is not provided, the request will default to the id of the requesting user.

Example Request and Response

{
  "meta": {
    "success": true,
    "status": 200
  },
  "data": {
    "overview": [
      {
        "calendar_date": "2016-09-01",
        "adds": "0",
        "cancels": "0",
        "total": "7",
        "setup": "6",
        "trial": "0",
        "active": "1",
        "disabled": "0",
        "expired": "0",
        "grace": "0",
        "arrears": "0"
      }
    ]
  }
}

Response Fields

calendar_date: The date.
adds: Number of clients added.
cancels: Number of clients removed.
total: Total number of clients.
setup: Total number of clients in Setup.
trial: Total number of clients in Trial.
active: Total number of clients Active.
disabled: Total number of clients Disabled.
expired: Total number of clients Expired.
grace: Total number of clients in Grace.
arrears: Total number of clients in Arrears.

GET/usage-overview/account-sign-in-trend

Available for plans: Grow and above

Description

A trend of account sign-in activity over a period of time.

Resource URL

https://app.klipfolio.com/api/1.0/usage-overview/account-sign-in-trend

Required Permissions

account.api

Required Parameters

start_date (Unix time)
end_date (Unix time)

Response Codes

200—Success
400—Bad request (missing parameter)
403—Forbidden (missing permissions)
404—Not found

Optional Parameters Permissions
company_id (string) client.access

Note: If company_id is not provided, the request will default to the id of the requesting user.

Example Request and Response

{
  "meta": {
    "success": true,
    "status": 200
  },
  "data": {
    "overview": [
      {
        "calendar_date": "2016-09-01",
        "last_login_calendar_date": "2016-08-01",
        "days_since_login": "161",
        "no_of_seats": "12",
        "no_of_users": "4",
        "24h_login_percentage": "0",
        "7d_login_percentage": "0",
        "14d_login_percentage": "0",
        "30d_login_percentage": "0",
        "90d_login_percentage": "50"
      },
      {
        "calendar_date": "2016-09-02",
        "last_login_calendar_date": "2016-08-01",
        "days_since_login": "161",
        "no_of_seats": "12",
        "no_of_users": "5",
        "24h_login_percentage": "20",
        "7d_login_percentage": "20",
        "14d_login_percentage": "20",
        "30d_login_percentage": "20",
        "90d_login_percentage": "60"
      }
    ]
  }
}

Response Fields

calendar_date: The date.
last_login_calendar_date: Date last logged in.
days_since_login: Number of days since the date last logged in and now.
no_of_seats: Number of seats assigned to the company.
no_of_users: Number of users existing in the company.
24h_login_percentage: Percentage of users that logged in during past 24 hours.
7d_login_percentage: Percentage of users that logged in during past 7 days.
14d_login_percentage: Percentage of users that logged in during past 14 days.
30d_login_percentage: Percentage of users that logged in during past 30 days.
90d_login_percentage: Percentage of users that logged in during past 90 days.

GET/usage-overview/user-sign-in-trend

Available for plans: Grow and above

Description

A trend of user sign-in activity per day.

Resource URL

https://app.klipfolio.com/api/1.0/usage-overview/user-sign-in-trend

Required Permissions

account.api

Required Parameters

start_date (Unix time)
end_date (Unix time)

Response Codes

200—Success
400—Bad request (missing parameter)
403—Forbidden (missing permissions)
404—Not found

Optional Parameters Permissions
company_id (string) client.access
user_id (string) user.manage

Note: If company_id is not provided, the request will default to the id of the requesting user.

Example Request and Response

{
  "meta": {
    "success": true,
    "status": 200
  },
 "data": {
    "overview": [
      {
        "CompanyName": "Acme",
        "FirstName": "Fatimah",
        "LastName": "Virjee",
        "Email": "fvirjee@acme.com",
        "AppContactId": "1f1234f56f123456b1234f123456a12b",
        "CalendarDate": "2017-04-03",
        "HMS": "10:18:50",
        "MobileLogin": "No"
      },
      {
        "CompanyName": "Acme",
        "FirstName": "Fatimah",
        "LastName": "Virjee",
        "Email": "fvirjee@acme.com",
        "AppContactId": "1f1234f56f123456b1234f123456a12b",
        "CalendarDate": "2017-04-04",
        "HMS": "9:44:58",
        "MobileLogin": "No"
      }
    ]
  }
}

Response Fields

CompanyName: Company/account name.
FirstName: First name of user.
LastName: Last name of user.
Email: User's email address.
AppContactId: User's ID.
CalendarDate: The date.
HMS: The time in h: m :s.
MobileLogin: Yes or no response indicating whether the user signed in from a mobile device.

Suggest Edits

Beta: Usage Details

Access information on account trends and usage.

 

Application Usage Statistics are currently a beta release

Note: Because this is a beta release, some history may not be retained.

GET /usage-details/published-link-views

Description

Track every published link view.

Resource URL

https://app.klipfolio.com/api/1.0/usage-details/published-link-views

Required permissions

account.api

Required parameters

start_date (Unix time)
end_date (Unix time)
agg_method: count, distinct, integral, mean, median, spread, sum
interval (integer) used to specify the grouping of results in relation to the optional parameter, units. If unit is not specified, the default unit is hour.

Response codes

200—Success
400—Bad request (missing parameter)
403—Forbidden (missing permissions)
404—Not found

Optional parameters Permissions
company_id (string) client.access
unit
s (seconds)
m (minutes)
h (hours)
d (days)
w (weeks)
no permission
link_id (string) tab.publish
is_public no permission

Notes:

If company_id is not provided, the request will default to the id of the requesting user.

Data at the second and minute level are updated instantly. Hourly, daily and weekly level data is updated once every hour.

Example Request and Response

{
  "meta": {
    "success": true,
    "status": 200
  },
  "data": {
    "measurement": "published-link-views",
    "agg_method": "SUM",
    "interval": 5,
    "unit": "m",
    "results": [
      {
        "timestamp": "2016-09-16T00:00:00Z",
        "value": 249
      },
      {
        "timestamp": "2016-09-21T00:00:00Z",
        "value": 171
      }
    ]
  }
}

GET /usage-details/api-calls

Description

Track every API call.

Resource URLPermissions

https://app.klipfolio.com/api/1.0/usage-details/api-calls

Required permissions

account.api

Required parameters

start_date (Unix time)
end_date (Unix time)
agg_method: count, distinct, integral, mean, median, spread, sum
interval (integer) used to specify the grouping of results in relation to the optional parameter, units. If unit is not specified, the default unit is hour.

Response codes

200—Success
400—Bad request (missing parameter)
403—Forbidden (missing permissions)
404—Not found

Optional parameters Permissions
company_id (string) client.access
unit
s (seconds)
m (minutes)
h (hours)
d (days)
w (weeks)
no permission

Notes:

If company_id is not provided, the request will default to the id of the requesting user.

Data at the second and minute level are updated instantly. Hourly, daily and weekly level data is updated once every hour.

Example Request and Response

{
  "meta": {
    "success": true,
    "status": 200
  },
  "data": {
    "measurement": "api-calls",
    "agg_method": "SUM",
    "interval": 5,
    "unit": "m",
    "results": [
      {
        "timestamp": "2016-09-16T00:00:00Z",
        "value": 923
      },
      {
        "timestamp": "2016-09-21T00:00:00Z",
        "value": 871
      }
    ]
  }
}

GET /usage-details/api-calls-over-limit

Description

Track the number of API calls over the limit.

Resource URL

https://app.klipfolio.com/api/1.0/usage-details/api-calls-over-limits

Required permissions

account.api

Required parameters

start_date (Unix time)
end_date (Unix time)
agg_method: count, distinct, integral, mean, median, spread, sum
interval (integer) used to specify the grouping of results in relation to the optional parameter, units. If unit is not specified, the default unit is hour.

Response codes

200—Success
400—Bad request (missing parameter)
403—Forbidden (missing permissions)
404—Not found

Optional parameters Permissions
company_id (string) client.access
unit
s (seconds)
m (minutes)
h (hours)
d (days)
w (weeks)
no permission

Notes:

If company_id is not provided, the request will default to the id of the requesting user.

Data at the second and minute level are updated instantly. Hourly, daily and weekly level data is updated once every hour.

Example Request and Response

{
  "meta": {
    "success": true,
    "status": 200
  },
  "data": {
    "measurement": "api-calls-over-limit",
    "agg_method": "SUM",
    "interval": 5,
    "unit": "m",
    "results": [
      {
        "timestamp": "2016-09-16T00:00:00Z",
        "value": 12
      },
      {
        "timestamp": "2016-09-21T00:00:00Z",
        "value": 23
      }
    ]
  }
}

GET/usage-details/dashboard-views

Description

Track dashboard views by user.

Resource URL

https://app.klipfolio.com/api/1.0/usage-details/dashboard-views

Required permissions

account.api

Required parameters

start_date (Unix time)
end_date (Unix time)
agg_method: count, distinct, integral, mean, median, spread, sum
interval (integer) used to specify the grouping of results in relation to the optional parameter, units. If unit is not specified, the default unit is hour.

Response Codes

200—Success
400—Bad request (missing parameter)
403—Forbidden (missing permissions)
404—Not found

Optional parameters Permissions
company_id (string) client.access
unit
s (seconds)
m (minutes)
h (hours)
d (days)
w (weeks)
no permission
user_id
dashboard_id

Notes:

If company_id is not provided, the request will default to the id of the requesting user.

Data at the second and minute level are updated instantly. Hourly, daily and weekly level data is updated once every hour.

Example Request and Response

{
  "meta": {
    "success": true,
    "status": 200
  },
  "data": {
    "measurement": "dashboard-views",
    "agg_method": "SUM",
    "interval": 5,
    "unit": "m",
    "results": [
      {
        "timestamp": "2016-09-16T00:00:00Z",
        "value": 149
      },
      {
        "timestamp": "2016-09-21T00:00:00Z",
        "value": 271
      }
    ]
  }
}
Suggest Edits

Clients

View, create, update existing clients, and manage clients for all client accounts belonging to the requesting company.

 

GET /clients

Description

Collects a list of all the clients associated with the requesting account. Users with admin role privileges have access to all clients.

Permissions

client.access

Parameters

external_id (string) — show only clients that have the specified external id
full (true/false) — include associations in the listing (users, groups, share_rights) (only works when specifying external_id)

Example Requests

GET https://app.klipfolio.com/api/1/clients
GET https://app.klipfolio.com/api/1.0/clients?status=active

Example Response

{
    "meta": {
        "success": true,
        "status": 200,
        "count": 3,
        "total": 3
    },
    "data": {
        "clients": [
            {
                "id": "0123456789abcdef0123456789abcdef",
                "name": "Company A",
                "description": "Testing for demo",
                "status": "Active",
                "seats": -1,
                "last_sign_in": "2015-02-26T23:58:29Z"
            },
            {
                "id": "0123456789abcdef0123456789abcdef",
                "name": "Company B,
                "description": "Marketing",
                "status": "Active",
                "seats": -1,
                "last_sign_in": "2017-03-02T18:03:07Z"
            },
            {
                "id": "0123456789abcdef0123456789abcdef",
                "name": "Company C",
                "description": "Stats for Google Analytics",
                "status": "Active",
                "seats": -1,
                "last_sign_in": null
            }
        ]
    }
}

Note: The external_id is not shown if the client’s external ID is null

GET /clients/{id}

Description

Get the details for the specified client.

Permissions

client.access

Parameters

full (true/false) — include associations in the listing (users, groups, share_right)

Example Request

GET https://app.klipfolio.com/api/1/clients/0123456789abcdef0123456789abcdef?full=true

Example Response

Note: custom_theme is shown only if the feature is enabled in the parent account
external_id is not shown if the client’s external id is null
trial_remaining is shown only if the client is a trial user

{
   "data": {
       "custom_theme": true,
       "description": Company C,
       "groups": [
           "0123456789abcdef0123456789abcdef",
           "23456789abcdef0123456789abcdef01",
           "456789abcdef0123456789abcdef0123"
       ],
       "id": "0123456789abcdef0123456789abcdef",
       "is_direct_billed": false,
       "last_sign_in": null,
       "name": "Client C",
       "primary_contact": null,
       "seats": 50,
       "share_rights": [
           {
               "group_id": "6789abcdef0123456789abcdef012345",
               "group_name": "Management",
               "can_manage": true
    }],
       "status": "Trial",
       "trial_remaining": 5,
       "users": [
           "0123456789abcdef0123456789abcdef",
           "23456789abcdef0123456789abcdef01",
           "456789abcdef0123456789abcdef0123"
       ]
   },
   "meta": {
       "status": 200,
       "success": true
   }
}

POST /clients

Description

Create a client.

Permissions

client.build

Fields

name, description, status, seats (optional), custom_theme (optional), external_id (optional)

Example Request

Note: 'status' can be 'disabled', ‘setup’ or ‘trial’. ‘custom_theme’ is optional, optionally include ‘external_id’ in the post data to add an external id to the new client

POST https://app.klipfolio.com/api/1/clients -d
“{
'name': 'Client From API',
'description': 'Hello there',
'seats': 20,
'status': 'trial'
'custom_theme': true
}"

##Example Response

{
"data": {},
"meta": {
"location": "/clients/0123456789abcdef0123456789abcdef",
"status": 201,
"success": true
}
}
```

PUT/clients/{id}

Description

Update the specified client.

Permissions

client.edit

Fields

name, description, status, seats, custom_theme, external_id

Example Request

PUT https://app.klipfolio.com/api/1/clients/0123456789abcdef0123456789abcdef -d {“status”: “disabled”}

Example Response

{
   "data": {},
   "meta": {
       "status": 200,
       "success": true
   }
}

DELETE /clients/{id}

Description

Delete a client.

Permissions

client.delete

Parameters

None.

Example Request

DELETE https://app.klipfolio.com/api/1/clients/0123456789abcdef0123456789abcdef

Example Response

{
   "data": {},
   "meta": {
       "status": 200,
       "success": true
   }
}

POST /clients/{id}/@/enable_direct_billing

Description

Switch a client to direct billing. This cannot be undone. This command is only available to Partner accounts.

Permissions

client.access

Fields

None.

Example Request

POST https://app.klipfolio.com/api/1/clients/0123456789abcdef01234589abcdef/@/enable_direct_billing

Example Response

{
  "data": {
      "op_requested":”enable_direct_billing” 
  },
  "meta": {
      "status": 200,
      "success": true
  }
}

POST /clients/{id}/@/extend trial

Description

Extend a client’s trial period.

Permissions

client.access

Fields

None.

Example Request

POST https://app.klipfolio.com/api/1/clients/0123456789abcdef0123456789abcdef/@/extend_trial -d “{‘days’:’7’}”

Example Response

{
  "data": {
      "op_requested":”extend_trial” 
  },
  "meta": {
      "status": 200,
      "success": true
  }
}
Suggest Edits

Client Features

View and update client features for all client accounts belonging to the requesting company.

 

GET /clients/{id}/features

Description

List features (Download Reports, Custom Theme, SSL Domain Alias, Private Links, Embeds, Public Links, Email Reports and SSO) allocated to a specified client. Users with admin role privileges have access to all clients.

Permissions

client.access

Parameters

id (string) — client id

Example Request

GET https://app.klipfolio.com/api/1.0/clients/1234c12345e064e6e05c5bfbddd9bdb4/features

Example Response

{
  "meta": {
    "success": true,
    "status": 200
  },
  "data": {
    "features": [
      {
        "name": "theming",
        "display_name": "Custom Theme",
        "enabled": false
      },
      {
        "name": "domain_cloaking",
        "display_name": "SSL Domain Alias",
        "enabled": false
      },
      {
        "name": "published_dashboards",
        "display_name": "Private Links",
        "enabled": false
      },
      {
        "name": "downloadable_reports",
        "display_name": "Download Reports",
        "enabled": true
      },
      {
        "name": "scheduled_emails",
        "display_name": "Email Reports",
        "enabled": true
      },
      {
        "name": "sso",
        "display_name": "SSO",
        "enabled": true
      },
      {
        "name": "embeds",
        "display_name": "Embeds",
        "enabled": true
      },
      {
        "name": "public_dashboards",
        "display_name": "Public Links",
        "enabled": true
      }
    ]
  }
}

PUT/clients/{id}/features

Description

Update the status of the specified feature. Users with admin role privileges have access to all clients.

Permissions

client.edit

Fields

Features:
downloadable_reports, embeds, public_dashboards, scheduled_emails, published_dashboards, theming, domain_cloaking and sso

Example Request

PUT https://app.klipfolio.com/api/1.0/clients/1234c12345e064e6e05c5bfbddd9bdb4/features -d {
"features": [{"name":"domain_cloaking","enabled":false}]}

Example Response

{
  "meta": {
    "success": true,
    "status": 200
  },
  "data": {}
}
Suggest Edits

Client Properties

Manage a client's dashboard

 

Manage a client's dashboard properties.

GET /clients/{id}/properties

Description

Retrieve a list of the client's dashboard properties.

Permissions

client.access

Parameters

None.

Example Response

{
  "meta": { "success": true, "status": 200 },
  "data": { "properties": { "alpha": "omega", "gamma": "zeta" } }
}

PUT /clients/{id}/properties

Description

Add or update a dashboard property in a client's account.

Permissions

client.edit

Parameters

None.

Example Post Request

curl https://app.klipfolio.com/api/1/clients/6xxxxxxxx3a29bc1babadc866aec723f/properties -X PUT
-d "{'properties': {'alpha': 'omega', 'gamma': 'zeta'}}" --header "kf-api-key:6xxxxxxxx60c488e9c5c18862a8967df5ab367c6e" -H "Content-Type: application/json"

Example Response

{ "meta": { "success": true, "status": 200 }, "data": { } }

DELETE /clients/{id}/properties

Description

Delete a dashboard property from a client's account.

Permissions

client.edit

Fields

name - the name of the property you want to delete

Example Delete

curl https://app.klipfolio.com/api/1/clients//6xxxxxxxx490ede0876ed71d48cfeee2/properties?name=alpha -X DELETE --header "kf-api-key:/6xxxxxxxx60c488e9c5c18862a8967df5ab367c6e"

Example Response

{ "meta": { "success": true, "status": 200 }, "data": { } }
Suggest Edits

Client Resources

View and update client resources for all client accounts belonging to the requesting company.

 

GET /clients/{id}/resources

Description

Lists all resources (dashboards, Klips, data sources, API resources, private links, concurrent sessions) allocated to a specified client. Users with admin role privileges have access to all clients.

Permissions

client.access

Parameters

id (string) — client id
full (true/false) — include resources (API Calls per Day, API Calls per Second, API Append Data Size (in KB), Klips per Dashboard,
Maximum viewable Dashboards, Dashboards, Data Sources per Formula, Users, Concurrent Sessions, Private Links)

Example Request

GET https://app.klipfolio.com/api/1.0/clients/7117c12053e064e6e05c5bfbddd9bab4/resources

Example Response

{
  "meta": {
    "success": true,
    "status": 200
  },
  "data": {
    "resources": [
      {
        "name": "API Calls per Day",
        "value": 10000
      },
      {
        "name": "API Calls per Second",
        "value": 5
      },
      {
        "name": "API Append Data Size (in KB)",
        "value": 10240
      },
      {
        "name": "Klips per Dashboard",
        "value": 30
      },
      {
        "name": "Maximum viewable Dashboards",
        "value": 60
      },
      {
        "name": "Dashboards",
        "value": -1
      },
      {
        "name": "Data Sources per Formula",
        "value": 12
      },
      {
        "name": "Users",
        "value": 3
      },
      {
        "name": "Concurrent Sessions",
        "value": 2
      },
      {
        "name": "Private Links",
        "value": 0
      },
      {
        "name": "Private Link Viewers",
        "value": 100
      }
    ]
  }
}

PUT/clients/{id}/resources

Description

Update the specified resource. Users with admin role privileges have access to all clients.

Permissions

client.edit

Fields

Resource names:
api.requests.perSecond
api.append.data.size
dashboard.klips.perTab
dashboard.tabs.perDashboard
dashboard.tabs.total
workspace.datasources.perFormula
company.seats
sessions.concurrent
published.private.links
published.private.concurrent

Example Request

https://app.klipfolio.com/api/1.0/clients/7117c12053e064e6e05c5bfbddd9bab4/resources -d
"resources": [{"name":"published.private.links", "value":7}]

Example Response

{
  "meta": {
    "success": true,
    "status": 200
  },
  "data": {}
}
Suggest Edits

Client Settings

View and set configurations for clients' accounts

 

GET /clients/{id}/settings

Description

Retrieve a list of settings for a specified client.

Permissions

client.access

Parameters

None.

Example Request

GET https://app.klipfolio.com/api/1/clients/0123456789abcdef0123456789abcdef/settings

Example Response

{
  "meta": {
    "success": true,
    "status": 200
  },
  "data": {
    "settings": {
      "brand.parent.enabled": null,
      "datasource.blacklist": null,
      "firstrun.introductoryTour": enabled,
      "dpn.env.date.language.tag": "fr-FR"
    }
  }
}

POST /clients/{id}/settings

Description

Sets the value of one or more company properties.

Permissions

client.access

Parameters

dpn.env.date.language.tag
List of possible locales supported by this tag:
ENGLISH = "en"
FRENCH = "fr"
GERMAN = "de"
ITALIAN = "it"
JAPANESE = "ja"
KOREAN = "ko"
CHINESE = "zh"
SIMPLIFIED_CHINESE = "zh-CN"
TRADITIONAL_CHINESE = "zh-TW"
FRANCE = "fr-FR"
GERMANY = "de-DE"
ITALY = "it-IT"
JAPAN = "ja-JP"
KOREA = "ko-KR"
CHINA = SIMPLIFIED_CHINESE
PRC = SIMPLIFIED_CHINESE
TAIWAN = TRADITIONAL_CHINESE
UK = "en-GB"
US = "en-US"
CANADA = "en-CA"
CANADA_FRENCH = "fr-CA"
optional introductory tour property:
firstrun.introductoryTour

Note: Clients of White Label partners have the tour property turned off by default. Clients of partners without White Label have the tour property turned on by default.

Example Request

POST https://app.klipfolio.com/api/1/clients/0123456789abcdef0123456789abcdef/settings -d "{'firstrun.introductoryTour.show':true}

Example Response

{
  "meta": {
    "success": true,
    "status": 200
  },
  "data": {}
}
Suggest Edits

Client Share Rights

Change who within the requesting company has access to clients. View, update and manage client share-rights.

 

GET /clients/{id}/share-rights

Description

Get a list of the specified client’s share rights.

Permissions

client.access

Parameters

None.

Example Request

GET https://app.klipfolio.com/api/1/clients/0123456789abcdef0123456789abcdef/share-rights

Example Response

{
   "data": {
       "share_rights": [
    {
       "group_id": "0123456789abcdef0123456789abcdef",
       "group_name": "Example Group",
       "can_manage": true
     },
     ...
   ]
   },
   "meta": {
       "status": 200,
       "success": true
   }
}

PUT /clients/{id}/share-rights

Description

Update the specified client’s share rights. If the client is not already shared with a specified group, a new share right is created, otherwise the existing share right is updated.

Permissions

client.share

Parameters

None.

Example Request

PUT https://app.klipfolio.com/api/1/clients/0123456789abcdef0123456789abcdef/share-rights -d "{'groups':[{'group_id':'fedcba9876543210fedcba9876543210','can_manage':true}]}"

Example Response

{
   "data": {},
   "meta": {
       "status": 200,
       "success": true
   }
}

DELETE /clients/{id}/share-rights/{group-id}

Description
Permissions
Resource URL
Parameters
Response codes

Revoke a group's access to a client
client.share
https://app.klipfolio.com/api/1.0/clients/{id}/share-rights
None.
400 — missing group id
401 — access denied to users from other companies and users who do not have share rights
403 — client is not shared with group
404 — {id} or {group-id} not found

Resource URL

client.share

Parameters

None.

Example Request

DELETE https://app.klipfolio.com/api/1/clients/0123456789abcdef0123456789abcdef/share-rights/fedcba9876543210fedcba9876543210

Example Response

{
   "data": {},
   "meta": {
       "status": 200,
       "success": true
   }
}
Suggest Edits

Data Sources

Viewing, creating, updating and managing data sources.

 

GET /datasources

Description

Get a list of all the data sources to which the user has access.

Permissions

dashboard.library

Parameters

client_id={id}

Example Request

GET https://app.klipfolio.com/api/1/datasources?client_id=0123456789abcdef0123456789abcdef

Example Response

{
  "meta": {
    "success": true,
    "status": 200,
    "count": 4,
    "total": 4
  },
  "data": {
    "datasources": [
      {
        "id": "c98bad42a8c8a63e0b5e6c0f7aca9898",
        "name": "Example: Marketing Web Analytics",
        "description": "Sample data you can use when trying out Klipfolio. This is an example of typical web analytics data that you might pull out of services like Google Analytics, GoSquared or Adobe Analytics.",
        "refresh_interval": 0,
        "date_last_refresh": "2016-06-17T13:33:57Z",
        "is_dynamic": false
      },

    ]
  }
}

GET /datasources/{id}

Description

Get the details for the specific data source id.

Permissions

dashboard.library

Parameters

id={datasource id}

Example Request

GET https://app.klipfolio.com/api/1/datasources/0123456789abcdef0123456789abcdef

Example Response

{
  "data": {
       "id":"0123456789abcdef0123456789abcdef",
       "company":"Self",
       "name":"Sample Datasource",
       "description":"Datasource sample details",
       "connector":"google_adwords",
       "format":"csv",
       "refresh_interval":432000,
       "created_by":"98765432109876543210987654321",
       "is_dynamic":false,
       "disabled":false,
       "date_created":"2014-11-04T20:26:22Z",
       "date_last_refresh":"2014-11-12T21:43:10Z"
  },
  "meta": {
      "status": 200,
      "success": true
  }

POST /datasources

Description

Create a data source. Data source properties can optionally be specified in the post data.

Permissions

datasource.create

Fields

name, description, format, connector, refresh_interval, properties, client_id (optional)

Where connector could be: 'box', 'comscore', 'db', 'dropbox', 'facebook', 'ftp', 'google_adwords', 'google_analytics', 'google_drive', 'google_spreadsheets', 'hubspot', 'iformbuilder', 'marketo', 'omniture', 'radian6', 'salesforce', 'searchMetrics', 'shopify', 'simple_rest', 'survey_monkey', 'versature', 'xero', 'xmla'

Example Requests

Note: optionally include 'client_id' in the post data to create a data source for a client.

POST https://app.klipfolio.com/api/1/datasources -d
“{'name': 'Example','description': 'This is a new data source', 'format': 'xml', 'connector': 'simple_rest', 'refresh_interval': 1800, 'properties': {'endpoint_url': 'http://test/data/scatter.xml', 'method': 'GET'}}”

This is an example request for a Google Analytics dynamic data source:

POST https://app.klipfolio.com/api/1/datasources -d "{'name': 'Test', 'description': 'Test', 'connector': 'google_analytics', 'format': 'csv', 'refresh_interval': 12345, 'properties': { 'endpoint_url': 'https://www.googleapis.com/analytics/v3/data/ga\?ids=ga:{props.profile_id}\&dimensions=ga:deviceCategory,ga:date\&metrics=ga:sessions\&start-date={date.add(-365).format()}\&end-date={date.today}\&max-results=10000', 'oauth_provider_id': 'google20', 'oauth_user_header': '123456abcdefg123456abcdef1234abcd12ab1234abcd', 'oauth_user_token': 'ab12.Ai-aA1G23BcD4EF5gHijk678lMNOpqrSTu-vW_x9Yzabcd1Efghij2kl3m4_N5OPQjQ', 'token_id': '123ab45c6a123b123a1abc1234abc12b1', 'prop:profile_id': '123456789'}}"

Example Response

Note that both the data source id and the corresponding data source instance id is returned.

{
 "meta": {
   "success": true,
   "status": 201,
   "location": "/datasources/5d8821caa9ac3b2a291496e182de13e2",
   "instance_location": "/datasource_instances/5d8821caa9ac3b2a291496e182de13e2"
 },
 "data": { }
}

PUT /datasources/{id}

Description

Update the specified data source.

Permissions

datasource.edit

Fields

name, description, refresh_interval

Example Request

PUT https://app.klipfolio.com/api/1/datasources/8ea607c46ba6a7ba6e4c16ee292d7608 -d
"{'name': 'Updated Data Source Name',
'description': 'This is cool info',
'refresh_interval': 14400}"

Example Response:

{ "meta": { "success": true, "status": 200 }, "data": { } }

Note: Use Data Source Instances Data to update the specified data source with data.

DELETE /datasources/{id}

Description

Delete the data source associated with a specific data source ID.

Permissions

datasource.delete

Parameters

id={datasource id}

Example Request

DELETE https://app.klipfolio.com/api/1/datasources/0123456789abcdef0123456789abcdef

Example Response

{
"data": {},
"meta": {
    "status": 200,
    "success": true
}
}
Suggest Edits

Data Source Operations

Perform tasks related to the data source including refresh the data source, enable or disable the data source and import a data source.

 

POST /datasources/{id}/@/enable

Description

Enable the specific datasource id.

Permissions

datasource.edit

Parameters

id={datasource id}

Example Request

POST https://app.klipfolio.com/api/1/datasources/0123456789abcdef0123456789abcdef/@/enable

Example Response

{
"data": {
     "op_requested":"enable"
},
"meta": {
    "status": 200,
    "success": true
}
}

POST /datasources/{id}/@/disable

Description

Disable the specific datasource ID.

Permissions

datasource.edit

Parameters

id={datasource id}

Example Request

POST https://app.klipfolio.com/api/1/datasources/0123456789abcdef0123456789abcdef/@/disable

Example Response

{
"data": {
    "op_requested":"disable"
},
"meta": {
   "status": 200,
   "success": true
}
}

POST /datasources/{id}/@/import

Description

Import the data source into the client account specified in the post data by the client id. The location of the newly imported data source is returned on successful completion.

Permissions

datasource.import

Parameters

id={datasource id}

Example Request

POST https://app.klipfolio.com/api/1/datasources/abc01234567/@/import -d
"{'client_id': '0123456789abcdef0123456789abcdef'}"

Example Response

{
 "meta": { "success": true, 
 "status": 201,
 “location”: “/datasources/abc01234567”},
 "data": { "op_requested": "import" }
}

POST /datasources/{id}/@/delete_instances

Description

Delete instances related to a specified data source.

Permissions

datasource.delete

Parameters

last_access (optional: Unix time) Only deletes instances that haven't been accessed since the specified time. If not specified, deletes all instances of the specified data source.
keep_latest_instance (boolean). Deletes all specified instances except the one most recently accessed.

Example Request

POST https://app.klipfolio.com/api/1/datasources/1234asdfg1234asdfg/@/delete_instances?last_access=50004

Example Response

{
  "meta": {
    "success": true,
    "status": 200
  },
  "data": {}
}
Suggest Edits

Data Source Properties

Specify how to connect to the data source, end point URL, method (GET/POST). Each data source has its own set of properties.

 

GET /datasources/{id}/properties

Description

Get the properties for the specific data source ID.

Permissions

dashboard.library

Parameters

id={datasource id}

Example Request

GET https://app.klipfolio.com/api/1/datasources/0123456789abcdef0123456789abcdef/properties

Example Response

{
"data": {
    "properties":"The response here depends on the datasource type”
},
"meta": {
   "status": 200,
   "success": true
}
}

PUT /datasources/{id}/properties

Description

Create or update the properties for this data source.

If the property exists, it will be updated. If the specified property does not already exist, it is created.

Permissions

datasource.edit

Parameters

id={datasource id}

Example Request

curl -X PUT https://app.klipfolio.com/api/1/datasources/0123456789abcdef0123456789abcdef/properties -d "{'properties': {'endpoint_url': 'http://abcd.com', 'other_example_prop': 'something'}}"

Example Response

"meta": {
   "status": 200,
   "success": true
}

DELETE /datasources/{id}/properties

Description

Delete a specific datasource property.

Permissions

datasource.edit

Parameters

None.

Example Request

DELETE https://app.klipfolio.com/api/1/datasources/0123456789abcdef0123456789abcdef/properties?name='Stuff'

Example Response

{
"meta": {
      "status": 200,
      "success": true
  }
}
Suggest Edits

Data Source Share Rights

View, update and manage the sharing rights for a data source.

 

GET /datasources/{id}/share-rights

Description

Get the sharing rights details for the specific datasource id.

Permissions

dashboard.library

Parameters

id={datasource id}

Response codes

401 — Access denied to users from other companies and users with no share right
404 — Data source not found

Example Request

GET https://app.klipfolio.com/api/1/datasources/0123456789abcdef0123456789abcdef/share-rights

Example Response

{
"data": {
    "share_rights":[
     {
       "group_id": "52978f697f02f7ac4459e979f2aac29b",
       "group_name": "Example Group",
       "can_copy": true,
       "can_edit": true
     },
     ...
   ]
},
"meta": {
   "status": 200,
   "success": true
}
}

PUT /datasources/{id}/share-rights

Description

Update a data source's share rights. If the data source is not already shared with the specified group a new share right is created, otherwise the existing right is updated.

Permissions

datasource.share

Parameters

id={datasource id}

Response codes

400 — 'groups' missing in post data or poorly formatted post data
401 — Access denied to users from other companies and users with no share right
403 — forbidden to share across companies
404 — Data source not found

Example Request

PUT https://app.klipfolio.com/api/1/datasources/0123456789abcdef0123456789abcdef/share-rights -d "{'groups': [{'group_id': 'abcdef0123456789986543210', 'can_edit': true, 'can_copy': false}]}"

Example Response

{
"meta": {
   "status": 200,
   "success": true
}
}

DELETE /datasources/{id}/share-rights/{group-id}

Description

Revoke a group's access to a data source.

Permissions

datasource.share

Parameters

None.

Response codes

400 — missing {group-id}
401 — access denied to users from other companies and users with no share right
403 — data source is not shared with group
404 — {id} or {group-id} not found

Example Request

DELETE https://app.klipfolio.com/api/1/datasources/0123456789abcdef0123456789abcdef/share-rights/fedcba9876543210fedcba9876543210

Example Response

{
   "data": {},
   "meta": {
       "status": 200,
       "success": true
   }
}
Suggest Edits

Data Source Instances

A data source may have more than one instance associated with it. If the data source is a dynamic data source, it will have more than one instance associated with it. Other data sources have one instance, and the ID in this case is the same as the data source ID.

 

GET /datasource-instances

Description

Get a list of all the datasource-instances to which the user has access.

Permissions

dashboard.library

Parameters

client_id={id}

Response codes

401 — Access to this datasource-instance is denied
404 — Data source instance not found

Example Request

GET https://app.klipfolio.com/api/1/datasource-instances?client_id=0123456789abcdef0123cdef

Example Response

{
  "meta": {
    "success": true,
    "status": 200,
    "count": 4,
    "total": 4
  "data": {
    "datasources": [
      {
        "id": "4928fb1d95bfb4e05012de483c7761a5",
        "name": "2014 World GDP and Population (Static)",
        "description": "Fake data used in Klip samples. Originates from the Gallery.",
        "refresh_interval": 14400,
        "date_last_refresh": "2016-06-20T11:56:08Z",
        "is_dynamic": false
      }]
    }
}

GET /datasource-instances/{id}

Description

Get the details for the specific data source ID.
Note: dates are returned in UTC time.

Permissions

dashboard.library

Parameters

id={datasource id}

Example Request

GET https://app.klipfolio.com/api/1/datasource-instances/0123456789abcdef0123456789abcdef

Example Response

{
"data": {
    "id":"0123456789abcdef0123456789abcdef"
    "datasource_id":"0123456789abcdef0123456789abcdef",
    "datasource_name":"Sample data",
    "date_last_refresh":"2014-11-18T19:34:36Z",
    "date_next_refresh":"2014-11-18T20:34:36Z",
    "refresh_fail_count":0,
    "data_size":14050
},
"meta": {
   "status": 200,
   "success": true
}
}

POST /datasource-instances

Description

Create a new data source instance based on a data source (specified as “datasource_id” in the post data). Data source instance properties can optionally be specified in the post data.

Permissions

datasource.create

Parameters

no_refresh
Note: The no_refresh parameter creates a data source with no instance, then creates an instance that doesn't refresh and then push data to it.

Example Request

POST https://app.klipfolio.com/api/1/datasource-instances -d {'datasource_id': '2342d101cee439562b794b07e9ebe9e2', 'properties': {'example': 'test', ...}}

Example Response

{
"meta": {
   "status": 200,
   "success": true

}
}

DELETE /datasource-instances

Description

Delete instances related to a specific data source.

Permissions

datasource.delete

Parameters

Example Request

DELETE https://app.klipfolio.com/api/1/datasource-instances/2342d101cee439562b794b07e9ebe9e2

Example Response

{
"meta": {
   "status": 200,
   "success": true
}
}
Suggest Edits

Data Source Instances Data

If a data source is a dynamic data source it will have more than one instance associated with it. A data source that has one instance will use the same ID for both the data source and the data source instance.

 

GET /datasource-instances/{id}/data

Description

Get the details for the specific data source ID.

Permissions

dashboard.library

Parameters

id={datasource id}

Example Request

GET https://app.klipfolio.com/api/1/datasource-instances/0123456789abcdef0123456789abcdef/data

Example Response

{
"data": {
   ga:continent,ga:visitors,ga: visits,ga: pageviews
   (not set),16,36,286
   Africa,157,545,3717
   Americas,4058,11956,105724
   Asia,824,2154,22109
   Europe,2102,8511,85399
   Oceania,544,2084,18580
},
"meta": {
   "status": 200,
   "success": true
}
}

PUT /datasource-instances/{id}/data

Description

Update the specified data source instance with data. Works with files only. For web accessible data sources use POST /@/refresh.

Permissions

dashboard.library

Parameters

id={datasource id}

Example Request

PUT https://app.klipfolio.com/api/1/datasource-instances/0123456789abcdef0123456789abcdef/data -d “<filename>”

Example Response:

{ "meta": { "success": true, "status": 200 }, "data": { } }
Suggest Edits

Data Source Instance Operations

Data source instance operations allow you to refresh a data source instance.

 

POST /datasource-instances/{id}/@/refresh

Description

Refresh the specified data source instance. This refresh operation queues the data source for refresh, but it does not necessarily refresh it instantly.

Permissions

dashboard.library

Parameters

id={datasource-instance id}
Note: The no_refresh parameter creates a data source with no instance, then creates an instance that doesn't refresh and then push data to it.

Example Request

POST https://app.klipfolio.com/api/1/datasource-instances/0123456789abcdef0123456789abcdef/@/refresh

Example Response

{
"data": {
    "op_requested":"refresh"
},
"meta": {
   "status": 200,
   "success": true
}
}
Suggest Edits

Data Source Instance Properties

Specifies how the API connects to the data source instance: end point URL, method. Each instance has its own set of properties. A data source instance is a copy of an original data source.

 

GET /datasource-instances/{id}/properties

Description

Get the properties for the specific

Permissions

dashboard.library

Parameters

id={datasource-instance id}

Example Request

GET https://app.klipfolio.com/api/1/datasource-instances/0123456789abcdef0123456789abcdef/properties

Example Response

{
"data": {
    "properties":{...}
},
"meta": {
   "status": 200,
   "success": true
}
}

PUT /datasource-instances/{id}/properties

Description

Create or update properties for this data source instance. If the specified property does not already exist it is created, otherwise the existing property is updated.

Permissions

dashboard.library

Parameters

id={datasource-instance id}

Example Request

PUT https://app.klipfolio.com/api/1/datasource-instances/0123456789abcdef0123456789abcdef/properties -d "{'properties':{'Stuff':'NewStuff'}}"

Example Response

{
"meta": {
   "status": 200,
   "success": true
}
}

DELETE /datasource-instances/{id}/properties

Description

Delete a specified data source instance.

Permissions

dashboard.library

Parameters

id={datasource-instance id}, name=<property name>

Example Request

DELETE https://app.klipfolio.com/api/1/datasource-instances/0123456789abcdef0123456789abcdef/properties?name=’Stuff’

Example Response

{
"meta": {
   "status": 200,
   "success": true
}
}

GET /groups

Description

Get the details for all groups

Permissions

user.manage

Parameters

client_id (string) — show only groups that belong to a specific client
external_id (string) — show only groups that have the specified external_id
full (true/false) — include associations in the listing (members) (Note: Only works when specifying external_id.)

Example Request

GET https://app.klipfolio.com/api/1/groups

Example Response

```

{
"meta": {
"success": true,
"status": 200
},
"data": {
"id": "c17db511dbc00421d0a093fc8c236064",
"company": "Hello",
"first_name": "Jane",
"last_name": "Doe",
"email": "jdoe@test.com",
"date_last_login": "2016-06-17T18:12:11Z",
"date_created": "2016-06-17T18:12:06Z",
"is_locked_out": false
}
}
``` 

GET /groups/{id}

Description

Get the details for the specific group.

Permissions

user.manage

Parameters

full (true/false) — include associations in the listing (members)

Example Request

GET https://app.klipfolio.com/api/1/groups/42c1abcdefgh54d44029ee5199111c2b?full=true

Example Response

```
{
"meta": {
"success": true,
"status": 200
},
"data": {
"id": "42c1accfbcfd54d44029ee5199805a9y",
"external_id": "group_api",
"company": "Self",
"name": "APIGroup",
"description": "Updated group",
"num_members": 1,
"members": [
{
"id": "2e21abc434a5169f9890576ec4d8e333",
"full_name": "Jane Doe"
}
]
}
}

``` 

POST /groups

Description

Create a new group.

Permissions

dashboard.library

Parameters

None.

Example Request

POST https://app.klipfolio.com/api/1/groups -d "{'name':'New Group', 'description':'A brand new group', ‘client_id’:’1234567890’, 'external_id':'group_api'}"

Example Response

{
"meta": {
   "success": true,
   "status": 201,
   "location": "/groups/0932d8270fb840f102d542331f200aca"
}
}

PUT /groups/{id}

Description

Update the specified group.

Permissions

dashboard.library

Parameters

name, description, external_id

Example Request

PUT https://app.klipfolio.com/api/1/groups/012345678998745641asfd -d "{description:'This is new'}"

Example Response

{
"meta": {
   "status": 200,
   "success": true
}
}

DELETE /groups/{id}

Description

Delete a group.

Permissions

user.manage

Parameters

None.

Example Request

DELETE https://app.klipfolio.com/api/1/groups/0987654321qwer -d

Example Response

{
"meta": {
      "status": 200,
      "success": true
  }
}
Suggest Edits

Groups Default Tabs

 

GET /groups/{id}/default-tabs

Description

Retrieve a list of default tabs (now called dashboards) for a specific group.

Permissions

user.manage

Parameters

tab_id (string) — show only dashboards that belong to a specific group
tab_name (string) — show dashboard name
description — information about the dashboard
can_edit — true/false
visibility — library, dashboard,permanent
index — tab position
id — default tab ID

Example Request

GET https://app.klipfolio.com/api/1.0/groups/bdd7b4d0a729704164ab4b38e788de21/default-tabs

Example Response

{ "meta": { "success": true, "status": 200 }, "data": { "tabs": [ { "tab_id": "fc67d8f1646b3333e1641e1085a5e555", "tab_name": "Group Sales", "description": null, "can_edit": false, "visibility": "permanent", "index": 1, "id": "caadadb4b08f36973c4446e459b14deb" } ] } }

GET /groups/{id}/default-tabs/{id}

Description

Retrieve the details for a specific group default tab.

Permissions

user.manage

Parameters

tab_id (string) — show only dashboards that belong to a specific group
tab_name (string) — show dashboard name
description — information about the dashboard
can_edit — true/false
visibility — library, dashboard,permanent
index — tab position
id — default tab ID
klips_shared
total_klips

Example Request

https://app.klipfolio.com/api/1.0/groups/dbb7b4d0a729704164ab4b38e799de11/default-tabs/caadadb4b08f36973c4446e459b14deb

Example Response

```
{
"meta": {
"success": true,
"status": 200
},
"data": {
"id": "caadadb4b08f36973c4446e459b14deb",
"tab_id": "fc67d8f1646b2306e1641e1085a5e704",
"tab_name": "Group Sales",
"description": null,
"can_edit": false,
"visibility": "permanent",
"index": 1,
"klips_shared": 1,
"total_klips": 2
}
}

``` 

POST /groups/{id}/default-tabs

Description

Add a new default dashboard to a specified group.

Permissions

user.manage

Parameters

None.

Example Request

https://app.klipfolio.com/api/1.0/groups/dbb7b4d0a729704164ab4b38e799de11/default-tabs -d "{'tab_id':'fc67d8f1646b2306e1641e1085a5e704','can_edit':true,'visibility':'dashboard','index':1}"

Example Response

{
  "meta": {
    "success": true,
    "status": 201,
    "location": "/groups/dbb7b4d0a729704164ab4b38e799de11/default-tabs/caadadb4b08f36973c4446e459b14deb"
  },
  "data": {}
}

PUT /groups/{id}/default-tabs/{id}

Description

Update an existing default dashboard for a specified group.

Permissions

dashboard.library

Parameters

name, description, external_id

Example Request

PUT https://app.klipfolio.com/api/1.0/groups/dbb7b4d0a729704164ab4b38e799de11/default-tabs/caadadb4b08f36973c4446e459b14deb -d "{'tab_id':'fc67d8f1646b2306e1641e1085a5e704',description:'Finance dashboard'}"

Example Response

{
  "meta": {
    "success": true,
    "status": 200
  },
  "data": {}
}

DELETE /groups/{id}/default-tabs/{id}

Description

Delete the specified group default dashboard.

Permissions

user.manage

Parameters

None.

Example Request

DELETE https://app.klipfolio.com/api/1.0/groups/dbb7b4d0a729704164ab4b38e799de11/default-tabs/caadadb4b08f36973c4446e459b14deb

Example Response

{
"meta": {
      "status": 200,
      "success": true
  }
}
Suggest Edits

Group Users

 

GET /groups/{id}/users

Description

Get the details for all users in a group.

Permissions

dashboard.library

Parameters

None.

Example Request

GET https://app.klipfolio.com/api/1/groups/0123456789abcdef0123456789abcdef/users

Example Response

{"meta":{"success":true,"status":200},
"data":
{
"users":[
{"id":"2e21eda434a5169f9890576ec4d8e789","first_name":"XYZ","last_name":"ZYX","email":"xyz@email.com"},...
]}}

PUT /groups/{id}/users/{id}

Description

Add the user to the group.

Permissions

dashboard.library

Parameters

group id (string)
userid (string)

Example Request

PUT https://app.klipfolio.com/api/1/groups/0123456789abcdef0123456789abcdef/users/asdbef012345789 -d "{'data':{'users':['id':'asdbef012345789']}}"

Example Response

{
"meta": {
   "status": 200,
   "success": true
}
}

DELETE /groups/{id}/users/{id}

Description

Delete a user from a group.

Permissions

user.manage

Parameters

None.

Example Request

DELETE https://app.klipfolio.com/api/1/groups/0987654321qwer/users/098765432211abc

Example Response

{
"meta": {
      "status": 200,
      "success": true
  }
}

GET /klips

Description

Get a list of all the Klips the user can access.

Permissions

dashboard.library

Parameters

client_id (string) — show only klips that belong to a specific client
datasource_id (string) — show only

Example Request

GET https://app.klipfolio.com/api/1/klips?client_id=0123456789abcdef0123456789abcdef

Example Response

{
   "data": {
       "klips": [
           {
               "description": "This is a sample klip",
               "id": "fedcba9876543210fedcba9876543210",
               "name": "sample klip"
           }
       ]
   },
   "meta": {
       "status": 200,
       "success": true
   }
}

GET /klips/{id}

Description

Get the details for the specified Klip.

Permissions

dashboard.library

Parameters

full (true/false) — include associations (share_rights)

Example Request

GET https://app.klipfolio.com/api/1/klips/0123456789abcdef0123456789abcdef?full=true

Example Response

{
   "data": {
       "company": "Klipfolio",
       "created_by": "12312312312312312312312312312312",
       "date_created": "2014-07-07T14:08:51Z",
       "description": "Table klip",
       "id": "0123456789abcdef0123456789abcdef",
       "last_updated": "2014-09-17T17:59:26Z",
       "name": "Inventory",
       "share_rights": [
         {
           "group_id": "5292aac2978f697f02f7ac4459e979fb",
           "group_name": "Managers",
           "can_edit": false
          },
        ]
   },
   "meta": {
       "status": 200,
       "success": true
   }
}

GET /klips/{id}/client-instances

Description

Returns a list of Klip instances for a specified Klip.

Permissions

client.access
dashboard.library

Parameters

{id} is the public id of the klip
full=[true/false] (full=true returns klip public id, name and client name)

Example Request

GET https://app.klipfolio.com/api/1/klips/0123456789abcdef0123456789abcdef/client-instances

Example Response

If full is false or omitted
{
  "meta": {
    "success": true,
    "status": 200
  },
  "data": {
    "klips": [
      "673e4f4a3cb3bc73fd5ca12d2bf4cd94",
      "fd17f1255a1544ab97fd2d9841d03e15"
    ]
  }
}

If full=true
{
  "meta": {
    "success": true,
    "status": 200
  },
  "data": {
    "klips": [
      {
        "id": "673e4f4a3cb3bc73fd5ca12d2bf4cd94",
        "name": "Sample Klip",
        "client_name": "Sample Company"
      },
      {
        "id": "fd17f1255a1544ab97fd2d9841d03e15",
        "name": "Sample Klip",
        "client_name": "Sample Company"
      }
    ]
  }
}

POST /klips

Description

Create a Klip; optionally include ‘client_id’ in the post data to create a Klip for a client. A schema may be specified by including ‘schema’ in the post data. If no schema is specified, the new Klip will have a simple default schema, which may be updated using the /klips/{id}/schema resource.

Permissions

klip.build

Fields

klip.build

Example Request

POST https://app.klipfolio.com/api/1/klips -d 
“{
 'name': 'Example', 
 'description': 'This is a new klip',
 ‘client_id’: ‘0123456789abcdef0123456789abcdef’
}”

Example Response

{
   "data": {},
   "meta": {
       "location": "/klips/ec6947ab9d07fdd6b9bb41551c79fd31",
       "status": 201,
       "success": true
   }
}

PUT /klips/{id}

Description

Update the specified klip details. To update the klip schema, use the /klips/{id}/schema resource.

Permissions

klip.edit

Fields

name, description

Example Request

PUT https://app.klipfolio.com/api/1/klips/ec6947ab9d07fdd6b9bb41551c79fd31 -d 
“{
 'name': 'Update', 
 'description': 'This is an updated klip',
}”

Example Response

{
   "data": {},
   "meta": {
       "status": 200,
       "success": true
   }
}

DELETE /klips/{id}

Description

Delete a specified Klip.

Permissions

klip.delete

Fields

name, description

Example

DELETE https://app.klipfolio.com/api/1/klips/01dd23b45fc67fd0123d81d16a0123e8 -d

Example Response

{
   "data": {},
   "meta": {
       "status": 200,
       "success": true
   }
}
Suggest Edits

Klip Annotations

Retrieve information on Klip annotations, create, update and delete annotations for specific Klips.

 

GET /klips/{id}/annotations

Description

Retrieve a list of annotations for a specified Klip.

Permissions

dashboard.annotation.view

Parameters

start_date (accepts Unix time format)
end_date (accepts Unix time format)

NOTE: Specify either none, one or both. For example, if start_date is not specified, it will retrieve all from the beginning of time; if end_date is not specified, it will retrieve all until the current date/time.

Example Request

GET https://app.klipfolio.com/api/1/klips/57ebf715c0fdd044e4191adaecb4fc6f/annotations

Example Response

{
  "meta": {
    "success": true,
    "status": 200
  },
  "data": {
    "annotations": [
      {
        "id": "12345eba2f065109fb88be86b2f9279e",
        "createdBy": {
          "id": "b1b1b11c7e4d34c6410d807564c470a7",
          "name": "Jane Doe"
        },
        "date_created": "2016-06-21T13:18:30Z",
        "body": "Order status for June"
      },
      {
        "id": "f1ea0a852348d0f606eabac4b2443477",
        "createdBy": {
          "id": "a5a9d31c7e4d34c6410d807564c470a7",
          "name": "Tamsin Douglas"
        },
        "date_created": "2016-06-21T13:32:05Z",
        "body": "Check Florida."
      }
    ]
  }
}

GET /klips/{id}/annotations/{id}

Description

Retrieve the details of an annotation for a specified Klip.

Permissions

dashboard.annotation.view

Parameters

None.

Example Request

GET https://app.klipfolio.com/api/1/klips/57ebf715c0fdd044e4191adaecb4fc6f/annotations/39874eba2f065109fb88be86b2f9279e

Example Response

{
  "meta": {
    "success": true,
    "status": 200
  },
  "data": {
    "id": "12345eba2f065109fb88be86b2f9279e",
    "createdBy": {
      "id": "b1b1b11c7e4d34c6410d807564c470a7",
      "name": "Jane Doe"
    },
    "date_created": "2016-06-21T13:18:30Z",
    "body": "Order status for June"
  }
}

POST /klips/{id}/annotations

Description

Create a a new annotation for a specified Klip.

Permissions

dashboard.annotation.edit

Fields

body: "" // String, required. Maximum 1024 characters.
NOTE: When creating an annotation, everything else uses a default: created_by is the authenticated user and date_created is the creation timestamp.

Example Request

POST https://app.klipfolio.com/api/1/klips/63d9abc8330ae256dac2e2f8c4371a8f/annotations -d "{'body':'I am writing an annotation'}"

Example Response

{
"meta":
{
"success":true,
"status":201,
"location":"/klips/63d9abc1234ae256dac2e2f8c4371a8f/annotations/23c618c919b1234d5f1d3359942559eb"
},
"data":{}
}
```

PUT /klips/{id}/annotations/{id}

Description

Update a specified Klip annotation.

Permissions

dashboard.annotation.edit

Fields

body: "" // String, required. Maximum 1024 characters.
NOTE 1: Editing an annotation does not update the date_created timestamp.
NOTE 2: The authenticated user must either be the creator of the annotation or have the "admin.annotation" permission to edit the annotation.

Example Request

PUT https://app.klipfolio.com/api/1/klips/63d9abc8330ae256dac2e2f8c4371a8f/annotations -d "{'body':'I am writing an annotation'}"

Example Response

{
   "data": {},
   "meta": {
       "status": 200,
       "success": true
   }
}

DELETE /klips/{id}/annotations/{id}

Description

Delete a specified annotation.

Permissions

dashboard.annotation.edit

Fields

None.

Example Request

DELETE https://app.klipfolio.com/api/1/klips/57ebf715c0fdd044e4191adaecb4fc6f/annotations/f1ea0a852348d0f606eabac4b2443477

Example Response

{
  "meta": {
    "success": true,
    "status": 200
  },
  "data": {}
}
Suggest Edits

Klip Client-Instance Operations

Updates the schema of client instances of Klips..

 

POST /api/1/klips/{id}/@/update_from_parent

Description

Updates a specified client instance of a Klip schema by replacing it with the schema of the original Klip.

Permissions

account.api
klip.import

Fields

{id} is the public id of the klip

Example Request

PUT 'https://app.klipfolio.com/api/1/klips/ec6947ab9d07fdd6b9bb41551c79fd31/@/update_from_parent'

Example Response

{
  "meta": {
    "success": true,
    "status": 200
  },
  "data": {
    "op_requested": "update_from_parent"
  }
}
Suggest Edits

Klip Schema

 

GET /klips/{id}/schema

Description

Get the schema for the specified klip.

Permissions

klip.edit

Parameters

None.

Example Request

GET https://app.klipfolio.com/api/1/klips/ec6947ab9d07fdd6b9bb41551c79fd31/schema

Example Response

{ "data": { "schema": { "components": [ { : } ], "id": "", "layoutConfig": ".region-2", "title": "LinkedIn Pie Chart", "version": "1", "workspace": { "datasources": [ "891e03e1e3f913a390e2e9c872c99cd5", "27a0aeeae2964f0e81e804cb55f43c86" ], "dimensions": { "w": 400 } } } }, "meta": { "status": 200, "success": true } }

PUT /klips/{id}/schema

Description

Update the schema for the specified Klip.

Permissions

klip.edit

Parameters

None.

Example Request

Note: The default schema is used when the Klip is created using POST/klips. 
PUT https://app.klipfolio.com/api/1/klips/ec6947ab9d07fdd6b9bb41551c79fd31/schema  -d 
   {
       "title": "Default",
       "id": "0123456789abcdef0123456789abcdef",
       "workspace": {
          "datasources": []
       },
       "components": [
          {
             "type": "simple_value",
             "displayName": "Value",
             "id": "8c79ad9b-4",
             "components": [
                {
                   "type": "label",
                   "displayName": "Primary Value",
                   "size": 2,
                   "fmt": "txt",
                   "role": "primary",
                   "id": "e0c29d78-5",
                   "formulas": [],
                   "data": [
                      []
                   ]
                },
                {
                   "type": "label",
                   "displayName": "Secondary Value",
                   "size": 1,
                   "role": "secondary",
                   "id": "4d34c828-6",
                   "formulas": [],
                   "data": []
                }
             ]
          }
       ]
    }

Example Response

{
   "data": {},
   "meta": {
       "status": 200,
       "success": true
   }
}
Suggest Edits

Klip Share Rights

 

GET /klips/{id}/share-rights

Description

Get a list of share rights for the specified Klip.

Permissions

dashboard.library

Parameters

None.

Example Request

GET https://app.klipfolio.com/api/1/klips/ec6947ab9d07fdd6b9bb41551c79fd31/share-rights

Example Response

{
   "data": {
       "share_rights": []
   },
   "meta": {
       "status": 200,
       "success": true
   }
}

PUT /klips/{id}/share-rights

Description

Update the share rights for the specified Klip. If the Klip is not already shared with the specified group, a new share-right is created, otherwise the existing share-right is updated.

Permissions

klip.share

Fields

groups

Example Request

PUT https://app.klipfolio.com/api/1/klips/ec6947ab9d07fdd6b9bb41551c79fd31/share-rights -d 
“{
 'groups': [
     {
       ‘group_id’:’0123456789abcdef0123456789abcdef’,
      ‘can_edit’:true
     }
  ]
}”

Example Response

{
   "data": {},
   "meta": {
       "status": 200,
       "success": true
   }
}

DELETE /klips/{id}/share-rights

Description

Delete a group’s share rights for the specified Klip.

Permissions

klip.share

Parameters

None.

Example Request

DELETE https://app.klipfolio.com/api/1/klips/ec6947ab9d07fdd6b9bb41551c79fd31/share-rights -d 
“{
 'groups': [
     {‘group_id’:’0123456789abcdef0123456789abcdef’,
      ‘can_edit’:true}
  ]
}”

Example Response

{
   "data": {},
   "meta": {
       "status": 200,
       "success": true
   }
}

POST /klips/{id}/@/import

Description
Permissions
Resource URL
Fields
Response codes

Import the specified klip and its associated data sources into the specified client account. The location of the imported klip is returned on successful completion.
klip.import
https://app.klipfolio.com/api/1.0/klips/{id}/@/import
None.
400 — missing client_id
401 — access denied to users with no share right and users from other companies
403 — klip is not shared with group_id
404 — {id} or client_id not found

Permissions

klip.import

Fields

None.

Example Request

POST https://app.klipfolio.com/api/1/klips/ec6947ab9d07fdd6b9bb41551c79fd31/@/import -d 
“{
  ‘client_id’:’0123456789abcdef0123456789abcdef’
}”

Example Response

{
   "data": {},
   "meta": {
       "status": 201,
       “location”: “/klips/01ab123012cd30123987330123da67e2”,
       "success": true
   }
}
Suggest Edits

Profile

View information about the authenticated user account.

 

GET /profile

Description

Retrieve information about the authenticated user account.

When the full parameter is set to true, the information includes associations (tab instances, dashboard properties, permissions for the authenticated user account).

Permissions

Parameters

full (true/false) — include associations in the listing (tab instances, dashboard properties, permissions).
Default is false.

Example Request when full = false

GET https://app.klipfolio.com/api/1/profile/011oct56d97775c3f18d281e3e3c0ggf

Example Response

{
    "data": {
    "id": "012feb56d97275c3f18d281e3e3c0ffd",
    "company": { "id": "3c9bf419ff803d7303e3db735f0fe20d", "name": "Test Inc." },
    "first_name": "John",
    "last_name": "Doe",
    "email": "jdoe@example.com",
    "date_last_login": "2016-04-11T15:29:49Z",
    "date_created": "2016-04-11T15:22:51Z",
    "is_locked_out": false
  }
}

Example Request when full = true

GET https://app.klipfolio.com/api/1/profile/011oct56d97775c3f18d281e3e3c0ggf?full=true

Example Response

{
     "data": {
    "id": "012feb56d97275c3f18d281e3e3c0ffd",
    "company": { "id": "3c9bf419ff803d7303e3db735f0fe20d", "name": "Test Inc." },
    "first_name": "John",
    "last_name": "Doe",
    "email": "jdoe@example.com",
    "date_last_login": "2016-04-11T15:29:49Z",
    "date_created": "2016-04-11T15:22:51Z",
    "is_locked_out": false,
    "tab_instances": [
      {
        "id": "9ebf35d99804cade918362557136abe2",
        "tab_id": "99e6e6a668f77e7080994741d3e934ae",
        "name": "How To: Klip Template Gallery",
        "context": "desktop",
        "layout": { "type": "", "state": { } }
      }
}
Suggest Edits

Roles

View, create, update and manage roles associated with your account.

 

GET /roles

Description

Retrieve all of the roles in the company.

Permissions

user.manage

Parameters

client_id (string) — show only roles that belong to a specific client

Example Request

GET https://app.klipfolio.com/api/1/roles

Example Response

{
"data": {
    "roles":[
    {"id":"12345678901234567890123abcde",
     "name":"Admin",
     "description":"Manage all assets, users, groups, roles, and account settings."},
    {...}
]
},
"meta": {
   "status": 200,
   "success": true
}
}

GET /roles/{id}

Description

Get the details for the specific role id.

Permissions

user.manage

Parameters

full (true/false) — include associations in the listing (users, num_users, permissions)

Example Request

GET https://app.klipfolio.com/api/1/roles/0123456789abcdef0123456789abcdef

Example Response

{
"data": {
    "id":"0123456789abcdef0123456789abcdef",
    "company":"N/A",
    "name":"View-Only",
    "description":"View-only dashboard with no customization."
},
"meta": {
   "status": 200,
   "success": true
}
}

PUT /roles/{id}

Description

Update the specified role. Permissions specified will replace existing permissions.

Permissions

user.manage

Fields

name, description, permissions

Example Request

PUT https://app.klipfolio.com/api/1/roles/abcdef9876543210 — d “{ 'name': Updated Name', 'description': 'Updated description', 'permissions':['klip.build','klip.edit']}”

Example Response

{
"meta": {
   "status": 200,
   "success": true
}
}

POST/roles/{id}

Description

create custom role

Permissions

user.manage

Fields

name, description, permissions

Example Request

POST https://app.klipfolio.com/api/1/roles —d “{ 'name': My New Role', 'description': 'This is a description', 'permissions':['klip.build','klip.edit']}”

Example Response

{
"meta": {
   "status": 200,
   "success": true
}
}

DELETE /roles/{id}

Description

Delete the specific role

Permissions

user.manage

Parameters

None.

Example Request

DELETE https://app.klipfolio.com/api/1/roles/0123456789abcdef0123456789abcdef

Example Response

{
"meta": {
      "status": 200,
      "success": true
  }
}
Suggest Edits

Role Users

View, update and manage users that belong to a specific role.

 

GET /roles/{id}/users

Description

Get a list of all the users associated with this role.

Permissions

user.manage

Parameters

role_id={id}

Response codes

401 — access denied
404 — role id not found

Example Request

GET https://app.klipfolio.com/api/1/roles/fedcba9876543210fedcba9876543210/users

Example Response

{
 "data": {
     "users": [
         {
"first_name":"John",
"last_name":"Smith",
"email":"jsmith@emailXYZ.com"
         }
     ]
 },
 "meta": {
     "status": 200,
     "success": true
 }
}

PUT /roles/{id}/users/{id}

Description

Add a user to the role.

Permissions

user.manage

Parameters

role_id={id}, user_id={id}

Response codes

400 — missing user id
401 — access denied to non-admins and users from other companies)
403 — user already has role
404 — user id or role id not found

Example Request

PUT https://app.klipfolio.com/api/1/roles/fedcba9876543210fedcba9876543210/users/9876543210abcdef -d "{'data':{'users':['id':'9876543210abcdef’]}}”

Example Response

{
 "data": {
     "users": [
         {
"id":"9876543210abcdef"
         }
     ]
 },
 "meta": {
     "status": 200,
     "success": true
 }
}

DELETE /roles/{id}/users/{id}

Description

Delete the specific user from the role

Permissions

user.manage

Parameters

None.

Response codes

400 — missing user id
401 — access denied to non-admins and users from other companies
403 — user does not have role
403 — admin role must have one or more users
404 — user id or role id not found

Example Request

DELETE https://app.klipfolio.com/api/1/roles/0123456789abcdef0123456789abcdef/users/0123456789abc

Example Response

{
"meta": {
      "status": 200,
      "success": true
  }
}
Suggest Edits

Role Permissions

View, update and manage permissions associated with a role.

 

GET /roles/{id}/permissions

Description

Get a list of all the role’s permissions.

Permissions

user.manage

Parameters

role_id={id}

Example Request

GET https://app.klipfolio.com/api/1/roles/fedcba9876543210fedcba9876543210/permissions

Example Response

{
 "data": {
"permissions":["account.api","account.eventlog","account.profile","account.settings","account.tokens","admin.annotation","admin.client","admin.datasource","admin.klip","admin.tab","client.access","client.build","client.delete","client.edit","client.login","client.share","dashboard.annotation.edit","dashboard.annotation.view","dashboard.ds_warning.view","dashboard.fullscreen","dashboard.klip","dashboard.library","dashboard.links","dashboard.tab","dashboard.theme","datasource.create","datasource.delete","datasource.download","datasource.edit","datasource.import","datasource.share","klip.build","klip.delete","klip.download","klip.edit","klip.email","klip.embed","klip.import","klip.share","tab.build","tab.delete","tab.download","tab.edit","tab.email","tab.import","tab.push","tab.share","user.manage"]
  },
 "meta": {
     "status": 200,
     "success": true
 }
}

PUT /roles/{id}/permissions

Description

Update the permissions associated with the role.

Permissions

user.manage

Parameters

role_id={id}

Example Request

PUT https://app.klipfolio.com/api/1/roles/fedcba9876543210fedcba9876543210/permissions -d {"permissions":["account.api","account.eventlog","account.profile","account.settings","account.tokens","admin.annotation","admin.client","admin.datasource","admin.klip","admin.tab","client.access","client.build","client.delete","client.edit","client.login","client.share","dashboard.annotation.edit","dashboard.annotation.view","dashboard.ds_warning.view","dashboard.fullscreen","dashboard.klip","dashboard.library","dashboard.links","dashboard.tab","dashboard.theme","datasource.create","datasource.delete","datasource.download","datasource.edit","datasource.import","datasource.share","klip.build","klip.delete","klip.download","klip.edit","klip.email","klip.embed","klip.import","klip.share","tab.build","tab.delete","tab.download","tab.edit","tab.email","tab.import","tab.push","tab.share","user.manage"]}

Example Response

{
 "meta": {
     "status": 200,
     "success": true
 }
}

DELETE /roles/{id}/permissions

Description

Delete a specific role permission.

Permissions

user.manage

Parameters

None.

Example Request

DELETE https://readme.io/.com/api/1/roles/0123456789abcdef0123456789abcdef/permissions?name='klip.delete'

Example Response

{
"meta": {
      "status": 200,
      "success": true
  }
}
Suggest Edits

Tabs (now called dashboards)

View, create, update and manage tabs (dashboards) associated with the requesting company.

 

GET /tabs

Description

Get a list of all the tabs to which the user has access.

Permissions

dashboard.library

Parameters

client_id (string) — show only tabs that belong to a specific client

Example Request

GET https://app.klipfolio.com/api/1/tabs

Example Response

{
 "data": {
       "id": "3c7b25bd388fc9a348d7c3e136986efb",
       "name": "Examples",
       "description": "Example Klips"
  },
 "meta": {
     "status": 200,
     "success": true
 }
}

GET /tabs/{id}

Description

Get the details for the specific tab.

Permissions

dashboard.library

Parameters

full (true/false) — include associations in the listing (klip_instances, share_rights)

Example Request

GET https://app.klipfolio.com/api/1/tabs/012345679012345978abcd

Example Response

{
 "data": {
       "id": "012345679012345978abcd",
        "company":"What Inc.",
   "name":"Examples",
   "description":”Example Klips”,
   "created_by":"2e21eda434a5169f9890576ec4d8e789",
   "last_updated":"2014-11-13T21:38:27Z"
  },
 "meta": {
     "status": 200,
     "success": true
 }
}

POST /tabs

Description

Create a new tab.

Permissions

tab.build

Fields

name, description, client_id (optional)

Example Request

POST https://app.klipfolio.com/api/1/tabs -d "{'name':'New Tab', 'description':'This is a new tab'}"

Example Response

{
  "meta": {
     "status": 201,
     "success": true,
     “location”:”/tabs/ab123456789”
 }
}

PUT /tabs/{id}

Description

Update the specified tab.

Permissions

tab.edit

Parameters

full (true/false) — include associations in the listing (klip_instances, share_rights)

Example Request

PUT https://app.klipfolio.com/api/1/tabs/abcde0123456 -d "{'name':Update Tab', 'description':'Updated tab'}"

Example Response

{
  "meta": {
     "status": 200,
     "success": true
 }
}

DELETE /tabs/{id}

Description

Delete tab.

Permissions

tab.delete

Parameters

name, description

Example Request

DELETE https://app.klipfolio.com/api/1/tabs/0987654321qwer

Example Response

{
"meta": {
      "status": 200,
      "success": true
  }
}
Suggest Edits

Tab Klip Instances

A tab (now called dashboard) may have more than one Klip instance associated with it. A Klip instance is a copy of a Klip in a user’s tab.

 

GET /tabs/{id}/klip-instances

Description

Get a list of the Klip instances associated with the tab.

Permissions

dashboard.tab

Parameters

tab id={id}

Example Request

GET https://app.klipfolio.com/api/1/tabs/fedcba9876543210fedcba9876543210/klip-instances

Example Response

{
 "data": {
  "klip_instances":
 [{
   "id":"04462abd3a38372173645f3b50128596",   
   "klip_id":"b2f4179cdc4f5a022a80310fe93b1022",
   "name":"Visits and Goals"
 }]
  },
 "meta": {
     "status": 200,
     "success": true
 }
}

PUT /tabs/{id}/klip-instances

Description

Add a Klip to a tab. The Klip id is used instead of the Klip instance id.
Note: If region and position are not included, they default to 1 and 0 respectively.

Permissions

dashboard.tab

Fields

Klips

Example Request

PUT https://app.klipfolio.com/api/1.0/tabs/ca74a78906543be66b2z9c123e76b1bc/klip-instances -d {'klips': [{'klip_id': 'd012d123b56123d1234ef12c8f12c123', 'region': 0, 'position': 1}]}

Example Response

{
  "meta": {
    "success": true,
    "status": 200
  },
  "data": {
    "klip_instances": [
      {
        "id": "12a123c123ef12333cbf7d3d864f674",
        "klip_id": "d012d123b56123d1234ef12c8f12c123",
        "name": "Klipfolio API, Client Dynamic, filter Active"
      }
    ]
  }
}

DELETE /tabs/{id}/klip-instances/

Description

Delete a Klip that is on a tab.

Permissions

dashboard.tab

Resource URL

https://app.klipfolio.com/api/1.0/tabs/{id}/klip-instances/

Parameters

None.

Example Request

DELETE https://app.klipfolio.com/api/1.0/tabs/ca12b12345678ie91b2o9c123e89b7bc/klip-instances/c5t8i9abc4ca99613a1bd1bf5c123ce4

Example Response

{
  "meta": {
    "success": true,
    "status": 200
  },
  "data": {}
}
Suggest Edits

Tab Layout

Change the layout schema of a tab (now called a dashboard).

 

GET /tabs/{id}/layout

Description

Get the layout of a tab.

Permissions

dashboard.share

Parameters

tab id={id}

Example Request

GET https://app.klipfolio.com/api/1/tabs/fedcba9876543210fedcba9876543210/layout

Example Response

{
 "data": {
     "type": "30_60",
     "state": {
         "0123457890123456789abcde":{"region":"region-1","idx":0},
         ...
        }
  },
 "meta": {
     "status": 200,
     "success": true
 }
}

PUT /tabs/{id}/layout

Description

Update the layout of the tab. The layout “type” refers to the size and number of Klip columns on the tab. The layout “state” is a JSON object representing the position of each Klip on the tab.

Permissions

dashboard.share

Fields

tab id={id}

Example Request

PUT https://app.klipfolio.com/api/1/tabs/fedcba9876543210fedcba9876543210/layout -d "{'type':'100', 'state':{'04462abd3a38372173645f3b50128596':{'region': 'region-1', 'idx': 1}}}"

Example Response

{
 "meta": {
     "status": 200,
     "success": true
 }
}
Suggest Edits

Tab Share Rights

View, update and manage tab (now called dashboard) share rights.

 

GET /tabs/{id}/share-rights

Description

Get a list of the tab’s share rights.
tab.share
https://app.klipfolio.com/api/1.0/tabs/{id}/share-rights
tab_id (string)
401 — access denied
404 — tab id not found

Permissions

tab.share

Parameters

tab_id (string)

Example Request

GET https://app.klipfolio.com/api/1/tabs/fedcba9876543210fedcba9876543210/share-rights

Example Response

{
 "data": {
       "share_rights":[{
          "group_id":"f3db5f3a05d53c60032ec0730759a785",
          "group_name":"First Test Group",
          "can_edit":false
          "vis_dashboard":"dashboard"
         }]
  },
 "meta": {
     "status": 200,
     "success": true
 }
}

PUT /tabs/{id}/share-rights

Description

Update a tab's share rights. If the tab is not already shared with the specified group a new share right is created, otherwise the existing right is updated.

Permissions

tab.share

Fields

groups, group_id, can_edit (true/false)

Example Request

PUT https://app.klipfolio.com/api/1/tabs/fedcba9876543210fedcba9876543210/share-rights -d “{'groups': [{'group_id': 'a9dff9e0b37ecd0fff24cba32ab88223', 'can_edit': true}, {'group_id': 'c4283e83f928255074e7c1aa3c35c30b', 'can_edit': false}]}”

Example Response

{
 "meta": {
     "status": 200,
     "success": true
 }
}

DELETE /tabs/{id}/share-rights/{group-id}

Description

Revoke access to a group tab.

Permissions

tab.share

Parameters

None.

Example Request

DELETE https://app.klipfolio.com/api/1/tabs/0987654321qwer/share-rights/098765432211abc

Example Response

{
"meta": {
      "status": 200,
      "success": true
  }
}
Suggest Edits

Tab Operations

Perform tasks related to importing tabs (now called dashboards).

 

POST /tabs/{id}/@/import

Description

Import the tab into the client account specified in the post data by the client id. All related Klips will also be imported along with the tab. The location of the newly imported tab is returned on success.

Permissions

tab.import

Fields

tab id={id}

Example Request

POST https://app.klipfolio.com/api/1/tabs/fedcba9876543210fedcba9876543210/@/import -d 
“{
‘client_id’: ‘0123456789abcdef0123456789abcdef’
}”

Example Response

{
 "meta": {
 "status": 201,
 “location”: “/tabs/ 5acc0711426cc202e61aa2ce9bc8dfd5”},
 "data": { "op_requested": "import" }
 }
}
Suggest Edits

Users

View, create, update and manage users belonging to the requesting company.

 

GET /users

Description

Get a list of all the users in the client account.

Permissions

user.manage

Parameters

client_id (string) — show only users belonging to a specific client
email (string) — search for a user by email address
external_id (string) — show only users that have the specified external_id
full (true/false) — include associations (tab_instances, properties) (only works when specifying external_id)
include_roles (true/false) — include the user’s roles
include_groups (true/false) — include the user’s groups

Example Request

GET https://app.klipfolio.com/api/1/users

Example Response (external_id is not displayed if it is null)

{
   "data": {
       "users": [
           {
               "id": "ab05f4a011e6a93fb307f4e3e970c3c0",
                "first_name": "Trial",
                "last_name": "User",
                 "email": "jdoe@klipfolio.com",
                 "date_last_login": "2016-06-03T17:05:54Z"
           }
       ]
   },
   "meta": {
       "status": 200,
       "success": true
   }
}

GET /users/{id}

Description

Get details for the specified user.

Permissions

user.manage

Parameters

full (true/false) — include associations (tab_instances, groups, roles, properties)

Example Request

GET https://app.klipfolio.com/api/1/users/0123456789abcdef0123456789abcdef?full=true

Example Response (external_id is not displayed if it is null)

{
  "meta": {
    "success": true,
    "status": 200
  },
  "data": {
    "id": "c17db511dbc00421d0a093fc8c236064",
    "company": "Hello",
    "first_name": "Jane",
    "last_name": "Doe",
    "email": "Doe+12@klipfolio.com",
    "date_last_login": "2016-06-17T18:12:11Z",
    "date_created": "2016-06-17T18:12:06Z",
    "is_locked_out": false,
    "tab_instances": [
      "a46d2e3fb99072c19f7997128e3e6f66",
      "b8b305c4ba9287b7fbabc40831744444"
    ],
    "groups": [
      {
        "id": "0016c12db53a58901bf19fd5e285c438",
        "name": "Trial Users"
      }
    ],
    "roles": [
      "26a3d3fb4cd6bf23d35b4126be26e5f3"
    ],
    "properties": {}
  }
}

POST /users

Description

Create a new user, optionally for a client.
user.manage

Permissions

user.manage

Fields

first_name, last_name, roles, email, password (optional), external_id (optional), client_id (optional), send_email (default is false).

Example Request

Note: Optionally include 'client_id' in the post data to create a user for a client, optionally include ‘external_id’ in the post data to add an external id to the new user, optionally include 'password' in the post data to set the password, optionally include ?send_email=true in the post data to send a welcome email to the user.

POST https://app.klipfolio.com/api/1/users -d 
"{
'client_id': '0123456789abcdef0123456789abcdef', 
'first_name': 'Jane', 
'last_name': 'Doe', 
'email': 'jdoe@klipfolio.com', 
'roles': ['0123456789abcdef0123456789abcdef'],
'password': 'tempPassword'
}"

Example Response

{
   "data": {},
   "meta": {
       "location": "/users/0123456789abcdef0123456789abcdef",
       "status": 201,
       "success": true
   }
}

PUT /users/{id}

Description

Update the specified user.

Permissions

user.manage

Fields

first_name, last_name, external_id, email

Example Request (only fields to be updated need to be sent)

PUT https://app.klipfolio.com/api/1/users/0123456789abcdef0123456789abcdef -d 
"{
'first_name': 'Janet', 
}"

Example Response

{
   "data": {},
   "meta": {
       "status": 200,
       "success": true
   }
}

DELETE /users/{id}

Description
Permissions
Resource URL
Parameters
Response codes

Delete the specified user.
user.manage
https://app.klipfolio.com/api/1.0/users
none
400 — missing {id}
401 — access denied to non-admins and users from other companies
403 — forbidden to: delete your own account, delete the super admin, delete the technical contact, delete the business contact 404 ({id} not found

Permissions

user.manage

Parameters

None.

Example Request

DELETE https://app.klipfolio.com/api/1/users/0123456789abcdef0123456789abcdef

Example Response

{
   "data": {},
   "meta": {
       "status": 200,
       "success": true
   }
}
Suggest Edits

User Groups

View and manage groups to which a user belongs.

 

GET /users/{id}/groups

Description

Retrieve the list of groups to which the specified user belongs.

Permissions

user.manage

Parameters

None.

Example Request

GET https://app.klipfolio.com/api/1/users/0123456789abcdef0123456789abcdef/groups

Example Response

{
   "data": {
       "groups": [
           {
               "description": All managers in the company,
               "id": "0123456789abcdef0123456789abcdef",
               "name": "Managers"
           },
           {
               "description": "All users in the company",
               "id": "0123456789abcdef0123456789abcdef",
               "name": "All"
           }
       ]
   },
   "meta": {
       "status": 200,
       "success": true
   }

PUT /users/{id}/groups/{id}

Description

Add a specified user to one group at a time.

Permissions

user.manage

Fields

groups, group_id, can_edit (true/false)

Example Request

PUT https://app.klipfolio.com/api/1/users/0123456789abcdef0123456789abcdef/groups/123a2d1234e123f2c7b1234123412341 -d

Example Response

{
   "meta": {
       "status": 200,
       "success": true
   }
}

DELETE /users/{id}/groups/{id}

Description

Delete a specified user from specified groups.

Permissions

user.manage

Parameters

None.

Example Request

DELETE https://app.klipfolio.com/api/1/users/0123456789abc/groups/01234123411qwer

Example Response

{
"meta": {
      "status": 200,
      "success": true
  }
}
Suggest Edits

User Operations

Perform tasks associated with users including resending invitations and resetting passwords.

 

POST /users/{id}/@/resend-invite

Description

Resend the invitation email to a new user.

Permissions

user.manage

Fields

None.

Example Request

POST https://app.klipfolio.com/api/1/users/0123456789abcdef0123456789abcdef/@/resend-invite

Example Response

{
 "meta": { "success": true, "status": 200 },
 "data": { "op_requested": "resend-invite" }
}

POST /users/{id}/@/reset-password

Description

Reset a user password.

Permissions

user.manage

Fields

None.

Example Request

POST https://app.klipfolio.com/api/1/users/0123456789abcdef0123456789abcdef/@/reset-password

Example Response

{
 "meta": { "success": true, "status": 200 },
 "data": { "op_requested": "reset-password" }
}
Suggest Edits

User Properties

View, create, update and manage user properties.

 

GET /users/{id}/properties

Description

Get a list of the user’s properties.

Permissions

user.manage

Parameters

user id={id}

Example Request

GET https://app.klipfolio.com/api/1/users/fedcba9876543210fedcba9876543210/properties

Example Response

{
 "data": {
       "properties":{}
  },
 "meta": {
     "status": 200,
     "success": true
 }
}

PUT /users/{id}/properties

Description

Create or update properties for this user. If the specified property does not already exist, it is created. If the property currently exists, it is updated.

Permissions

user.manage

Fields

properties

Example Request

PUT https://app.klipfolio.com/api/1/users/fedcba9876543210fedcba9876543210/properties -d

Example Response

{
 "data": {},
 "meta": {
     "status": 200,
     "success": true
 }
}

DELETE /users/{id}/properties

Description

Delete properties associated with a user.

Permissions

user.manage

Parameters

None.

Example Request

DELETE https://app.klipfolio.com/api/1/users/0123456789abc/properties?name=Stuff

Example Response

{
"meta": {
      "status": 200,
      "success": true
  }
}
Suggest Edits

User Roles

View, update and manage user roles.

 

GET /users/{id}/roles

Description
Permissions
Resource URL
Parameters
Response codes

Get a list of the user’s roles.
user.manage
https://app.klipfolio.com/api/1.0/users/{id}/roles
user id={id}
401 — access denied
404 — user id not found

Permissions

user.manage

Parameters

user id={id}

Example Request

GET https://app.klipfolio.com/api/1/users/fedcba9876543210fedcba9876543210/roles

Example Response

{
 "data": {
       "id":"fedcba9876543210fedcba9876543210",
       "name":"Admin",
       "description":"Manage all assets, users, groups, roles, and account settings."
  },
 "meta": {
     "status": 200,
     "success": true
 }
}

PUT /users/{id}/roles/{id}

Description

Assign a user to a role.

Permissions

user.manage

Parameters

user id={id}, roles id={id}

Example Request

PUT https://app.klipfolio.com/api/1/users/fedcba9876543210fedcba9876543210/roles/abcdef123456 -d “{'id': ['f70a1cd9817b85ffa252a7b4280f0223’]}”

Example Response

{
  "meta": {
     "status": 200,
     "success": true
 }
}

DELETE /users/{id}/roles/{id}

Description

Delete the user from a specified role.

Permissions

user.manage

Parameters

None.

Example Request

DELETE https://app.klipfolio.com/api/1/users/0123456789abc/roles/0123456789abdef0123456789abcdef

Example Response

{
"meta": {
      "status": 200,
      "success": true
  }
}
Suggest Edits

User Tab Instances

View, update and manage tab (now called dashboard) instances. An instance is a copy of one tab that is in a user's account; a dashboard is a collection of tab instances.

 

GET /users/{id}/tab-instances

Description

Retrieve a list of the user’s tab instances.

Permissions

user.manage

Parameters

user id={id}, roles id={id}

Example Request

GET https://app.klipfolio.com/api/1/users/fedcba9876543210fedcba9876543210/tab-instances

Example Response

{
  "meta": {
    "success": true,
    "status": 200
  },
  "data": {
    "tab_instances": [
      {
        "id": "789ae076049d6b835200ea2419411d4c",
        "tab_id": "cf66f1679068052446987c9ec99d3e91",
        "name": "Adwords",
        "context": "desktop"
      },
      {
        "id": "81740be2e4746a4bb79dd0aab3cc4652",
        "tab_id": "a538858966297b776216141579bb0dbe",
        "name": "API Tab",
        "context": "desktop"
      }
 ]
}

PUT /users/{id}/tab-instances

Description

Add one or more tabs to a user’s dashboard. Use tab IDs not tab instance IDs.

Permissions

user.manage

Fields

tab_ids

Example Request

PUT https://app.klipfolio.com/api/1.0/users/ab8c07b4d6bb53acd1234567c36213be/tab-instances -d {"tab_ids": ["ab12a34580678e912d9c365e12b1bc"]}

Example Response

{
  "meta": {
    "success": true,
    "status": 200
  },
  "data": {
    "tab_instances": [
      {
        "id": "4a123b834414868061a9045a3750abcd",
        "tab_id": "ab12a34580678e912d9c365e12b1bc",
        "name": "HTML Test"
      }
    ]
  }
}

DELETE /users/{id}/tab-instances/{id}

Description

Delete a user’s tab instance.

Permissions

user.manage

Parameters

None.

Example Request

DELETE https://app.klipfolio.com/api/1/users/0123456789abc/tab-instances/0123456789abc

Example Response

{
"meta": {
      "status": 200,
      "success": true
  }
}
Suggest Edits

List of Role Permissions

The permissions below are used when updating roles (see PUT for the /roles resource above).

 
Permission
Permitted Action

client.build

Create clients

client.access

Access client accounts

client.edit

Edit clients

client.share

Share clients

client.delete

Delete clients

client.login

Login with client credentials

dashboard.tab

Add, remove and rearrange tabs

dashboard.klip

Add, remove and rearrange Klips

dashboard.theme

Switch to a new theme

dashboard.fullscreen

Enter full-screen mode

dashboard.annotation.view

See annotations

dashboard.annotation.edit

Add and edit annotations

dashboard.library

Access library

dashboard.links

See Getting Started links

datasource.create

Create data sources

datasource.share

Share data sources

datasource.download

Download data sources

datasource.import

Import data sources (only available for partners)

datasource.edit

Edit data sources

datasource.delete

Delete data sources

klip.build

Build Klips

klip.share

Share Klips

klip.email

Email Klips

klip.embed

Embed Klips

klip.download

Download Klips

klip.import

Import Klips (only available for partners)

klip.edit

Edit Klips

klip.delete

Delete Klips

tab.build

Build tabs

tab.share

Share tabs

tab.email

Email tabs

tab.download

Download tabs

tab.import

Import tabs (only available for partners)

tab.edit

Edit tabs

tab.delete

Delete tabs

tab.push

Manage tab visibility

user.manage

Manage all users, groups, and roles