Kickserv API

Introduction

The Kickserv API is implemented via XML over HTTP in a RESTful manner. The following resources are available through the API:

Authentication

Authentication is performed via HTTP Basic Authentication using an employee's API token.

This API token must be passed on every API call.

An employee's unique API token can be found in the employee management section of your Kickserv account.

An API token should be treated like your normal Kickserv password. Changing your password will also change your API token.

Exploring the API through curl

Curl is a simple command line tool that is perfect for quickly exploring the API. The examples in the following sections use curl syntax.

Customers

List

Records are returned 30 at a time. 

curl -u token:token https://myapp.kickserv.com/customers.xml

Additional records can fetched by passing a page parameter. 

curl -u token:token https://myapp.kickserv.com/customers.xml?page=2

Records can filtered by passing one or more filters:

  • customer_number
  • name
  • phone_number
  • fax
  • email_address
  • service_address
  • service_city
  • service_zip_code
  • service_state
  • service_country
  • billing_address
  • billing_city
  • billing_zip_code
  • billing_state
  • billing_country
curl -u token:token https://myapp.kickserv.com/customers.xml?service_zip_code=55555

The following relational data can be included:

  • contacts
  • jobs
  • tasks
  • notes
  • tax_entity
curl -u token:token https://myapp.kickserv.com/jobs.xml?include=jobs

The return XML can be made much smaller by specifying the attributes needed.

IMPORTANT: This is highly recommended as it will speed up the data request and post-processing. 

curl -u token:token https://myapp.kickserv.com/jobs.xml?only=customer_number,name

Show

curl -u token:token https://myapp.kickserv.com/customers/[customer number].xml

Create

Records are added via HTTP POST. The Content-Type header must be set to 'application/xml'. 

curl -u token:token -H 'Content-Type: application/xml' -d "<customer><name>ABC Corp.</name></customer>" https://myapp.kickserv.com/customers.xml

Note: If the customer_number field is passed in, it will be ignored. Customer numbers are automatically assigned by Kickserv. Future releases will support user-assignable customer numbers.

Update

Records are updated via HTTP PUT. The Content-Type header must be set to 'application/xml'. 

curl -u token:token -X PUT -H 'Content-Type: application/xml' -d "<customer><name>New name</name></customer>" https://myapp.kickserv.com/customers/[customer number].xml

Delete

Records are deleted via HTTP DELETE. 

curl -u token:token -X DELETE https://myapp.kickserv.com/customers/[customer number].xml

Jobs

List

Records are returned 30 at a time. 

curl -u token:token https://myapp.kickserv.com/jobs.xml

Additional records can fetched by passing a page parameter. 

curl -u token:token https://myapp.kickserv.com/jobs.xml?page=2

Scope by customer number to return jobs for a particular customer. 

curl -u token:token https://myapp.kickserv.com/customers/customer number/jobs.xml

Jobs can be filtered by scheduled date based on these smart values:

  • today
  • tomorrow
  • yesterday
  • this_week
  • next_week
  • last_week
  • this_month
  • next_month
  • last_month

curl -u token:token https://myapp.kickserv.com/jobs.xml?scheduled=today

Jobs can filtered by state based on these smart values:

  • in_progress
  • completed
  • uncompleted
curl -u token:token https://myapp.kickserv.com/jobs.xml?state=uncompleted

Jobs can be filtered by employee. 

curl -u token:token https://myapp.kickserv.com/jobs.xml?employee_number=123

Jobs can be filtered by category. 

curl -u token:token https://myapp.kickserv.com/jobs.xml?job_type_id=123

Jobs can be filtered by job status. 

curl -u token:token https://myapp.kickserv.com/jobs.xml?job_status_id=123

The following relational data can be included:

  • customer
  • employees
  • job_charges
  • time_entries
  • notes
  • job_type
  • job_status
  • tax_entity
curl -u token:token https://myapp.kickserv.com/jobs.xml?include=customer,job_charges

The return XML can be made much smaller by specifying the attributes needed.

IMPORTANT: This is highly recommended as it will speed up the data request and post-processing. 

curl -u token:token https://myapp.kickserv.com/jobs.xml?only=job_number,name

Show

curl -u token:token https://myapp.kickserv.com/jobs/[job number].xml

Create

Records are added via HTTP POST. The Content-Type header must be set to 'application/xml'. 

curl -u token:token -H 'Content-Type: application/xml' -d "<job><name>foo</name><scheduled_on>1/2/09 09:00am</scheduled_on></job>" https://myapp.kickserv.com/customers/[customer number]/jobs.xml

Update

Records are updated via HTTP PUT. The Content-Type header must be set to 'application/xml'. 

curl -u token:token -X PUT -H 'Content-Type: application/xml' -d "<job><name>New name</name></job>" https://myapp.kickserv.com/jobs/[job number].xml

When creating or updating customers use the following examples when trying to specify Employees, Categories or Job Status.

  • Employees
curl -u token:token -X PUT -H 'Content-Type: application/xml' -d '<job><employee_ids type="array"><employee_id>employee_id</employee_id><employee_id>employee_id</employee_id></employee_ids></job>' https://myapp.kickserv.com/jobs/[job number].xml
  • Category
curl -u token:token -X PUT -H 'Content-Type: application/xml' -d '<job><job_type_id>[JOB_TYPE_ID]</job_type_id>></job>' https://myapp.kickserv.com/jobs/[job number].xml
  • Job Status
curl -u token:token -X PUT -H 'Content-Type: application/xml' -d '<job><job_status_id>[JOB_STATUS_ID]</job_status_id></job>' https://myapp.kickserv.com/jobs/[job number].xml

(Note: the above URLs are for updating. To create, use the create URL listed above.)

Delete

Records are deleted via HTTP DELETE. 

curl -u token:token -X DELETE https://myapp.kickserv.com/jobs/[job number].xml

Job Charges

Create

Records are added via HTTP POST. The Content-Type header must be set to 'application/xml'. 

curl -u token:token -H 'Content-Type: application/xml' -d '<job_charge><item_id>[ITEM ID]</item_id><details>[details]</details><quantity>[quantity]</quantity><price_per_unit>[unit price]</price_per_unit></job_charge>' https://myapp.kickserv.com/jobs/[job number]/job_charges.xml

Example of creating a job charge on job # 1: 

curl -u token:token -H 'Content-Type: application/xml' -d '<job_charge><item_id>367</item_id><details>Test Job Charge from API</details><quantity>4</quantity><price_per_unit>17.25</price_per_unit></job_charge>' https://myapp.kickserv.com/jobs/1/job_charges.xml

Employees

List

curl -u token:token https://myapp.kickserv.com/employees.xml

Show

curl -u token:token https://myapp.kickserv.com/employees/[employee number].xml

Create

Records are added via HTTP POST. The Content-Type header must be set to 'application/xml'. 

curl -u token:token -H 'Content-Type: application/xml' -d "<employee><name>John</name></employee>" https://myapp.kickserv.com/employees.xml

Example of creating an employee with login access: 

curl -u token:token -H 'Content-Type: application/xml' -d "<employee><name>John</name><can_login>true</can_login><username>johndoe</username><password>123456</password></employee>" https://myapp.kickserv.com/employees.xml

Update

Records are updated via HTTP PUT. The Content-Type header must be set to 'application/xml'. 

curl -u token:token -X PUT -H 'Content-Type: application/xml' -d "<employee><name>New name</name></employee>" https://myapp.kickserv.com/employees/[employee number].xml

Delete

Employees can be made inactive but cannot be deleted. This allows the integrity of historical job assignments, notes, etc. to remain.

Time Entries

List

curl -u token:token https://myapp.kickserv.com/jobs/[job number]/time_entries.xml

Show

curl -u token:token https://myapp.kickserv.com/jobs/[job number]/time_entries/[time entry id].xml

Create

Records are added via HTTP POST. The Content-Type header must be set to 'application/xml'. 

curl -u token:token -H 'Content-Type: application/xml' -d "<time_entry><employee_id>123</employee_id><started_on>01/02/2009 01:00pm</started_on><number_of_hours>1.25</number_of_hours></time_entry>" https://myapp.kickserv.com/jobs/[job number]/time_entries.xml

Update

Records are updated via HTTP PUT. The Content-Type header must be set to 'application/xml'. 

curl -u token:token -X PUT -H 'Content-Type: application/xml' -d "<time_entry><number_of_hours>9</number_of_hours></time_entry>" https://myapp.kickserv.com/jobs/[job number]/time_entries/[time entry id].xml

Delete

Records are deleted via HTTP DELETE. 

curl -u token:token -X DELETE https://myapp.kickserv.com/jobs/[job number]/time_entries/[time entry id].xml

Tasks

List

Records are returned 30 at a time. 

curl -u token:token https://myapp.kickserv.com/tasks.xml

Additional records can fetched by passing a page parameter. 

curl -u token:token https://myapp.kickserv.com/tasks.xml?page=2

Tasks can be filtered by the assigned employee. 

curl -u token:token https://myapp.kickserv.com/tasks.xml?employee_number=123

Tasks can be filtered by completed state. 

curl -u token:token https://myapp.kickserv.com/tasks.xml?completed=[true|false]

Tasks can be filtered by date based on these smart values:

  • today
  • tomorrow
  • yesterday
  • this_week
  • next_week
  • last_week
  • this_month
  • next_month
  • last_month
curl -u token:token https://myapp.kickserv.com/tasks.xml?scheduled_at=today

Show

curl -u token:token https://myapp.kickserv.com/tasks/[id].xml

Create

Records are added via HTTP POST. The Content-Type header must be set to 'application/xml'. 

curl -u token:token -H 'Content-Type: application/xml' -d "<task><name>do this</name><scheduled_at>1/2/2009 09:30pm</scheduled_at></task>" https://myapp.kickserv.com/tasks.xml

Update

Records are updated via HTTP PUT. The Content-Type header must be set to 'application/xml'. 

curl -u token:token -X PUT -H 'Content-Type: application/xml' -d "<task><scheduled_at>1/23/2009 11:30am</scheduled_at></task>" https://myapp.kickserv.com/tasks/[id].xml

Delete

Records are deleted via HTTP DELETE. 

curl -u token:token -X DELETE https://myapp.kickserv.com/tasks/[id].xml

Customer notes

List

curl -u token:token https://myapp.kickserv.com/customers/[customer number]/notes.xml

Show

curl -u token:token https://myapp.kickserv.com/customers/[customer number]/notes/[note id].xml

Create

Records are added via HTTP POST. The Content-Type header must be set to 'application/xml'. 

curl -u token:token -H 'Content-Type: application/xml' -d "<note><note>bar</note></note>" https://myapp.kickserv.com/customers/[customer number]/notes.xml

Update

Records are updated via HTTP PUT. The Content-Type header must be set to 'application/xml'. 

curl -u token:token -X PUT -H 'Content-Type: application/xml' -d "<note><note>bar</note></note>" https://myapp.kickserv.com/customers/[customer number]/notes/[note id].xml

Delete

Records are deleted via HTTP DELETE. 

curl -u token:token -X DELETE https://myapp.kickserv.com/customers/[customer number]/notes/[note id].xml

Job notes

List

curl -u token:token https://myapp.kickserv.com/jobs/[job number]/notes.xml

Show

curl -u token:token https://myapp.kickserv.com/jobs/[job number]/notes/[note id].xml

Create

Records are added via HTTP POST. The Content-Type header must be set to 'application/xml'. 

curl -u token:token -H 'Content-Type: application/xml' -d "<note><note>foo</note></note>" https://myapp.kickserv.com/jobs/[job number]/notes.xml

Update

Records are updated via HTTP PUT. The Content-Type header must be set to 'application/xml'. 

curl -u token:token -X PUT -H 'Content-Type: application/xml' -d "<note><note>bar</note></note>" https://myapp.kickserv.com/jobs/[job number]/notes/[note id].xml

Delete

Records are deleted via HTTP DELETE. 

curl -u token:token -X DELETE https://myapp.kickserv.com/jobs/[job number]/notes/[note id].xml