Core API (in beta)
- Introduction
- API Reference
Kissmetrics is currently testing our Core API that allows you to retrieve and work with core aspects of our system. It allows you to query information about your Accounts, Products, Reports, Events, and Properties.
Introduction
Generate an API token
In order to work with our API you need to generate a Personal Token from within your Kissmetrics administration interface. This can be viewed from within the Account settings menu option. You will see Manage API Tokens. From there you can Generate a new token and you are ready to get started.
Request Requirements
Content Negotiation
We currently only support JSON (application/json
) in our request lifecycle. You can specify this with an HTTP Header:
Accept: application/json
When we require a POST
to an endpoint, such as our People Search execution, you must specify the Content-Type
.
Content-Type: application/json
Authentication
We require authentication via the Authorization
HTTP header. All
requests must be made over HTTPS
. Calls made over HTTP
will result
in a 301 Permanent Redirect
. Authentication is required for all requests.
Authorization: Bearer your-token-here
Pagination
All lists of objects support pagination. Those requests will include a common pagination structure. The default limit
is set to 20.
{
"pagination":{
"total":6,
"offset":0,
"limit":20
}
}
Available Arguments
limit
(optional, integer) Use this to set the number of items to be returned. Default is 20.offset
(optional, integer) Use this to specify the offset from within the collection of items.
Link Envelopes
Along with standard pagination
information, there are also link
elements with pre-built URI
s for next
, previous
, last
, and first
. This allows you to reference the links in a scripted environment and for auto pagination.
Some links follow RFC 6570 and utilize URI
Templates. This is denoted with the
templated
key.
{
"links":[
{
"templated":false,
"href":"https://api.kissmetrics.com/core/products?limit=1&offset=0",
"rel":"first",
"name":"First"
},
{
"templated":false,
"href":"https://api.kissmetrics.com/core/products?limit=1&offset=5",
"rel":"last",
"name":"Last"
},
{
"templated":false,
"href":"https://api.kissmetrics.com/core/products?limit=1&offset=2",
"rel":"next",
"name":"Next"
},
{
"templated":false,
"href":"https://api.kissmetrics.com/core/products?limit=1&offset=0",
"rel":"prev",
"name":"Previous"
}
]
}
API Reference
All requests in the examples assume proper Authorization
and Accept
headers. All examples utilize curl
, but could be executed with any HTTP client of your choosing.
Root Directory
The root directory returns a list of all available link
s within the API.
Request
curl -i 'https://api.kissmetrics.com/core' \
-H 'Authorization: Bearer YOUR-API-TOKEN'
Response
{
"links": [
{
"templated": false,
"href": "https://api.kissmetrics.com/core",
"rel": "self",
"name": "Directory"
}
],
"data": {
"links": [
{
"templated": false,
"href": "https://api.kissmetrics.com/core",
"rel": "self",
"name": "Directory"
},
{
"templated": false,
"href": "https://api.kissmetrics.com/core/accounts",
"rel": "accounts",
"name": "Accounts"
},
],
"description": "API access for KISSmetrics",
"name": "KISSmetrics API"
}
}
All Accounts
The accounts endpoint returns a list of accounts you are authorized to access.
Request
curl -i 'https://api.kissmetrics.com/core/accounts' \
-H 'Authorization: Bearer YOUR-API-TOKEN'
Response
[
{
"links": [
{
"templated": false,
"href": "https://api.kissmetrics.com/core/accounts/51cc9c30-0edf-0131-ead3-12313b0d181e",
"rel": "self",
"name": "Self"
},
{
"templated": false,
"href": "https://api.kissmetrics.com/core/accounts/51cc9c30-0edf-0131-ead3-12313b0d181e/products",
"rel": "products",
"name": "Products"
}
],
"contact": {
"phone": null,
"country": null,
"name": null
},
"updated_at": "2014-09-02T19:46:43Z",
"created_at": "2013-10-04T04:56:57Z",
"status": "active",
"name": "My SaaS Account",
"id": "51cc9c30-0edf-0131-ead3-12313b0d181e"
}
]
Account Details
The account endpoint returns the body of the account you are authorized
to access. You can retrieve this URI
via several means:
- The
links
from within an All Accounts list response. - The URI Template from within the
links
inside of the Root Directory.
Link Envelopes
self
Save a link to the Account to reference laterproducts
Link to retrieve all Products scoped to the Account
Model
id
(UUID) The identifier of the Accountname
(string) The name of the Accountstatus
(enum,active
orcanceled
) The status of the Accountcreated_at
(datetime, ISO8601) The date the Account was createdupdated_at
(datetime, ISO8601) The date the Account was updatedcontact
(json) The details of the person of contact for the Account
Request
curl -i 'https://api.kissmetrics.com/core/accounts/51cc9c30-0edf-0131-ead3-12313b0d181e' \
-H 'Authorization: Bearer YOUR-API-TOKEN'
Response
{
"links": [
{
"templated": false,
"href": "https://api.kissmetrics.com/core/accounts/51cc9c30-0edf-0131-ead3-12313b0d181e",
"rel": "self",
"name": "Self"
},
{
"templated": false,
"href": "https://api.kissmetrics.com/core/accounts/51cc9c30-0edf-0131-ead3-12313b0d181e/products",
"rel": "products",
"name": "Products"
}
],
"contact": {
"phone": null,
"country": null,
"name": null
},
"updated_at": "2014-09-02T19:46:43Z",
"created_at": "2013-10-04T04:56:57Z",
"status": "active",
"name": "My Saas Account",
"id": "51cc9c30-0edf-0131-ead3-12313b0d181e"
}
All Products
The products endpoint returns a collection of all products you have access to. If you are a member of multiple Accounts, then you will see all products across those accounts.
Request
curl -i 'https://api.kissmetrics.com/core/products' \
-H 'Authorization: Bearer YOUR-API-TOKEN'
Response
[
{
"links": [
{
"templated": false,
"href": "https://apikissmetrics.com/core/products/e7063aa0-0edf-0131-ead3-12313b0d181e",
"rel": "self",
"name": "Self"
},
{
"templated": false,
"href": "https://apikissmetrics.com/core/accounts/51cc9c30-0edf-0131-ead3-12313b0d181e",
"rel": "account",
"name": "Account"
},
{
"templated": false,
"href": "https://apikissmetrics.com/core/products/e7063aa0-0edf-0131-ead3-12313b0d181e/reports",
"rel": "reports",
"name": "Product Reports"
},
{
"templated": false,
"href": "https://apikissmetrics.com/core/products/e7063aa0-0edf-0131-ead3-12313b0d181e/events",
"rel": "events",
"name": "Product Events"
},
{
"templated": false,
"href": "https://apikissmetrics.com/core/products/e7063aa0-0edf-0131-ead3-12313b0d181e/properties",
"rel": "properties",
"name": "Product Properties"
}
],
"id": "e7063aa0-0edf-0131-ead3-12313b0d181e",
"account_id": "51cc9c30-0edf-0131-ead3-12313b0d181e",
"name": "My SaaS Product",
"url": "http://mysaasproduct.com",
"status": "active",
"environment": "",
"timezone": "US/Pacific",
"created_at": "2013-10-04T05:01:07+00:00"
}
]
Product Details
The product endpoint returns the body of the product you are authorized
to access. You can retrieve this URI
via several means:
- The
links
from within an All Products list response. - The URI Template from within the
links
inside of the Root Directory.
Model
id
(UUID) The identifier of the Productaccount_id
(UUID) The identifier of the parent Accountname
(string) The name of the Producturl
(string) The URL of the Productenvironment
(string) This is typically one of production, staging, or development.status
(enum,active
,canceled
) The status of the Producttimezone
(string) The timezone of the Productcreated_at
(datetime, ISO8601) The date the Product was created
Request
curl -i 'https://api.kissmetrics.com/core/products/e7063aa0-0edf-0131-ead3-12313b0d181e' \
-H 'Authorization: Bearer YOUR-API-TOKEN'
Response
{
"links": [],
"id": "e7063aa0-0edf-0131-ead3-12313b0d181e",
"account_id": "51cc9c30-0edf-0131-ead3-12313b0d181e",
"name": "My Saas Product",
"url": "http://mysaasproduct.com",
"status": "active",
"environment": "",
"timezone": "US/Pacific",
"created_at": "2013-10-04T05:01:07+00:00"
}
All Reports
The reports endpoint returns a list of reports you are authorized to access. This includes all Reports across all Products.
Request
curl -i 'https://api.kissmetrics.com/core/reports' \
-H 'Authorization: Bearer YOUR-API-TOKEN'
Response
[
{
"links": [
{
"templated": false,
"href": "https://api.kissmetrics.com/core/reports/64361c30-4a48-0131-0cbb-22000a9f1c0f",
"rel": "self",
"name": "Self"
},
{
"templated": false,
"href": "https://api.kissmetrics.com/core/products/6c921840-0edf-0131-ead4-12313b0d181e",
"rel": "product",
"name": "Product"
},
{
"templated": false,
"href": "https://api.kissmetrics.com/core/accounts/51cc9c30-0edf-0131-ead3-12313b0d181e",
"rel": "account",
"name": "Account"
}
],
"created_at": "2013-12-18T19:27:43+00:00",
"name": "My People Search",
"report_type": "people_search_v2",
"account_id": "51cc9c30-0edf-0131-ead3-12313b0d181e",
"product_id": "6c921840-0edf-0131-ead4-12313b0d181e",
"id": "64361c30-4a48-0131-0cbb-22000a9f1c0f"
}
]
Report Details
The report endpoint returns the body of the report you are authorized to
access. You can retrieve this URI
via several means:
- The
links
from within an All Reports list response. - The URI Template from within the
links
inside of theRoot Directory
.
Model
id
(UUID) The identifier of the Accountaccount_id
(UUID) The identifier of the parent Accountproduct_id
(UUID) The identifier of the parent Productname
(string) The name of the Reportreport_type
(string) The type of the Report. Note thatpeople_search_v2
are the only reports that may be run via the API.created_at
(datetime, ISO8601) The date the Report was created
Request
curl -i 'https://api.kissmetrics.com/core/reports/64361c30-4a48-0131-0cbb-22000a9f1c0f' \
-H 'Authorization: Bearer YOUR-API-TOKEN'
Response
{
"links": [],
"created_at": "2013-12-18T19:27:43+00:00",
"name": "My People Search",
"report_type": "people_search_v2",
"account_id": "51cc9c30-0edf-0131-ead3-12313b0d181e",
"product_id": "6c921840-0edf-0131-ead4-12313b0d181e",
"id": "64361c30-4a48-0131-0cbb-22000a9f1c0f"
}
All Events
The events endpoint returns a list of events from your event libraries. This includes all Events across all Products.
Request
curl -i 'https://api.kissmetrics.com/core/events' \
-H 'Authorization: Bearer YOUR-API-TOKEN'
Response
[
{
"links": [
{
"templated": false,
"href": "https://api.kissmetrics.com/core/events/d71bf5f0-3de7-0131-aa07-1231392acb4b",
"rel": "self",
"name": "Self"
},
{
"templated": false,
"href": "https://api.kissmetrics.com/core/products/6c921840-0edf-0131-ead4-12313b0d181e",
"rel": "product",
"name": "Product"
}
],
"last_sent_at": "2014-08-29T15:41:08+00:00",
"first_sent_at": "2013-12-03T01:26:21+00:00",
"last_used_at": "2014-08-29T14:58:30+00:00",
"id": "d71bf5f0-3de7-0131-aa07-1231392acb4b",
"product_id": "6c921840-0edf-0131-ead4-12313b0d181e",
"name": "search engine hit",
"display_name": "Search engine hit",
"description": null,
"is_visible": true,
"total": 8,
"first_used_at": "2013-12-03T01:02:05+00:00"
}
]
Event Details
The event endpoint returns the body of the event you are authorized to
access. You can retrieve this URI
via several means:
- The
links
from within an All Events list response. - The
links
from within an All Products list response via theevents
link relationship. This will return events scoped to that product. - The URI Template from within the
links
inside of the Root Directory.
Model
id
(UUID) The identifier of the Eventproduct_id
(UUID) The identifier of the parent Productname
(string) The name of the Eventdisplay_name
(string) The display name of the Eventdescription
(text) The description of the Eventis_visible
(boolean) The visibility of the Event in the Event Librarytotal
(integer) The total times this Event has been trackedfirst_used_at
(datetime, ISO8601) The date this Event was first usedlast_used_at
(datetime, ISO8601) The date this Event was last usedfirst_sent_at
(datetime, ISO8601) The date this Event was first sentlast_sent_at
(datetime, ISO8601) The date this Event was last sent
Request
curl -i 'https://api.kissmetrics.com/core/events/d71bf5f0-3de7-0131-aa07-1231392acb4b' \
-H 'Authorization: Bearer YOUR-API-TOKEN'
Response
{
"links": [],
"last_sent_at": "2014-08-29T15:41:08+00:00",
"first_sent_at": "2013-12-03T01:26:21+00:00",
"last_used_at": "2014-08-29T14:58:30+00:00",
"id": "d71bf5f0-3de7-0131-aa07-1231392acb4b",
"product_id": "6c921840-0edf-0131-ead4-12313b0d181e",
"name": "search engine hit",
"display_name": "Search engine hit",
"description": null,
"is_visible": true,
"total": 8,
"first_used_at": "2013-12-03T01:02:05+00:00"
}
All Properties
The properties endpoint returns a list of properties defined. This includes all Property records across all Products.
Request
curl -i 'https://api.kissmetrics.com/core/properties' \
-H 'Authorization: Bearer YOUR-API-TOKEN'
Response
[
{
"links": [
{
"templated": false,
"href": "https://api.kissmetrics.com/core/properties/6234e85e-2941-11e4-a20e-12313932e372",
"rel": "self",
"name": "Self"
},
{
"templated": false,
"href": "https://api.kissmetrics.com/core/products/6c921840-0edf-0131-ead4-12313b0d181e",
"rel": "product",
"name": "Product"
}
],
"last_sent_at": "2014-08-29T22:43:17+00:00",
"first_sent_at": "2013-10-04T05:58:54+00:00",
"last_used_at": "2014-08-29T21:50:32+00:00",
"id": "6234e85e-2941-11e4-a20e-12313932e372",
"product_id": "6c921840-0edf-0131-ead4-12313b0d181e",
"type": null,
"name": "referrer",
"display_name": "Referrer",
"description": null,
"is_visible": true,
"first_used_at": "2013-10-04T05:00:09+00:00"
}
]
Property Details
The property endpoint returns the body of the property you are
authorized to access. You can retrieve this URI
via several means:
- The
links
from within an All Properties list response. - The
links
from within an All Products list response via theproperties
link relationship. This will return properties scoped to that product. - The URI Template from within the
links
inside of the Root Directory.
Model
id
(UUID) The identifier of the Propertyproduct_id
(UUID) The identifier of the parent Productname
(string) The name of the Propertydisplay_name
(string) The display name of the Propertydescription
(text) The description of the Propertyis_visible
(boolean) The visibility of the Propertytype
(enum,automatic
,text
,number
) The type of the Propertyfirst_used_at
(datetime, ISO8601) The date this Property was first usedlast_used_at
(datetime, ISO8601) The date this Property was last usedfirst_sent_at
(datetime, ISO8601) The date this Property was first sentlast_sent_at
(datetime, ISO8601) The date this Property was last sent
Request
curl -i 'https://api.kissmetrics.com/core/properties/6234e85e-2941-11e4-a20e-12313932e372' \
-H 'Authorization: Bearer YOUR-API-TOKEN'
Response
{
"links": [],
"last_sent_at": "2014-08-29T22:43:17+00:00",
"first_sent_at": "2013-10-04T05:58:54+00:00",
"last_used_at": "2014-08-29T21:50:32+00:00",
"id": "6234e85e-2941-11e4-a20e-12313932e372",
"product_id": "6c921840-0edf-0131-ead4-12313b0d181e",
"type": null,
"name": "referrer",
"display_name": "Referrer",
"description": null,
"is_visible": true,
"first_used_at": "2013-10-04T05:00:09+00:00"
}
All Metrics
The metrics endpoint returns a list of metrics defined. This includes all Metric records across all Products.
Request
curl -i 'https://api.kissmetrics.com/core/metrics' \
-H 'Authorization: Bearer YOUR-API-TOKEN'
Response
[
{
"links": [
{
"templated": false,
"href":
"https://api.kissmetrics.com/core/metrics/48434344-088b-1031-a8b0-22923a9f01ba",
"rel": "self",
"name": "Self"
},
{
"templated": false,
"href": "https://api.kissmetrics.com/core/products/6c921840-0edf-0131-ead4-12313b0d181e",
"rel": "product",
"name": "Product"
},
{
"templated": false,
"href": "https://api.kissmetrics.com/query/metrics/48434344-088b-1031-a8b0-22923a9f01ba/over-time",
"rel": "metric-over-time",
"name": "Metrics Over Time Query"
},
{
"templated": false,
"href": "https://api.kissmetrics.com/query/metrics/48434344-088b-1031-a8b0-22923a9f01ba/by-segment",
"rel": "metric-by-segment",
"name": "Metrics By Segment Query"
}
],
"config_last_changed_at": "2011-05-30T17:23:24+00:00",
"color": null,
"id": "48434344-088b-1031-a8b0-22923a9f01ba",
"product_id": "6c921840-0edf-0131-ead4-12313b0d181e",
"title": "Average Revenue Per Person",
"description": "The average amount of revenue per person generated during the given time period.",
"unit_type": "numeric",
"status": "pending",
"sort_index": 0,
"is_visible": true
}
]
Metric Details
The metric endpoint returns the body of the metric you are
authorized to access. You can retrieve this URI
via several means:
- The
links
from within an All Metrics list response. - The
links
from within an All Products list response via themetrics
link relationship. This will return metrics scoped to that product. - The URI Template from within the
links
inside of the Root Directory.
Model
id
(UUID) The identifier of the Metricproduct_id
(UUID) The identifier of the parent Producttitle
(string) The title of the Metricdescription
(text) The description of the Metricis_visible
(boolean) The visibility of the Metricunit_type
(enum,numeric
,time
,percent
) The unit type of the Metricstatus
(boolean) The status of the Metriccolor
(string) The color of the Metricsort_index
(integer) The sort index of the Metricconfig_last_changed_at
(datetime, ISO8601) The date this Metric configuration was last changed
Request
curl -i 'https://api.kissmetrics.com/core/metrics/48434344-088b-1031-a8b0-22923a9f01ba' \
-H 'Authorization: Bearer YOUR-API-TOKEN'
Response
{
"links": [],
"config_last_changed_at": "2011-05-30T17:23:24+00:00",
"color": null,
"id": "48434344-088b-1031-a8b0-22923a9f01ba",
"product_id": "6c921840-0edf-0131-ead4-12313b0d181e",
"title": "Revenue",
"description": "The amount of revenue generated during the given time period.",
"unit_type": "numeric",
"status": "pending",
"sort_index": 1,
"is_visible": true
}