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 projects filtered by the parameters provided. Admin can see all projects on the subscription, while non-admins can only access the projects they are assigned.

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>
    <owner_id type="integer">14</owner_id>
    <opened_on type="date">2006-01-01</opened_on>
    <closed_on type="date"></closed_on>
    <created_at type="datetime">Tue, 07 Oct 2008 14:46:16 -0400</created_at>
    <updated_at type="datetime">Tue, 07 Oct 2008 14:46:16 -0400</updated_at>
   # The following attributes are derived and provided for informational purposes:
    <client_name>Starfleet Command</client_name>
    <sum_hours type="float">22.5</sum_hours>
    <user_count type="integer">2</user_count>
   # All of the tasks for the project are returned as well
    <tasks type="array">
      <task>
        ...
      </task>
    </tasks>
  </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 and available for time entries (open).

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. Either a start and end date have to be provided or an updated_at time. The entries will be in the start and end date range or they will be after the updated_at time depending on what criteria is provided. Each of the optional parameters will further filter the response.

Required Parameters Optional Parameters URL
  • email
  • password
  • start_date
    end_date
    OR updated_at
  • project_id
  • task_id
  • user_id
  • user_email
  • 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.00</hours>
    <notes>Had trouble with tribbles.</notes>
    <billable>true</billable> # Billable is an attribute inherited from the task
    <billed>true</billed>     # Billed is an attribute to track whether the entry has been invoiced
    <created_at type="datetime">Tue, 07 Oct 2008 14:46:16 -0400</created_at>
    <updated_at type="datetime">Tue, 07 Oct 2008 14:46:16 -0400</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>
    <sum_hours type="float">2.00</sum_hours>
    <budget type="float">10.00</budget>
    <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">Tue, 07 Oct 2008 14:46:16 -0400</created_at>
    <updated_at type="datetime">Tue, 07 Oct 2008 14:46:16 -0400</updated_at>
  </user>
</users>

create_entry : The create_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
  • date
  • notes
  • /api/create_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">Tue, 07 Oct 2008 14:46:16 -0400</created_at>
  <updated_at type="datetime">Tue, 07 Oct 2008 14:46:16 -0400</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">Tue, 07 Oct 2008 14:46:16 -0400</created_at>
    <updated_at type="datetime">Tue, 07 Oct 2008 14:46:16 -0400</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>

update_entry : The update_entry method will allow you to modify attributes of an existing entry. The only required parameter is the id of the entry. Additional parameters must be provided for any attribute that you wish to update. For example, if you are only changing the billed attribute, your post should only include the required parameters and the billed parameter.

Required Parameters Optional Parameters URL
  • email
  • password
  • id
  • hours
  • date
  • billed
  • task_id
  • user_id
  • notes
  • /api/update_entry

This document is subject to change. Last updated March 8th, 2012.