The KISSmetrics API is very simple. You request a URL from our tracking servers that contains various parameters explained below.
Note: All parameters must be properly URL-escaped (such as replacing spaces with + or %20). Most programming languages provide libraries to do this for you.
You must make your requests against trk.kissmetrics.com using GET. Both HTTP and HTTPS are supported.
To record an event you must make a request to our tracking API with the path /e. There are three additional required parameters:
_k - your KISSmetrics API key._n - the name of the event you want to record. This is limited to 255 chars and all commas (,), and colons (:) will automatically be changed to spaces (KISSmetrics will convert foo:bar,baz to foo bar baz)._p - the identity of the person doing the event. For an e-mail campaign this will likely be the e-mail address of the e-mail recipient. This is limited to 255 chars and all commas (,), and colons (:) will automatically be changed to spaces (KISSmetrics will convert foo:bar,baz to foo bar baz)._t - the timestamp of the event (in seconds as a UTC Unix epoch). By default this is ignored - it is used only to help make requests unique and the time that our servers receive the event is used for the timestamp of the event. However, if you would like to specify a timestamp of your own, including a timestamp from the past, you can pass in your own _t value with an additional parameter of _d=1._d - if set to 1 then KISSmetrics will use the value you pass in for _t as the timestamp of the event. If the _d parameter is not set, or is set to any other value besides 1 then KISSmetrics will use the time that our servers receive the event.You can, like the other KISSmetrics APIs record any other arbitrary properties that you might want. For example you might include the name of the e-mail variation if you are split testing different e-mail messages. See below for more information on properties.
To record that the user bob did the event Signup and his gender was male you would request the URL:
http://trk.kissmetrics.com/e?_p=bob&_n=Signup&gender=male&_k=YOUR_KEYAny additional URL parameter besides the required parameters listed above are automatically recorded as properties. You can set properties on a person without recording an event by making a request to /s. You will need to include:
_k - your KISSmetrics API key.
_p - the identity of the person you are setting properties on. This is limited to 255 chars and all commas (,), and colons (:) will automatically be changed to spaces (KISSmetrics will convert foo:bar,baz to foo bar baz).
_t - the timestamp of when the properties were set (in seconds as a UTC Unix epoch). By default this is ignored - it is used only to help make requests unique and the time that our servers receive the request is used for the timestamp of the properties. However, if you would like to specific a timestamp of your own you can pass in your own _t value with an additional parameter of _d=1.
_d - if set to 1 then KISSmetrics will use the value you pass in for _t as the timestamp of the properties. If the _d parameter is not set, or is set to any other value besides 1 then KISSmetrics will use the time that our servers receive the properties.
Any properties you want to set (as additional parameters)
To set the property Payment Plan to Pro for the user sally you would request the URL:
http://trk.kissmetrics.com/s?_p=sally&Payment+Plan=Pro&_k=YOUR_KEYYou can pass in more than one property at a time also:
http://trk.kissmetrics.com/s?_p=sally&size=small&color=black&_k=YOUR_KEYProperty names are limited to 255 chars and all commas (,), and colons (:) will automatically be changed to spaces (KISSmetrics will convert foo:bar,baz to foo bar baz). Property values are limited to 8 KB of data in theory, but in practice are usually restricted to much shorter values due to maximum URL lengths. KISSmetrics does not alter the values you pass in in any way.
So if you are recording an event use /e, but if you just want to set properties without recording an event, use /s.
In some cases a user may have more than one identity. For example if a person comes to your site without signing in you may set a cookie with a unique identifier. You might then use this anonymous identity to track all their activity before signing in. Then later when they sign in you’ll have their username (a named identity) which you might start to use after they sign in. If you want to tie the activity from before they signed in to the activity after they signed in you will have to tell KISSmetrics to treat the two identities as aliases of each other. You can do this by making a request to /a with the following parameters:
_k - your KISSmetrics API key._p - the identity of the person you are aliasing. This is limited to 255 chars and all commas (,), and colons (:) will automatically be changed to spaces (KISSmetrics will convert foo:bar,baz to foo bar baz)._n - the other identity you want to alias. This is limited to 255 chars and all commas (,), and colons (:) will automatically be changed to spaces (KISSmetrics will convert foo:bar,baz to foo bar baz).So if you want to treat the person bob the same as bob@bob.com you could make a request to:
http://trk.kissmetrics.com/a?_p=bob&_n=bob@bob.com&_k=YOUR_KEYKISSmetrics will tie together the two records and will treat the identities bob and bob@bob.com as the same person. It’s OK to call this more than once with the same pair of identities. It’s also OK if a person has more than one alias. Also, which identity you use for _p and which one you use for _n are not important (either order works the same).
Note: The KISSmetrics Javascript API takes care of all of this stuff for you automatically. You should only need to call _kmq.push('identify', some_identity) and the Javascript API takes care of aliasing and all of the other bits. However, if you are not using the Javascript API you may need to use this functionality.
Our language-specific APIs often have mechanisms to retry event requests when they do not successfully go through on the first request. Consider implementing such a system if you plan to send us batch amounts of events through a direct HTTP request to trk.kissmetrics.com.
Filed under APIs