
The Beta release of our documentation is available at:
http://developer.mavenlink.com/beta/
Time Entries in Mavenlink allow users to track timed items of work. Once created, they can be included in invoices generated subsequently.
Time Entry objects have the following readable attributes:
id
- the internal time entry IDcreated_at
- the date the time entry was created in Mavenlinkupdated_at
- the date the time entry was last updateddate_performed
- the date the time entry was performedstory_id
- the internal story ID of the story this time entry is associated withtime_in_minutes
- the amount of time entered in minutesbillable
- whether this time entry is billable timenotes
- any notes added to the time entryrate_in_cents
- the hourly rate for this time entry in centscurrency
- the currency of this time entry's ratecurrency_symbol
- the currency symbol for this time entry's currencycurrency_base_unit
- the amount of cents in each of the currency's dollars, for example 100 for USD.user_can_edit
- whether the current user can edit this time entry or nottaxable
was this time entry marked as taxable when invoiced?workspace_id
- the internal ID of the project workspace this time entry is associated withuser_id
- the internal ID of the user who created this time entryapproved
- whether the time entry has been approvedYou can access all your time entries as follows:
curl "https://api.mavenlink.com/api/v1/time_entries.json"
The resulting JSON will be an array of objects. The entries will be sorted by the date_performed
field in descending order by default.
You can include time entries' associations with the include
param. For example, to include returned time entries' creators and stories, you would do the following:
curl "https://api.mavenlink.com/api/v1/time_entries.json?include=user,story"
In this example, our API will ensure that the returned JSON contains top-level keys called users
and stories
where you can find associated data by inspecting time entries' user_id
and story_id
fields. See Object Associations to learn more. The following associations can be requested through the API:
workspace
- the workspace (project) that owns this time entry, returned in the workspaces
top-level keyuser
- the user object of the time entry creator, returned in the users
top-level keystory
- linked story (task), returned in the stories
top-level keyThe Mavenlink API allows you to pass in filter conditions to allow the retrieval of only certain time entries.
workspace_id
- only return time entries from the given workspace (project)from_archived_workspaces
- (default false
) also return time entries from workspaces that have been archiveddate_performed_between
- Requires a colon separated pair of dates in YYYY-MM-DD format. If a date is not passed in, it is interpreted as negative or positive infinitycreated_before
- include time entries created before the given timestamp (in ISO 8601 format)created_after
- include time entries created after the given timestamp (in ISO 8601 format)updated_before
- include time entries updated before the given timestamp (in ISO 8601 format)updated_after
- include time entries updated after the given timestamp (in ISO 8601 format)For example to get all time entries from Workspace 1:
curl "https://api.mavenlink.com/api/v1/time_entries.json?workspace_id=1"
To get all time entries created on July 4th, 2013:
curl "https://api.mavenlink.com/api/v1/time_entries.json?created_at_between=2013-07-04T000000:2013-07-04T115959"
Valid orders are:
date_performed
created_at
updated_at
As with all resources, you can request either GET /api/v1/time_entries.json?only=5
or GET /api/v1/time_entries/5.json
. In both cases, default filters will be applied. Therefore, you won't receive Time Entries from archived workspaces (and will receive a 404 status on the "show" route) unless you provide the from_archived_workspaces:true
filter.
Mavenlink Time Entries take the following parameters:
workspace_id
- (required) the internal ID of the project workspace this time entry is associated withdate_performed
- (required) the date the activity for which the time is being entered was performed, format: YYYY-MM-DDtime_in_minutes
- (required) the amount of time entered in minutesbillable
- (optional) whether this time entry is billable time, you must also provide rate_in_cents
if you set billable
to true
. If you don't provide this parameter, billable
will be defaulted to the value of the billable
flag of its associated Story if any, otherwise to true
notes
- (optional) any notes added to the time entryrate_in_cents
- (optional, required if billable is true) the hourly rate for this time entry in cents, you must also set billable
to true
when setting thisrole_id
- (optional) the internal ID of the role this time entry is associated withstory_id
- (optional) the internal ID of the story this time entry is associated withuser_id
- (optional) the internal ID of the user the time entry is associated with. This parameter is ignored unless the authorizing user has financial access in the workspace and is on the consultants team (or if the authorizing user is an account administrator and has proxy permissions via an account member with those permissions).You can create a Time Entry in a workspace as follows:
curl -d "time_entry[date_performed]=01/01/2012" -d "time_entry[time_in_minutes]=120" -d "time_entry[workspace_id]=10" "https://api.mavenlink.com/api/v1/time_entries.json"
The response will contain a JSON representation of the newly created time entry or an error message indicating which arguments are missing or erroneous
You can create multiple Time Entries in a single request if you send a time_entries
array. An example would be to send a request with the following parameters encoded as application/json
:
{"time_entries": [{"workspace_id": 2, "date_performed": "2015-02-08", "time_in_minutes": 100 }, {"workspace_id": 2, "date_performed": "2015-02-09", "time_in_minutes": 32}]}
Using curl, that request could be sent as:
curl -H "Content-Type: application/json" -d '{"time_entries": [{"workspace_id": 2, "date_performed": "2015-02-08", "time_in_minutes": 100 }, {"workspace_id": 2, "date_performed": "2015-02-09", "time_in_minutes": 32}]}' "https://api.mavenlink.com/api/v1/time_entries.json"
You can edit Time Entries as follows:
curl -X PUT -d "time_entry[time_in_minutes]=120" "https://api.mavenlink.com/api/v1/time_entries/1.json"
The response will contain the JSON representation of the updated Time Entry or an error message indicating which arguments are missing or erroneous.
Any of the required or optional create parameters can be edited by an update.
You can delete Time Entries as follows:
curl -X DELETE "https://api.mavenlink.com/api/v1/time_entries/1.json"
The response will have no content and HTTP 204 status code if the Time Entry has been successfully deleted, or a JSON error message indicating why the Time Entry could not be deleted.