Kickserv APIv2 - Common Fields and Where to Find Them

There’s a lot of data in Kickserv, and as with any relational datastore some are more important than others. As you work with the API you’ll quickly become familiar with them and what fields tie all the records together. There are a number of fields that you'll either never touch, can't touch (if no mechanism is provided), or simply don't need to mess with. Far from being a static landscape, there are occasionally new fields that pop up (sometimes before a feature is released in the web UI) and some that are deprecated but still functional.

Speaking generally, the top-level object is a customer. A customer can have more than one job, but a job can and must have only one customer. Any sub-object (charge, note, attachment, etc) will contain a key that allows you to follow the path upward. Using a note as an example, a job note object will have an 'id' key which serves as a global identifier. It will also have a 'noteable_id' key which maps to the global id of the job to which it's connected, and the job will have a 'customer_id' field indicating to whom the job belongs. Similarly, an attachment has it's own global 'id' key and also a 'job_id' key which contains the job to which it's assigned. Some fields come up frequently, and here are a few to get you started:

job_type_id

This is the numeric representation of what in the web UI is called a 'service'; think of it as the type of job, such as 'Roof Evaluation', 'Deck Repair', or 'Siding Installation' might be to a construction company. These can be seen in 'Settings > Services' and then hovering over the 'edit' icon. Programmatically, they can be retrieved by GETing https://app.kickserv.com/SLUG/calendar.json and examining the job_types stanza.

task_type_id

All entries in the 'Schedule' section of a job in the web UI are the same type of object with different task_type_ids. A 'reminder' will be one value, 'work' will be another, 'estimate' will be a third, and finally ‘time off’ will have its own value. These can either be gleaned from existing job entries (GETing a job and examining the tasks stanza) or by GETing https://app.kickserv.com/SLUG/calendar.json and examining the task_types stanza. These appear to be unique to your instance of Kickserv and do not change over time. While I’m generally opposed to hard-coding values, I have yet to see a situation where these change once they are created. I've had numerous scripts running for years without any problem hard-coding those values. Given that they are globally unique, I assume that they serve as a lookup into some other data structure in the innards of Kickserv, though I have yet to see direct evidence of this.

employee_number

This is the locally-significant (account-scoped) number of each employee in your instance of Kickserv. Unless you have amazingly high turnover it will probably be three digits or less. The account owner is employee_number 1. These are used for operations such as assigning a task to an employee or logging who created a note.

In many cases, the information about an employee such as their name is returned as part of the API query I refer to these in this documentation as 'glue records' due both to their passing similarity to DNS glue records, and for lack of a better term. When querying for a job, the employee objects for any employees currently associated with the job (such as those to whom it is assigned) are returned as well. Similar records are returned for other endpoints, which means you don't have to immediately query again to find out which employees those are, for example. All employees can be retrieved from /employees.json or by GETing https://app.kickserv.com/SLUG/calendar.json and examining the employees stanza.

account_id

You'll see this quite a bit as it's returned somewhere in virtually every API response. This is the internal ID of your Kickserv account and is not modifiable. In a handful of API requests it's a required parameter but by and large you'll be seeing it more than you have to supply it. The only time this will change is if you're switching between multiple Kickserv accounts so this is the kind of thing that could be hardcoded into a library or settings file.

Miscellaneous Data

This section contains miscellaneous snippets about specific fields or information that doesn't belong anywhere else.

payment_code (Job)

If QR codes are enabled on the default invoice, this is the code that must be entered at kck.im/pay for the customer to be able to pay the balance. When displayed on the invoice it is broken into two groups of four characters.

ok_to_sync (Job)

A flag indicating that an invoice has been approved for sync to Quickbooks (possibly Xero as well, I have no experience with it). Values are 'true' or 'null'.

txn_id (Job)

The Quickbooks (possibly Xero too, though untested) URL identifier of an invoice.

ref_number (Job)

The Quickbooks (possibly Xero too, though untested) identifier of an invoice.

self_service (Job)

A flag indicating that an opp/job was created via the Customer Center.

customer_(number|datetime|text)* (Job, Customer)

Legacy custom fields. They have been deprecated as far as I know, and should not be relied on.

disable_customer_center_payment (Job)

A flag permitting or disabling a customer's ability to pay with a credit card via the Customer Center. Applies to that job only, but can be set as the global default.