Core API (in beta)

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.

Along with standard pagination information, there are also link elements with pre-built URIs 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 links 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.
  • self Save a link to the Account to reference later
  • products Link to retrieve all Products scoped to the Account

Model

  • id (UUID) The identifier of the Account
  • name (string) The name of the Account
  • status (enum, active or canceled) The status of the Account
  • created_at (datetime, ISO8601) The date the Account was created
  • updated_at (datetime, ISO8601) The date the Account was updated
  • contact (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 Product
  • account_id (UUID) The identifier of the parent Account
  • name (string) The name of the Product
  • url (string) The URL of the Product
  • environment (string) This is typically one of production, staging, or development.
  • status (enum, active, canceled) The status of the Product
  • timezone (string) The timezone of the Product
  • created_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 the Root Directory.

Model

  • id (UUID) The identifier of the Account
  • account_id (UUID) The identifier of the parent Account
  • product_id (UUID) The identifier of the parent Product
  • name (string) The name of the Report
  • report_type (string) The type of the Report. Note that people_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 the events 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 Event
  • product_id (UUID) The identifier of the parent Product
  • name (string) The name of the Event
  • display_name (string) The display name of the Event
  • description (text) The description of the Event
  • is_visible (boolean) The visibility of the Event in the Event Library
  • total (integer) The total times this Event has been tracked
  • first_used_at (datetime, ISO8601) The date this Event was first used
  • last_used_at (datetime, ISO8601) The date this Event was last used
  • first_sent_at (datetime, ISO8601) The date this Event was first sent
  • last_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 the properties 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 Property
  • product_id (UUID) The identifier of the parent Product
  • name (string) The name of the Property
  • display_name (string) The display name of the Property
  • description (text) The description of the Property
  • is_visible (boolean) The visibility of the Property
  • type (enum, automatic, text, number) The type of the Property
  • first_used_at (datetime, ISO8601) The date this Property was first used
  • last_used_at (datetime, ISO8601) The date this Property was last used
  • first_sent_at (datetime, ISO8601) The date this Property was first sent
  • last_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 the metrics 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 Metric
  • product_id (UUID) The identifier of the parent Product
  • title (string) The title of the Metric
  • description (text) The description of the Metric
  • is_visible (boolean) The visibility of the Metric
  • unit_type (enum, numeric, time, percent) The unit type of the Metric
  • status (boolean) The status of the Metric
  • color (string) The color of the Metric
  • sort_index (integer) The sort index of the Metric
  • config_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
}
Is anything on this page unclear? Suggest edits on Github!