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.
Looking for documentation on connecting to third-party application APIs?
If you want to bring data into your Klipfolio account from an external application's API, refer to our third-party service connector documentation.
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.
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.
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.
The current version of the Klipfolio API is 1.0 (1 is also accepted).
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.
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.
Some API requests include additional parameters that can be used. These are listed with the particular request in the reference guide.
View, create, update existing clients, and manage clients for all client accounts belonging to the requesting company.
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.
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/jsonUploading 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/jsonCreating 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\"]",
}
}Clients
View, create, update existing clients, and manage clients for all client accounts belonging to the requesting company.
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
Resource URL
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)
status (active, trial, setup, disabled) — show only clients that have the specified account status.
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
Description
Get the details for the specified client.
Resource URL
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
}
}
Description
Create a client.
Resource URL
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
}
}
```
Description
Update the specified client.
Permissions
client.edit
Resource URL
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
}
}
Description
Delete a client.
Permissions
client.delete
Resource URL
Parameters
None.
Example Request
DELETE https://app.klipfolio.com/api/1/clients/0123456789abcdef0123456789abcdef
Example Response
{
"data": {},
"meta": {
"status": 200,
"success": true
}
}
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
}
}
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
}
}
Client Features
View and update client features for all client accounts belonging to the requesting company.
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
}
]
}
}
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": {}
}
Client Properties
Manage a client's dashboard
Manage a client's dashboard 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" } }
}
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": { } }
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": { } }
Client Resources
View and update client resources for all client accounts belonging to the requesting company.
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
}
]
}
}
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": {}
}
Client Settings
View and set configurations for clients' accounts
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,
"dpn.env.date.language.tag": "fr-FR"
}
}
}
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"
Example Request
POST https://app.klipfolio.com/api/1/clients/0123456789abcdef0123456789abcdef/settings -d
Example Response
{
"meta": {
"success": true,
"status": 200
},
"data": {}
}
Data Sources
Viewing, creating, updating and managing data sources.
Description
Get a list of all the data sources to which the user has access.
Permissions
dashboard.library
Resource URL
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
},
]
}
}
Description
Get the details for the specific data source id.
Permissions
dashboard.library
Resource URL
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
}
Description
Create a data source. Data source properties can optionally be specified in the post data.
Permissions
datasource.create
Resource URL
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": { }
}
Description
Update the specified data source.
Permissions
datasource.edit
Resource URL
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.
Description
Delete the data source associated with a specific data source ID.
Permissions
datasource.delete
Resource URL
Parameters
id={datasource id}
Example Request
DELETE https://app.klipfolio.com/api/1/datasources/0123456789abcdef0123456789abcdef
Example Response
{
"data": {},
"meta": {
"status": 200,
"success": true
}
}
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.
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
}
}
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
}
}
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" }
}
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": {}
}
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.
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
}
}
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
}
Description
Delete a specific datasource property.
Permissions
datasource.edit
Resource URL
Parameters
None.
Example Request
DELETE https://app.klipfolio.com/api/1/datasources/0123456789abcdef0123456789abcdef/properties?name='Stuff'
Example Response
{
"meta": {
"status": 200,
"success": true
}
}
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.
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": "4928fb1d95bfb4e02012de483c1234a5",
"datasource_id": "4928fb1d95bfb4e02012de483c1234a5",
"datasource_name": "Fake data used in Klip samples. Originates from the Gallery.",
"refresh_fail_count": 0
"data_size": 32564,
"date_last_refresh": "2016-06-20T11:56:08Z"
}]
}
}
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
}
}
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
}
}
Description
Delete instances related to a specific data source.
Permissions
datasource.delete
Parameters
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.
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
}
}
Description
Update the specified data source instance with data. Works with files and with raw data. For web accessible data sources use POST /@/refresh to get new data.
Permissions
dashboard.library
Parameters
id={datasource id}
Data Source Instance Operations
Data source instance operations allow you to refresh a data source instance.
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
}
}
Description
Queue multiple data sources for refresh in one API call.
Permissions
datasource.edit
Parameters
"datasources" = ["datasourceId1", "datasourceId2", ..., "datasourceIdN"]
List the data source IDs in your request body.
Example Request
POST https://app.klipfolio.com/api/1.0/datasources/@/refresh
{
"datasources" = ["1a12bc34de56abc12de3ab4c45de12a3", "2a12bc34de12abc12de3ab3c45de32a1", "3a12bc34de56cba32de1ab5c45de12b3"]
}
Example Responses
{
"meta": {
"success": true,
"status": 200
},
"data": {
"op_requested": "refresh",
"success": true,
"total_datasources_requested": 3,
"total_instances_requested": 5,
"queue_status": 200,
"total_instances_queued": 3,
}
}
{
"meta": {
"success": true,
"status": 200
},
"data": {
"op_requested": "refresh",
"success": true,
"total_datasources_requested": 2,
"total_instances_requested": 1,
"queue_status": 200,
"total_instances_queued": 1,
"failed_results": {
"description": "Some datasources/instances failed to queue.",
"invalid_datasources": {
"1234a1b23bc4d12345abc1a123ab2a2c": {
"error": "Data source not found: 1234a1b23bc4d12345abc1a123ab2a2c",
"status": 404,
"success": false
}
}
}
}
}
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.
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
}
}
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
}
}
Description
Delete a specified data source instance.
Permissions
dashboard.library
Resource URL
Parameters
id={datasource-instance id}, name=<property name>
Groups
Description
Get the details for all groups
Resource URL
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
}
}
```
Description
Get the details for the specific group.
Permissions
user.manage
Resource URL
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"
}
]
}
}
```
Description
Create a new group.
Permissions
dashboard.library
Resource URL
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"
}
}
Description
Update the specified group.
Permissions
dashboard.library
Resource URL
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
}
}
Description
Delete a group.
Permissions
user.manage
Resource URL
Parameters
None.
Groups 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"
}
]
}
}
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
}
}
```
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": {}
}
Description
Update an existing default dashboard for a specified group.
Permissions
dashboard.library
Resource URL
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": {}
}
Description
Delete the specified group default dashboard.
Permissions
user.manage
Parameters
None.
Group Users
Description
Get the details for all users in a group.
Permissions
dashboard.library
Resource URL
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"},...
]}}
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
}
}
Description
Delete a user from a group.
Permissions
user.manage
Parameters
None.
Klips
Description
Get a list of all the Klips the user can access.
Permissions
dashboard.library
Resource URL
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
}
}
Description
Get the details for the specified Klip.
Resource URL
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
}
}
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"
}
]
}
}
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
Resource URL
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
}
}
Description
Update the specified klip details. To update the klip schema, use the /klips/{id}/schema resource.
Permissions
klip.edit
Resource URL
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
}
}
Description
Delete a specified Klip.
Permissions
klip.delete
Resource URL
Fields
name, description
Klip Annotations
Retrieve information on Klip annotations, create, update and delete annotations for specific Klips.
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."
}
]
}
}
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"
}
}
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":{}
}
```
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
}
}
Description
Delete a specified annotation.
Permissions
dashboard.annotation.edit
Fields
None.
Klip Client-Instance Operations
Updates the schema of client instances of Klips..
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
Klip Schema
Description
Get the schema for the specified klip.
Permissions
klip.edit
Resource URL
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
}
}
Description
Update the schema for the specified Klip.
Permissions
klip.edit
Resource URL
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
}
}
Profile
View information about the authenticated user account.
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
Resource URL
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": { } }
}
}
Roles
View, create, update and manage roles associated with your account.
Description
Retrieve all of the roles in the company.
Permissions
user.manage
Resource URL
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
}
}
Description
Get the details for the specific role id.
Permissions
user.manage
Resource URL
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
}
}
Description
Update the specified role. Permissions specified will replace existing permissions.
Permissions
user.manage
Resource URL
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
}
}
Description
create custom role
Permissions
user.manage
Resource URL
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
}
}
Description
Delete the specific role
Permissions
user.manage
Resource URL
Parameters
None.
Role Users
View, update and manage users that belong to a specific role.
Description
Get a list of all the users associated with this role.
Permissions
user.manage
Resource URL
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
}
}
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
}
}
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
Role Permissions
View, update and manage permissions associated with a role.
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
}
}
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
}
}
Description
Delete a specific role permission.
Permissions
user.manage
Resource URL
https://app.klipfolio.com/api/1.0/roles/{id}/permissions?<field>=<value>
Parameters
None.
Tabs (now called dashboards)
View, create, update and manage tabs (dashboards) associated with the requesting company.
Description
Get a list of all the tabs to which the user has access.
Permissions
dashboard.library
Resource URL
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
}
}
Description
Get the details for the specific tab.
Permissions
dashboard.library
Resource URL
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
}
}
Description
Create a new tab.
Permissions
tab.build
Resource URL
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”
}
}
Description
Update the specified tab.
Permissions
tab.edit
Resource URL
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
}
}
Description
Delete tab.
Permissions
tab.delete
Resource URL
Parameters
name, description
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.
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
}
}
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"
}
]
}
}
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.
Tab Layout
Change the layout schema of a tab (now called a dashboard).
Description
Get the layout of a tab.
Permissions
dashboard.share
Resource URL
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
}
}
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
Resource URL
Fields
tab id={id}
Tab Operations
Perform tasks related to importing tabs (now called dashboards).
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
Resource URL
Fields
tab id={id}
Users
View, create, update and manage users belonging to the requesting company.
Description
Get a list of all the users in the client account.
Resource URL
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
}
}
Description
Get details for the specified user.
Permissions
user.manage
Resource URL
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": {}
}
}
Description
Create a new user, optionally for a client.
user.manage
Permissions
user.manage
Resource URL
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
}
}
Description
Update the specified user.
Permissions
user.manage
Resource URL
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
}
}
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
Resource URL
Parameters
None.
User Groups
View and manage groups to which a user belongs.
Description
Retrieve the list of groups to which the specified user belongs.
Permissions
user.manage
Resource URL
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
}
Description
Add a specified user to one group at a time.
Permissions
user.manage
Resource URL
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
}
}
Description
Delete a specified user from specified groups.
Permissions
user.manage
Parameters
None.
User Operations
Perform tasks associated with users including resending invitations and resetting passwords.
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" }
}
Description
Reset a user password.
Permissions
user.manage
Fields
None.
User Properties
View, create, update and manage user 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
}
}
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
}
}
Description
Delete properties associated with a user.
Permissions
user.manage
Parameters
None.
User Roles
View, update and manage user 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
Resource URL
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
}
}
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
}
}
Description
Delete the user from a specified role.
Permissions
user.manage
Parameters
None.
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.
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"
}
]
}
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"
}
]
}
}
Description
Delete a user’s tab instance.
Permissions
user.manage
Parameters
None.
List of Role Permissions
The permissions below are used when updating roles (see PUT for the /roles resource above).
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