Skip to the Menu if you just want to get started.

Who is this document for?

This document assumes that you know what an API is and have development experience.
For this to be of any use to you you also need to have a Kickserv account.

There's no guarantee that every single endpoint is listed here (last updated 1/3/2023), or that all information is up to date; the API can change at any time and I'm not notified if it does. GET, PUT, POST, and DELETE were the only HTTP verbs tested; they were not tested on every endpoint, only the ones where functionality would be expected. For example, /customers.json was not tested for DELETE because one wouldn't expect to be able to blow away all customers in one shot via the API. Verbs that function for an endpoint are shown as GET, DELETE, and so forth.

In instances where verb support was expected but either did not function, or was never tested successfully despite repeated attempts, it is listed as PUT, GET, etc. As far as I've been able to ascertain, PUT and PATCH are equivalent verbs and can be used interchangeably although this has not been fully and exhaustively tested. In general, HTTP 200 means whatever you just did was successful, so be careful about writing code that expects, for example, a 201 when creating a new customer. In my testing the most common HTTP code for something gone wrong was 422.

Every user in your Kickserv instance has an API key automatically generated when the user is created, but they are only visible to admin-level users. If you want someone to be able to use the API they’ll have to be told what their key is. To see the key for a user go to 'Settings > Manage Users' and then click on the user's name. Keys are valid for all versions of the API, and anything done using an API key is logged the same way as if that user had done it using the web UI. To execute any query a user must have valid permissions, and those permissions are the same as for the web UI; if a user can’t delete a job in the web UI they are also blocked from doing it via the API. In the event an API user attempts to do something for which they do not have permissions an error message will be returned. The specific message and format differs, but two examples are:

• {error: "unauthorized"}
• {"success": false, "message": "Access denied."}

That being said, there's quite a lot of variation in how errors are conveyed back to the API user, and don't appear to be standardized. In some cases the presence of an 'errors' key is indicative of an error, and in some cases the id field being null in the returned object is the signal. In at least one endpoint the indication is that 'success' is set to false. Play around with them and get a feel for how different endpoints show errors.

It's important to know that version 2 of the API is not just version 1 with improvements. Version 1 of the API has been published for quite some time and is built on XML. Version 2 has been around for a long time but has not been published in the same manner. It's there, it works, but to my knowledge it's never been publicly documented by Kickserv. Version 2 uses JSON to haul data instead of the clunkier XML but it's more than just an improvement on version 1.

From testing, there are things that are simply not possible with version 2, but ARE possible with version 1 or version 3 (yes, there is a version 3 as well). Take that statement with a grain of salt as I’ve had to piece together what I know about version 2 and 3 from observation and experimentation. It’s possible that there are version 2 endpoints that exist which just do not follow the patterns established by others. For example, creating a new customer is trivial in version 1 and version 3 but from limited testing it does not appear to be possible in version 2 (as of the time of writing). Similarly, the integrated messaging functionality appears to ride entirely over version 3 with no access at all for version 1 or version 2.

Each Kickserv account has what's called a 'slug', serving as a unique identifier for that account. If you go to any page in Kickserv and look at your browser's address bar you’ll see something like 'https://app.kickserv.com/weaselco/jobs'; in this case, 'weaselco' is your slug. Unless noted otherwise every endpoint listed here expands to:

https://app.kickserv.com/YOURSLUG/api/v2/jobs.json with the endpoint being documented below as simply /jobs.json. APIv3 is similar but with the obvious change.

All API calls must be made using HTTPS and must include the appropriate API key as an HTTP Basic Authentication header for both the username and password (they will work as well with the API key as the username and a null password, but I’m not convinced that’s intentional so I wouldn't rely on it). When POSTing or PUTing you must also include a Content-Type header set to 'application/json' to allow the API to understand the payload. No Content-Type header is required for GET or DELETE operations.

Not every possible parameter may be listed for every endpoint, in an effort to someday finish this and pretend that I have a social life.

Everything accessible by the API is represented as a JSON object or collection of objects. Both the web UI and the mobile app ride on top of and consume the API for at least some of their operations. At the time of this writing most, but not all things, that can be seen in the web UI are accessible via the API as nested objects. For example, both a job and a note are internally represented as an object (each with their own structure) and a job may contain one or more note objects. Not all keys in an object are editable; some are assigned by Kickserv (such as the assigned internal ID) and some are only modifiable by changing something else (such as updated_at on a note).

As there may be a lot of information sent back from an API call ("give me all scheduled jobs") many endpoints return paginated data. At the end of any paginated data set are a few fields to allow you to navigate through the pages. In the event paginated records are returned they will be contained in an array as a top level key in the returned object, followed by pagination metadata:

{
  "jobs": [ ...lots of stuff... ],
  "current_page": 1,
  "per_page": 25,
  "total_entries": 2340,
  "total_pages": 94,
  "next_page": 2,
  "previous_page": null
}

The 'meat' of what you want is, in this case, contained inside jobs but that text will change to customers, notes, or other values depending on what's being returned to you. This 'container' and the pagination information are returned even if there’s no other data to return for a query. When PUTing or POSTing, frequently the endpoint requires that data be wrapped inside the appropriate container for it to be considered a valid payload. Notes are returned inside a note container and similarly to edit a field of a note your payload must be wrapped inside a note container: { note : { public : true } } instead of just { public : true }

Forgetting to properly encapsulate your payload is a common mistake to make. That, and trying to POST/PUT without specifying the Content-Type header are the two mistakes that I made the most frequently when starting out.

per_page can be overridden and page can be supplied to jump to a certain page:

GET /customers.json?per_page=30&page=2

Skipping to a page that’s non-existent within a certain data set (e.g., skipping to page 6 out of a total of 4 pages) will return an empty array and the pagination metadata. If next_page or previous_page are null, there is no data in that direction. This makes it easy to wrap a loop around calls retrieving the next page as long as next_page is not null.

Be aware that if you pass page=0, it will be automatically incremented to 1. This can be problematic if you’re using a zero-based page counter in your code as you’ll iterate over the first result set twice, once for page=0 and again for page=1.

If you just want to know how many entries there are for a certain object (such as how many jobs there are in status 'unscheduled') that can be extracted from the pagination metadata without having to pull and count all objects (depending on the specific endpoint/data there may be other methods as well). This can be sped up by something like a GET request to /jobs.json?status=unscheduled&per_page=1 - this limits the size of the data returned to one job, allowing you to then pull the total_entries from the pagination data.

To make the examples easier to read, sometimes the quotes normally found in properly-formatted JSON have been omitted. In real-world JSON quotes will be around every key and string value. Finally, if an example reads:

POST {note:{note:"Test note"}} /jobs/55/notes.json

That means the JSON object is the payload that should be POSTed to /jobs/55/notes.json. All examples are generic and the specifics of what needs to go where in your code vary by language, library, and probably six or seven other things. There are literally millions of examples online about how to send HTTP requests in any language you might wish to use; please consult them for specifics. To allow you to play around, here’s one full example using cURL, a common CLI tool, and an easy way to poke at the CLI without having to write a full application. This cURL syntax may differ slightly depending on what operating system you’re running; this one is from a Debian server.

The example will change the description of job 12345 (change the light blue text as necessary):

curl -u APIKEY:APIKEY \
-X PUT -d'{"job":{"description":"Some new description"}}' -H 'Content-Type: application/json' \
'https://app.kickserv.com/YOURSLUG/api/v2/jobs/12345.json'

• -u is for specifying the username and password, in this case your API key, then a colon, then the API key again (no spaces). This method is simpler, but does allow anyone with access to your computer who can see your command history to also see your credentials. While it’s outside the scope of this document, this method should not be considered secure and something like a .netrc file or env variable should be considered.
• -X is the HTTP verb being used - be careful - this is the only difference between reading a job and deleting a job.
• -d indicates the payload. If the payload is in a file (which is common with cURL, since JSON can be cumbersome to type on a single line) the syntax would be -d@filename
• -H appends a header to the request. 'Content-Type: application/json' is required whenever you’re sending a JSON payload, typically any PUT or POST request. It is not required for GET or DELETE requests, but is not harmful if present.

Notice that the URL and payload are enclosed in single quotes. The case of the command line arguments matters; -X is not the same thing as -x.

To make reading the JSON easier on the command line I recommend using a utility like 'jq' and piping the output of cURL to it. 'jq' is available for all major operating systems but if you’d prefer you can copy/paste the JSON into http://www.jqplay.org and look at it there.

As the returned data can be quite lengthy, jq can also be used to extract specific fields out of the reply:

... | jq .job_charges[].item.name
"Feed dog"
"Walk dog"

To make things easier to read, if multiple keys are being read the can all be shown on the same line:

... | jq '.job_number,.description,.status' | paste - - -

12345 "Remove marmoset from armoire and release" unscheduled