Help » ServiceSidekick API

ServiceSidekick API

Introduction

The ServiceSidekick 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 ServiceSidekick account. An API token should be treated like your normal ServiceSidekick 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 http://myapp.servicesidekick.com/customers.xml
Additional records can fetched by passing a page parameter.
curl -u token:token http://myapp.servicesidekick.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 http://myapp.servicesidekick.com/customers.xml?service_zip_code=55555
The following relational data can be included:
  • contacts
  • jobs
  • tasks
  • notes
  • tax_entity
curl -u token:token http://myapp.servicesidekick.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 http://myapp.servicesidekick.com/jobs.xml?only=customer_number,name
Show
curl -u token:token http://myapp.servicesidekick.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>" http://myapp.servicesidekick.com/customers.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 "<customer><name>New name</name></customer>" http://myapp.servicesidekick.com/customers/[customer number].xml
Delete
Records are deleted via HTTP DELETE.
curl -u token:token -X DELETE http://myapp.servicesidekick.com/customers/[customer number].xml

Jobs

List
Records are returned 30 at a time.
curl -u token:token http://myapp.servicesidekick.com/jobs.xml
Additional records can fetched by passing a page parameter.
curl -u token:token http://myapp.servicesidekick.com/jobs.xml?page=2
Scope by customer number to return jobs for a particular customer.
curl -u token:token http://myapp.servicesidekick.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 http://myapp.servicesidekick.com/jobs.xml?scheduled=today
Jobs can filtered by state based on these smart values:
  • in_progress
  • completed
  • uncompleted
curl -u token:token http://myapp.servicesidekick.com/jobs.xml?state=uncompleted
Jobs can be filtered by employee.
curl -u token:token http://myapp.servicesidekick.com/jobs.xml?employee_number=123
Jobs can be filtered by job type.
curl -u token:token http://myapp.servicesidekick.com/jobs.xml?job_type_id=123
Jobs can be filtered by job status.
curl -u token:token http://myapp.servicesidekick.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 http://myapp.servicesidekick.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 http://myapp.servicesidekick.com/jobs.xml?only=job_number,name
Show
curl -u token:token http://myapp.servicesidekick.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>" http://myapp.servicesidekick.com/customer/[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>" http://myapp.servicesidekick.com/jobs/[job number].xml
Delete
Records are deleted via HTTP DELETE.
curl -u token:token -X DELETE http://myapp.servicesidekick.com/jobs/[job number].xml

Employees

List
curl -u token:token http://myapp.servicesidekick.com/employees.xml
Show
curl -u token:token http://myapp.servicesidekick.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>" http://myapp.servicesidekick.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>" http://myapp.servicesidekick.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>" http://myapp.servicesidekick.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 http://myapp.servicesidekick.com/jobs/[job number]/time_entries.xml
Show
curl -u token:token http://myapp.servicesidekick.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>" http://myapp.servicesidekick.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>" http://myapp.servicesidekick.com/jobs/[job number]/time_entries/[time entry id].xml
Delete
Records are deleted via HTTP DELETE.
curl -u token:token -X DELETE http://myapp.servicesidekick.com/jobs/[job number]/time_entries/[time entry id].xml

Tasks

List
Records are returned 30 at a time.
curl -u token:token http://myapp.servicesidekick.com/tasks.xml
Additional records can fetched by passing a page parameter.
curl -u token:token http://myapp.servicesidekick.com/tasks.xml?page=2
Tasks can be filtered by the assigned employee.
curl -u token:token http://myapp.servicesidekick.com/tasks.xml?employee_number=123
Tasks can be filtered by completed state.
curl -u token:token http://myapp.servicesidekick.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 http://myapp.servicesidekick.com/tasks.xml?scheduled_at=today
Show
curl -u token:token http://myapp.servicesidekick.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>" http://myapp.servicesidekick.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>" http://myapp.servicesidekick.com/tasks/[id].xml
Delete
Records are deleted via HTTP DELETE.
curl -u token:token -X DELETE http://myapp.servicesidekick.com/tasks/[id].xml

Customer notes

List
curl -u token:token http://myapp.servicesidekick.com/customers/[customer number]/notes.xml
Show
curl -u token:token http://myapp.servicesidekick.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>foo</note></note>" http://myapp.servicesidekick.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>" http://myapp.servicesidekick.com/customers/[customer number]/notes/[note id].xml
Delete
Records are deleted via HTTP DELETE.
curl -u token:token -X DELETE http://myapp.servicesidekick.com/customers/[customer number]/notes/[note id].xml

Job notes

List
curl -u token:token http://myapp.servicesidekick.com/jobs/[job number]/notes.xml
Show
curl -u token:token http://myapp.servicesidekick.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>" http://myapp.servicesidekick.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>" http://myapp.servicesidekick.com/jobs/[job number]/notes/[note id].xml
Delete
Records are deleted via HTTP DELETE.
curl -u token:token -X DELETE http://myapp.servicesidekick.com/jobs/[job number]/notes/[note id].xml