IMPORTANT NOTE ABOUT THIS API DOCUMENTATION:


The API documentation has been moved to http://www.dovico.com/developer/API_doc/index.htm.



The Content of this wiki will be deleted on Friday July 20th, 2018.

PLEASE UPDATE YOUR BOOKMARKS AS REQUIRED

What's Changed


Important note about API versions


If you are using Dovico Timesheet version 13 or below, you should use API version 5. If using version 14, use API version 6.



Sept 21, 2017


Changes to GETs of Time Entries and Expense Entries with a new Return Currency query string after the date range filter sections. Applies to all versions




July 19, 2017


Version 6 changes listed further down the page

Version 5 changes


General note on changes to version 5
If the database is less than 20.0 (Dovico Timesheet v13.x) then things will continue to work as they do now. If the database is 20.0 (Dovico Timesheet v14) then there were some changes that we need to handle.


Assignments
GET /Assignments
  • Prorate - This property has been dropped from the database
    • We will hard code this to 1 if the data returned is an employee-level assignment (still returns N/A if not an employee-level assignment. 0 or -1 would throw off any calculations. a multiplication of 1 is still the original number)
  • ETC - Although still in the database, the plan is that this field will be dropped
    • We will hard code this to -1 if the data returned is an employee-level assignment (still returns N/A if not an employee-level assignment)
  • Hide - Although still in the database, the plan is that this field will be dropped.
    • We will +hard code+ it to *F* if the data returned is an employee-level assignment _(still returns N/A if not an employee-level assignment)_

POST /Assignments
and
PUT /Assignments
  • ETC - This property has been dropped from the database. Ignored
  • Hide – This property has been dropped from the database. Ignored


Custom Terminology
GET /CustomTerminology
  • Team - Pulled from the UI but still exists in the db. The UI now uses the custom terminology for Employee and add on Group (<E> Group, <E> Groups)
    • The values held in the database need to be ignored and treated as if they don't exist because they may be dropped at any point.
    • A hard coded value of "<E> Group"/"<E> Groups" will be returned to match what Dovico Timesheet is doing.
  • Billing - Pulled from the UI but still exists in the db but is ignored and treated as if it does not exist because it may be dropped.
    • A hard coded value of 'Billing'/'Billing' will be returned
  • Project status has been reduced to Draft, Active, Completed
    • Estimate → value of Draft (no change here: Prefs.STAEST)
    • Quotation will return a hard coded string "Quotation"
    • Active → value of Active (no change here: Prefs.STAACT)
    • Rejected will return a hard coded string "Rejected"
    • Terminated will return a hard coded string "Terminated"
    • Finished → value of Completed (no change here: Prefs.STAFIN)
  • Billing By has been dropped
    • BillingBy nodes will return hard coded strings "Fixed Cost", "Actual Hours", and "Estimated Hours"


Employees
GET /Employees
  • SoftwareAccess
    • In the database, this field now holds: A - Active, D - Deactivated, I - Invited, E - Expired
    • Return N if the db holds 'D', 'I', or 'E'
    • Determine if the employee is a TET-Only user or Manager and returns T or B based on that check if the db holds 'A'
  • Number has been dropped - Return an empty string

POST /Employees
and
PUT /Employees
  • SoftwareAccess
    • A value of N is recorded to the db as D (deactivated)
    • A value of T or B is recorded to the db as A (active)
  • Number - The value is ignored and is no longer be validated (if the string is too long for the db, etc) since it no longer exists in the database
  • Email - This is now a required field.



Tasks
GET /Tasks
  • Global - Removed from the database
    • Hard coded to return F
  • Prorate -Removed from the database
    • Hard coded to return 1 (1 because any value multiplied by 1 keeps its original value...0 or -1 would change results)

PUT /Tasks
  • Global - Removed from the database.
  • Prorate - Removed from the database.

POST /Tasks
  • Global - Removed from the database
  • Prorate - Removed from the database
  • ProjectID - A new ProjectID property has been added to the POST call data that indicates which project the task belongs to. This is a required value for all POST Task calls (version 1+).


Projects
GET /Projects
  • Status
    • 0 (draft) will get returned as E (estimate)
    • 1 (active) will get returned as A (active)
    • 2 (completed) will get returned as F (finished)
  • BillingBy
    • 0 (employee hourly), 1 (task hourly), and 2 (project hourly) will get returned as A (Actual Hours)
    • 3 (fixed project amount) will get returned as F (Fixed Costs)
  • PreventEntries
    • Hide tasks and prevent entries have been combined as one checkbox in the UI (not in the db yet but we will treat it like it has been)
    • Now returns the value that's held by HideTasks
  • TimeBillableByDefault
    • This has been dropped from the UI (not yet dropped from the database but we will treat it like it has been)
    • Hard coded to T

GET /Project Statistics
  • HoursWithETC
    • Although not yet pulled from the database it will be at some point so we will treat it as if it isn't there.
    • HoursWithETC will now just return the same values as Hours

NOTE: Get Project Statistics had to be adjusted from a SECOBJ_ASSIGNMENT to SECOBJ_PROJECT since the assign security permission has been dropped in DTv14. Statistics are now considered to be part of the project's permissions


POST /Projects
And
PUT /Projects
  • Status
    • This value will be ignored since a change to the status is not simply a change of a flag anymore (it would need to trigger business logic to publish the project for example)
  • BillingBy
    • E (Estimated Hours) or A (Actual Hours) will get saved as 0 (Employee hourly)
    • F (Fixed Costs) will get saved as 3 (Fixed project amount)
  • PreventEntries - Ignored
  • TimeBillableByDefault - Ignored

Note: For PUT calls, If the project is marked Complete, a validation error will be returned since the project is now read-only.



Version 6 changes


Assignments
GET /Assignments
  • Prorating – Removed
  • ETC – Removed
  • Hide - Removed

POST /Assignments
and
PUT /Assignments
  • ETC – Removed
  • Hide - Removed


Custom Terminology
GET /CustomTerminology
  • Team property - Renamed from Team to EmployeeGroup
  • Billing - Removed from the return data
  • Fixed Project Amount - New property added to the return data the same way that Quantity is returned: <FixedProjectAmount>Fixed Project Amount</FixedProjectAmount>
  • ProjectStatus
    • Estimate node name renamed to Draft
    • Quotation node removed from the return data
    • Active node (no change)
    • Rejected node name removed from the return data
    • Terminated node removed from the return data
    • Finished node name renamed to Completed
  • BillingBy - Removed from the return data



Employees
GET /Employees
  • Team - Renamed from Team to EmployeeGroup
  • SoftwareAccess - The 3rd party apps need to know if a person is a manager or not so this field needs to continue to return the data the way it did in versions 1-5...
    • In the database, this field now holds: A - Active, D - Deactivated, I - Invited, E - Expired
    • Return N if the db holds 'D', 'I', or 'E'
    • We will determine if the employee is a TET-Only user or Manager and will return T or B based on that check if the db holds 'A'
  • Number - Removed from the return data

POST /Employees
and
PUT /Employees
  • TeamID - Renamed to EmployeeGroupID
  • SoftwareAccess - Since the GETs need to remain the same as they were in versions 1-5, for consistency sake, the POST/PUT calls remain the same too (so that GETs aren't dealing with different data than the POST/PUT calls)
    • A value of N is recorded to the db as D (deactivated)
    • A value of T or B is recorded to the db as A (active)
  • Number - Removed. No longer part of the POST/PUT data
  • Email - This is now a required field


Project
GET /Projects
  • Status - Return one of the new values:
    • 0 (draft)
    • 1 (active)
    • 2 (completed)
  • ProjectObjective - New property added that returns one of the following values
    • 0 (track time only)
    • 1 (track time for costing - pay rate x hours)
    • 2 (track time for billing - bill rate x hours)
    • 3 (track time for costing and billing)
  • BillingBy - Return one of the new values
    • 0 (employee hourly)
    • 1 (task hourly)
    • 2 (project hourly)
    • 3 (fixed project amount)
  • BillingByProjectRate - New property added
    • 0 is returned if the BillingBy value is not Project Hourly (2)
  • BudgetedHoursType - New property added that returns one of the following values
    • 0 (no budget)
    • 1 (budgeted hours per task)
    • 2 (project budgeted hours)
  • BudgetedHoursProjectHours - New property added
    • 0 is returned if the BudgetedHoursType value is not Project budgeted hours (2)
  • PreventEntries - Removed from the return data
  • TimeBillableByDefault - Removed from the return data


GET Projects/{sProjectID}/Statistics/
  • HoursWithETC - Removed


POST /Projects
and
PUT /Projects
  • Status - Removed. No longer part of the POST/PUT data since this is no longer just a flag (changing this value needs to trigger business logic changes like publishing the project for example)
  • ProjectObjective - New property accepts one of the following values
    • 0 (track time only)
    • 1 (track time for costing - pay rate x hours)
    • 2 (track time for billing - bill rate x hours)
    • 3 (track time for costing and billing)
  • BillingBy - Now accepts one of the following values
    • 0 (employee hourly)
    • 1 (task hourly)
    • 2 (project hourly)
    • 3 (fixed project amount)
  • BillingByProjectRate - New property added
    • Must be a valid US English number
    • Is ignored if the BillingBy value is not 2 (project hourly)
  • BudgetedHoursType - New property added that accepts one of the following values
    • 0 (no budget)
    • 1 (budged hours per task)
    • 2 (project budgeted hours)
  • BudgetedHoursProjectHours - New property added
    • Must be a valid US English number
    • Is ignored if the BudgetedHoursType value is not 2 (project budgeted hours)
  • PreventEntries - Removed
  • TimeBillableByDefault - Removed

Note: For PUT calls, if the project is marked Complete, a validation error will be returned since the project is now read-only


Tasks
Get /Tasks
  • Project - New fields that indicates which project the task belongs to (ID, Name, and GetItemURI)
  • Global - Removed
  • Prorate - Removed

PUT /Tasks
  • Global - Removed
  • Prorate - Removed

POST /Tasks
  • ProjectID - New field that needs to be specified to identify which project the task belongs to
  • Global - Removed
  • Prorate - Removed


Time Entries
GET /TimeEntries
  • Prorate - Removed from the return data


Task Templates
A new resource added so that apps can pull Task Template information
  • GET /TaskTemplates
  • POST /TaskTemplates
  • PUT /TaskTemplates
  • DELETE /TaskTemplates

If GET /TaskTemplates is called, but we're dealing with a DTv13 build, we will simply do a GET Tasks call
One thing to note is that if you make a call with version 6 or greater, and the server is DTv13, the API version will be modified to be 5 so that the GET Task call will not return a 404 (GET Tasks of version 6+ on DTv13 servers are not implemented because version 6 contains new calls for DTv14 servers)...There won't be any errors but looking at the return data and you will see different URIs than what you put in.


October 28, 2015

Added a new way of filtering ($filter query string) to the following calls - for versions 1 through 5
  • Clients
  • Employees
  • ExpenseCategories
  • ExpenseEntries
  • Projects
  • Tasks
  • Teams
  • TimeEntries


October 16, 2014

Added Bulk PUT calls for the following (versions= 4 and 5 only)
  • Assignments
  • Clients
  • Employees
  • Expense Categories
  • Expense Entries
  • Projects
  • Sheets
  • Tasks
  • Teams
  • Time Entries

Added optional query string 'ForTimeEntry' for the GET requests of Assignments (applies to all versions)
If ‘T’ is specified (e.g. GET /Assignments/?ForTimeEntry=T&version=5) then the logged in user’s permissions are ignored and the request is treated as if the logged in user is a TET-Only user returning only the assignments that they’re assigned to, that are not hidden, where the project is Estimate or Active, within the date range if hide tasks/prevent entries is on, etc.

Corrected an issue with the result from the Authentication call (applies to all versions)





July 11, 2014

This is the 5th release of the Hosted Service API.
  • GET of Assignments now returns TimeBillableByDefault and ExpensesBillableByDefault elements (version=5 only)
  • GET of Employees now returns SecurityGroup and SoftwareAccess fields (version=5 only)
  • POST/PUT of Employees now allow the TeamID, SecurityGroupID, and SoftwareAccess fields to be specified (version=5 only)
  • SecurityGroupID and SoftwareAccess require a trusted consumer secret/3rd party developer token in order to specify the values
  • GET of Employee TET-Options (GET ‘Employees/Me/Options/’) (available to all versions)
  • GET of Security Groups (GET ‘SecurityGroups/’) (available to all versions)
  • Time entries now enforce limited access at the employee level (applies to all versions)





April 15, 2014


This is the 4th release of the Hosted Services API.

  • Add a call (Bulk update) for Time Entries.


February 18, 2014

In this release (version 4)
  • Version 4 released
  • Version numbers updated to 4 in all XML and JSON examples for applicable called (some older calls removed from the table of contents)
  • Assignments
    • Can no longer do a PUT for a task level assignment.
    • StartDate/FinishDate removed from Field for Task when doing a POST.
  • TimeEntries
    • Update to the return data of the bulk GET calls now return CustomField nodes.




December 20, 2013

Version 3 changes
  • Version 3 released
  • Version numbers updated from 2 to 3 in all XML and JSON examples for applicable calls (excluded Time Entries v1, Expense Entries v1 and v2, Projects v1 and v2)
  • Assignments
    • JSON examples added
    • Bug Fix - Start/finish dates for POST/PUT of Task level assignment. For the GET of non-Employee level (and non-project level) assignments we return N/A for the Start/Finish dates. DOVICO Timesheet does not set the Start/Finish dates on non-Employee level assignments
  • Expenses v3 - added Expense Attachments (GET, PUT/POST, DELETE)
  • Expenses v1, v2 and v3 - Added Approval and Rejection of Expense Sheets
  • Added Custom Terminology call - all versions
  • Employees - Add employee regional settings (GET)





October 1, 2013

Version 2 changes
  • Add a call (Authenticate) to authenticate users via their Dovico login credentials (Company name, User ID and Password) rather than a Data Access Token.



April 25, 2013

  • A call for Project Expense totals now exists (GET ‘Projects/{ProjectID}/ExpenseTotals/’)
  • It is now possible to include a Title value in the message body when submitting time to override the default title

Documentation change
  • JSON examples added to Time Entries and Expenses
  • The details about the return result for Sheet calls were indicating that the Status could be A, U, N, or R. Sheets only exist as U or R




April 10, 2013

Teams API call
  • New Call

JSON examples added to Tasks, ExpenseCategories, and Employees
Tasks: TaskGroup ID was indicating -1 for the [None] record but it should have been 0 (return value was ok, just a documentation issue)
ExpenseCategories: Asterisk also removed from the PUT XML’s UnitDescription field (all fields are optional for a PUT call)
Employees: Team ID was indicating -1 for the [None] record but it should have been 0 (return value was ok, just a documentation issue)
Clients: Region ID was indicating -1 for the [None] record but it should have been 0 (return value was ok, just a documentation issue)
Projects: ProjectGroup ID was indicating -1 for the [None] record but it should have been 0 (return value was ok, just a documentation issue)




March 28, 2013

GET Projects/{ProjectID}/Statistics: Returns the same statistics that you get in Dovico Timesheet’s Project Assignments view (View Statistics – F8)
PUT Sheets/{SheetID}/: Allows the adjustment of a sheet’s Title or Description

Several bugs that were identified in the API, have now been fixed…
  1. When submitting an expense sheet, it was using the name of the logged in person. Not a problem if the logged in person is the one the sheet belongs to but, if the logged in person is an admin, the sheet title was incorrect. (bug # 70)
  2. The previous/next page URI for the GET of Custom Field Templates by Type was incomplete…(bug #71)



March 13, 2013

Supports accepting and returning data as JSON
Sheets API call
  • New Call


March 8, 2012

Time Entries API call
  • The Client Name has been added
  • Billable flag has been added
  • OT Charge rate has been added
  • OT Wage rate has been added
  • The documentation for the version 1 call has been archived but is available using this link.

For all other API calls
  • The version number in the code examples has been updated to version 2.

Summary and Getting Started pages
  • The version number in the code examples has been updated to version 2.