Time Entries

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 ID
• created_at - the date the time entry was created in Mavenlink
• updated_at - the date the time entry was last updated
• date_performed - the date the time entry was performed
• story_id - the internal story ID of the story this time entry is associated with
• time_in_minutes - the amount of time entered in minutes
• billable - whether this time entry is billable time
• notes - any notes added to the time entry
• rate_in_cents - the hourly rate for this time entry in cents
• currency - the currency of this time entry's rate
• currency_symbol - the currency symbol for this time entry's currency
• currency_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 not
• taxable was this time entry marked as taxable when invoiced?
• workspace_id - the internal ID of the project workspace this time entry is associated with
• user_id - the internal ID of the user who created this time entry
• approved - whether the time entry has been approved

Fetching Time Entries

You 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.

Associated Objects

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 key
• user - the user object of the time entry creator, returned in the users top-level key
• story - linked story (task), returned in the stories top-level key

Filtering Time Entries

The 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 archived
• date_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 infinity
• created_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"

Ordering Time Entries

Valid orders are:

• date_performed
• created_at
• updated_at

Getting a Single Time Entry

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.

Creating a New Time Entry

Mavenlink Time Entries take the following parameters:

• workspace_id - (required) the internal ID of the project workspace this time entry is associated with
• date_performed - (required) the date the activity for which the time is being entered was performed, format: YYYY-MM-DD
• time_in_minutes - (required) the amount of time entered in minutes
• billable - (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 entry
• rate_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 this
• role_id - (optional) the internal ID of the role this time entry is associated with
• story_id - (optional) the internal ID of the story this time entry is associated with
• user_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

Creating Multiple Time Entries

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"

Updating an Existing Time Entry

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.

Destroying an Existing Time Entry

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.