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 https://myapp.servicesidekick.com/customers.xml
Additional records can fetched by passing a page parameter.
curl -u token:token https://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 https://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 https://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 https://myapp.servicesidekick.com/jobs.xml?only=customer_number,name
Show
curl -u token:token https://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>" https://myapp.servicesidekick.com/customers.xml
Note: If the 
customer_number
field is passed in, it will be ignored. Customer numbers are automatically assigned by ServiceSidekick. 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.servicesidekick.com/customers/[customer number].xml
Delete
Records are deleted via HTTP DELETE.
curl -u token:token -X DELETE https://myapp.servicesidekick.com/customers/[customer number].xml

Jobs

List
Records are returned 30 at a time.
curl -u token:token https://myapp.servicesidekick.com/jobs.xml
Additional records can fetched by passing a page parameter.
curl -u token:token https://myapp.servicesidekick.com/jobs.xml?page=2
Scope by customer number to return jobs for a particular customer.
curl -u token:token https://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 https://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 https://myapp.servicesidekick.com/jobs.xml?state=uncompleted
Jobs can be filtered by employee.
curl -u token:token https://myapp.servicesidekick.com/jobs.xml?employee_number=123
Jobs can be filtered by job type.
curl -u token:token https://myapp.servicesidekick.com/jobs.xml?job_type_id=123
Jobs can be filtered by job status.
curl -u token:token https://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 https://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 https://myapp.servicesidekick.com/jobs.xml?only=job_number,name
Show
curl -u token:token https://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>" https://myapp.servicesidekick.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.servicesidekick.com/jobs/[job number].xml
When creating or updating customers use the following examples when trying to specify Employees, Job Types 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.servicesidekick.com/jobs/[job number].xml
  • Job Type
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.servicesidekick.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.servicesidekick.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.servicesidekick.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.servicesidekick.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.servicesidekick.com/jobs/1/job_charges.xml

Employees

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

Customer notes

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

Job notes

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