The Tick API

Introduction

This document is intended for 3rd parties wishing to integrate their applications with Tick's online services.

Terms of Use

Molehill is the company behind Tick and reserves the right to modify, expand, or terminate API services at any time for any or no reason. By using this API, you acknowledge and agree to the following terms. The availability and the terms upon which it is available are continually under experimentation. Molehill may suspend or terminate your access to the Tick API or Molehill may change any of the API specifications, protocols, or methods of access for any or no reason and will bear no liability for such decisions. It is solely your responsibility at all times to be prepared to manage your accounts and conduct your business without access to the Tick API. Molehill does not represent or warrant, and specifically disclaims that the Tick API will be available without interruption or without bugs.

Methods

The following section will address each of the methods made available through the Tick API. All methods are made available by using an HTTP POST to the appropriate Tick URL for the method being accessed. Included with each POST are parameters required or optional for each method. If the post is successful, the server will respond with an XML formatted response. If the post fails for any reason, the server will respond simply with an HTTP status code and a message indicating the cause of the failure in the body of the response.

The email and password parameters are always required to authorize

For example, if one wanted to retrieve a list of clients, they would execute an HTTP post with the the required parameters, email and password as follows:

https://company.tickspot.com/api/clients?email=me@company.com&password=mypass

If the email and password combination failed authentication, the server would respond with an HTTP status 401. A successful post will result in a response with an HTTP status of 200 and a body containing the data in an XML format:

<?xml version="1.0" encoding="UTF-8"?>
<clients type="array">
  <client>
    <id type="integer">12341</id>
    <name>Starfleet Command</name>
  </client>
  <client>
    <id type="integer">12342</id>
    <name>The Vulcans</name>
  </client>
  <client>
    <id type="integer">12343</id>
    <name>The Cardassians</name>
  </client>
</clients>

clients : The clients method will return a list of all clients and can only be accessed by admins on the subscription.

Required Parameters Optional Parameters URL
  • email
  • password
  • open [true|false]
  • /api/clients

Sample Output

<?xml version="1.0" encoding="UTF-8"?>
<clients type="array">
  <client>
    <id type="integer">12341</id>
    <name>Starfleet Command</name>
  </client>
  <client>
    <id type="integer">12342</id>
    <name>The Vulcans</name>
  </client>
  <client>
    <id type="integer">12343</id>
    <name>The Cardassians</name>
  </client>
</clients>

projects : The projects method will return a list of all projects and can only be accessed by admins on the subscription.

Required Parameters Optional Parameters URL
  • email
  • password
  • project_id
  • open [true|false]
  • project_billable [true|false]
  • /api/projects

Sample Output

<?xml version="1.0" encoding="UTF-8"?>
<projects type="array">
  <project>
    <id type="integer">7</id>
    <name>Realign dilithium crystals</name>
    <budget type="float">50</budget>
    <client_id type="integer">4</client_id>
    <opened_on type="date">2006-01-01</opened_on>
    <closed_on type="date"></closed_on>
    <created_at type="datetime">Sun Dec 09 21:33:59 -0600 2007</created_at>
    <updated_at type="datetime">Sun Dec 09 21:33:59 -0600 2007</updated_at>
   # The following attributes are derived and provided for informational purposes:
    <sum_hours type="float">22.5</sum_hours>
    <user_count type="integer">2</user_count>
  </project>
</projects>

tasks : The tasks method will return a list of all the current tasks for a specified project and can only be accessed by admins on the subscription.

Required Parameters Optional Parameters URL
  • email
  • password
  • project_id
  • task_id
  • open [true|false]
  • task_billable [true|false]
  • /api/tasks

Sample Output

<?xml version="1.0" encoding="UTF-8"?>
<tasks type="array">
  <task>
    <id type="integer">14</id>
    <name>Remove converter assembly</name>
    <position type="integer">1</position>
    <project_id type="integer">2</project_id>
    <opened_on type="date">2006-01-01</opened_on>
    <closed_on type="date"></closed_on>
    <budget type="float">50</budget>
    <billable type="boolean">true</billable>
   # The following attributes are derived and provided for informational purposes:
    <sum_hours type="float">22.5</sum_hours>
    <user_count type="integer">2</user_count>
  </task>
</tasks>

clients_projects_tasks : The method will return a list of all clients, projects, and tasks that are assigned to the user.

Required Parameters Optional Parameters URL
  • email
  • password
  • none
  • /api/clients_projects_tasks

Sample Output

  <?xml version="1.0" encoding="UTF-8"?>
  <clients type="array">
    <client>
      ...
      <projects type="array">
        <project>
          ...
          <tasks type="array">
            <task>
              ...
            </task>
          </tasks>
        </project>
      </projects>
    </client>
  </clients>

entries : The entries method will return a list of all entries that meet the provided criteria. While the start date and end date are the only required parameters, each of the optional parameters will further filter the response.

Required Parameters Optional Parameters URL
  • email
  • password
  • start_date
  • end_date
  • project_id
  • task_id
  • user_id
  • client_id
  • entry_billable [true|false]
  • billed [true|false]
  • /api/entries

Sample Output

<?xml version="1.0" encoding="UTF-8"?>
<entries type="array">
  <entry>
    <id type="integer">24</id>
    <task_id type="integer">14</task_id>
    <user_id type="integer">3</user_id>
    <date type="date">2008-03-08</date>
    <hours type="float">1.0</hours>
    <notes>Had trouble with tribbles.</notes>
    <created_at type="datetime">Sun Dec 09 21:33:59 -0600 2007</created_at>
    <updated_at type="datetime">Sun Dec 09 21:33:59 -0600 2007</updated_at>
   # The following attributes are derived and provided for informational purposes:
    <user_email>scotty@enterprise.com</user_email>
    <task_name>Remove converter assembly</task_name>
    <project_name>Realign dilithium crystals</project_name>
    <client_name>Starfleet Command</client_name>
  </entry>
</entries>

recent_tasks : The users method will return a list of the most recently used tasks. This is useful for generating quick links for a user to select a task they have been using recently.

Required Parameters Optional Parameters URL
  • email
  • password
  • none
  • /api/recent_tasks

Sample Output

<?xml version="1.0" encoding="UTF-8"?>
<tasks type="array">
  <task>
    <id type="integer">14</id>
    <name>Remove converter assembly</name>
    <position type="integer">1</position>
    <project_id type="integer">2</project_id>
    <opened_on type="date">2006-01-01</opened_on>
    <closed_on type="date"></closed_on>
    <budget type="float"></budget>
    <billable type="boolean">true</billable>
  </task>
</tasks>

users : The users method will return a list of users.

Required Parameters Optional Parameters URL
  • email
  • password
  • project_id
  • /api/users

Sample Output

<?xml version="1.0" encoding="UTF-8"?>
<users type="array">
  <user>
    <id type="integer">2</id>
    <first_name>James</first_name>
    <last_name>Kirk</last_name>
    <email>james@idiggreenchicks.com</email>
    <created_at type="datetime">Thu Mar 13 16:20:23 -0400 2008</created_at>
    <updated_at type="datetime">Thu Mar 13 16:20:23 -0400 2008</updated_at>
  </user>
</users>

create_entry : The add_entry method will accept a time entry for a specified task_id and return the created entry along with the task and project stats.

Required Parameters Optional Parameters URL
  • email
  • password
  • task_id
  • hours
  • notes
  • date
  • none
  • /api/add_entry

Sample Output

  <?xml version="1.0" encoding="UTF-8"?>
  <entry>
    <id type="integer">77</id>
    <task_id type="integer">1</task_id>
    <user_id type="integer">1</user_id>
    <date type="date">2008-03-17</date>
    <hours type="float">2.5</hours>
    <notes>She can't take much more of this Captain</notes>
    <created_at type="datetime">Mon Mar 17 10:52:49 -0400 2008</created_at>
    <updated_at type="datetime">Mon Mar 17 10:52:49 -0400 2008</updated_at>
    <user_email type="text">scotty@ncc1701.com</user_email>
    <task>
      <id type="integer">1</id>
      <name>Remove converter assembly</name>
      <position type="integer">1</position>
      <project_id type="integer">1</project_id>
      <opened_on type="date">2006-01-01</opened_on>
      <closed_on type="date"></closed_on>
      <budget type="float"></budget>
      <billable type="boolean">true</billable>
     # The following attributes are derived and provided for informational purposes:
      <total_hours>4.5</total_hours>
      <user_count>1</user_count>
    </task>
    <project>
      <id type="integer">1</id>
      <name>Realign dilithium crystals</name>
      <budget type="float"></budget>
      <client_id type="integer">1</client_id>
      <opened_on type="date">2006-01-01</opened_on>
      <closed_on type="date"></closed_on>
      <created_at type="datetime">Mon Mar 17 10:52:49 -0400 2008</created_at>
      <updated_at type="datetime">Mon Mar 17 10:52:49 -0400 2008</updated_at>
     # The following attributes are derived and provided for informational purposes:
      <total_hours type="float">10.5</total_hours>
      <client_name>Starfleet Command</client_name>
    </project>
  </entry>

This document is subject to change. Last updated March 12, 2008.