Time Entries API
- List time entries
- Get a single time entry
- Create a time entry
- Update a time entry
- Remove a time entry
- Archive a time entry
- Trash a time entry
- Restore a time entry
- Fields
List time entries
List all time entries for an account:
GET /time_entries
Response
Status: 200 OK
[
{
"id": 195,
"date": "2016-03-28",
"correction": false,
"created_at": "2016-03-28T12:13:11-05:00",
"updated_at": "2016-03-28T12:13:11-05:00",
"time_spent": 120,
"organization": {
"id": 7,
"name": "Widget North America, Information Technology"
},
"person": {
"id": 7,
"name": "Chess Cole"
},
"time_allocation": {
"id": 4,
"group": "Project",
"name": "Transparency of Performance (TOP)",
"account": {
"id": "wna-it",
"name": "Widget N. America - IT"
},
"localized_group": "Project",
"localized_name": "Transparency of Performance (TOP)"
},
"service": {
"id": 36,
"name": "SAP Basis",
"localized_name": "SAP Basis"
},
"customer": {
"id": 8,
"name": "Widget North America, Human Resources"
},
"description": "Transaction response time testing for new HR features."
},
{
"id": 231,
"date": "2016-03-28",
"created_at": "2016-03-28T14:55:00-05:00",
"updated_at": "2016-03-28T14:57:00-05:00",
"time_spent": 10,
"organization": {
"id": 44,
"name": "Widget Data Center, External IT"
},
"person": {
"id": 57,
"name": "Tom Waters"
},
"request": {
"id": 70248,
"subject": "Expense reporting is slow",
"account": {
"id": "wna-it",
"name": "Widget N. America - IT"
},
"service": {
"id": 22,
"name": "Expense Reporting",
"localized_name": "Expense Reporting"
},
"customer": {
"id": 48,
"name": "Widget North America, Sales & Marketing"
}
}
},
"..."
]
The response contains these fields by default. Filtering and pagination are available to reduce/limit the collection of time entries.
Collection Fields
By default the following fields will appear in collections of time entries:
id
date
time_spent
person
request
(only when available) problem
(only when available) task
(only when available) project_task
(only when available) time_allocation
(only when available) service
customer
organization
description
deleted
created_at
updated_at
Obtain a different set of fields using the ?fields= parameter.
Note that the problem
, request
, task
and project_task
fields
cannot be specified using the ?fields= parameter.
These fields will appear when the time_allocation
field is specified.
Filtering
Filtering is available for the following fields:
id
source
sourceID
date
created_at
updated_at
deleted
person
Sorting
By default a collection of time entries is sorted ascending by id
.
The following fields are accepted by the ?sort= parameter:
id
date
created_at
updated_at
Get a single time entry
GET /time_entries/:id
Response
Status: 200 OK
{
"id": 195,
"date": "2016-03-28",
"deleted": false,
"correction": false,
"created_at": "2016-03-28T12:13:11-05:00",
"updated_at": "2016-03-28T12:13:11-05:00",
"time_spent": 120,
"organization": {
"id": 7,
"name": "Widget North America, Information Technology"
},
"person": {
"id": 7,
"name": "Chess Cole"
},
"time_allocation": {
"id": 4,
"group": "Project",
"name": "Transparency of Performance (TOP)",
"account": {
"id": "wna-it",
"name": "Widget N. America - IT"
},
"localized_group": "Project",
"localized_name": "Transparency of Performance (TOP)"
},
"service": {
"id": 36,
"name": "SAP Basis",
"localized_name": "SAP Basis"
},
"customer": {
"id": 8,
"name": "Widget North America, Human Resources"
},
"description": "Transaction response time testing for new HR features."
}
The response contains these fields.
Create a time entry
POST /time_entries
When creating a new time entry these fields are available.
Response
Status: 201 Created
{
"coverage": "...",
"...": "..."
}
The response contains all fields of the created time entry and is similar to the response in Get a single time entry
Update a time entry
PATCH /time_entries/:id
When updating a time entry these fields are available.
Response
Status: 200 OK
{
"date": "...",
"...": "..."
}
The response contains all fields of the updated time entry and is similar to the response in Get a single time entry
Remove a time entry
Remove a time entry with a specific ID.
DELETE /time_entries/:id
Response
Status: 204 No Content
Archive a time entry
POST /time_entries/:id/archive
Moves a given time entry to the Archive. This action requires the Account Administrator or Directory Administrator role in the account of the time entry.
Response
Status: 200 OK
{
"archived": "true",
"coverage": "...",
"...": "..."
}
The response contains all fields of the archived time entry and is similar to the response in Get a single time entry
Trash a time entry
POST /time_entries/:id/trash
Moves a given time entry to the Trash. This action requires the Account Administrator or Directory Administrator role in the account of the time entry.
Response
Status: 200 OK
{
"trashed": "true",
"coverage": "...",
"...": "..."
}
The response contains all fields of the archived time entry and is similar to the response in Get a single time entry
Restore a time entry
POST /time_entries/:id/restore
Moves a given time entry from the Archive or the Trash back into the active state. This action requires the Account Administrator or Directory Administrator role in the account of the time entry.
Response
Status: 200 OK
{
"coverage": "...",
"...": "..."
}
The response contains all fields of the archived time entry and is similar to the response in Get a single time entry
Fields
- activityID
- Readonly string — The Activity ID is the unique identifier by which an activity that is performed in the context of a service offering is known in the billing system of the service provider. Some examples of activities are standard requests, a high impact incident or a request for information. The Activity ID can be used to support integrations between the billing system of the service provider and the R-Service account in which the activities are performed.
- agreementID
- Readonly string — The Agreement ID is the unique identifier by which all the activities that are performed through the coverage of the SLA are known in the billing system of the service provider. The billing ID can be used to support integrations between the billing system of the service provider and the R-Service account in which the activities are performed.
- charge
- Readonly decimal — For a Time and Materials activity the charge is calculated by multiplying the time spent by the charge rate of the person’s who spent the time based on the selected effort class. For a Fixed Price activity the charge is the amount defined for the fixed price activity in the service offering (of the billable SLA related to the request).
- charge_currency
- Readonly reference — The currency of the charge field value of the time entry.
- charge_rate
- Readonly decimal — Shows the charging rate per hour and is defined by the effort class that was selected when the person registered the time entry.
- charge_type
- Readonly enum — The charge type field defines how the activity is charged. Valid values are:
-
fixed_price
: Fixed Pricetime_material
: Time and Material
- correction
- Optional boolean, default:
false
— The Correction box is checked when the time entry should be considered a correction for a time entry that was registered for a date that has already been locked. - cost
- Readonly decimal, — The cost field shows cost of the time entry. It is calculated by multiplying the time spent by the cost per hour of the person’s who spent the time.
- cost_currency
- Optional enum — The currency of the cost field value of the time entry. For valid values, see the list of currencies in the Currency field of the Account API.
- created_at
- Readonly datetime — The date and time at which the time entry was created.
- customer
- Required reference to Organization — The Customer field is used to select the organization for which the time was spent. It is automatically set when this time entry is linked to a request, problem, task, or project task.
- date
- Required date — The Date field is used to select the date on which the time was spent.
- deleted
- Optional boolean, default:
false
— The Deleted box is automatically checked after the time entry has been deleted. The data of a deleted time entry that is older than 3 months can no longer be retrieved. - description
- Required string (max 80) — The Description field is used to enter a short description of the time spent. This field is available and required only when the Description required box is checked in the selected time allocation.
- effort_class
- Optional reference to Effort Class — The Effort class field is used to select the effort class that best reflects the type of effort for which time spent is being registered.
- id
- Readonly integer — The unique ID of the time entry.
- note_id
- Optional integer — The unique ID of the note that the time entry is linked to.
- organization
- Optional reference to Organization — Always set to the organization to which the person was linked when the time entry was created.
- person
- Required reference to Person — The Person field is used to specify the person who spent the time.
- problem
- Optional reference to Problem — The Problem field shows the problem in which the Time spent field was filled out to cause the time entry to be generated.
- project_task
- Optional reference to Task — The Project Task field shows the project task in which the Time spent field was filled out to cause the time entry to be generated.
- rateID
- Readonly string — The Rate ID is the unique identifier by which an effort class that is linked to a time entry when an activity was performed through the coverage of the SLA is known in the billing system of the service provider. The effort class represents the type of effort that was performed when working on an activity. Some examples of effort classes are ‘Billable - Normal Hours’, ‘Billable overtime’, ‘Non Billable’ or ‘Senior System Engineer’. The Rate ID can be used to support integrations between the billing system of the service provider and the R-Service account in which the activities are performed. In the billing system the Rate IDs will be linked to the rates that have been agreed on in the service contract.
- request
- Optional reference to Request — The Request field shows the request in which the Time spent field was filled out to cause the time entry to be generated.
- service
- Required reference to Service — The Service field is used to select the service for which the time was spent. It is automatically set when this time entry is linked to a request, problem, task, or project task.
- service_instance
- Readonly reference to Service Instance — The service instance for which the time was spent. It is automatically set when this time entry is linked to a request, problem, task, or project task.
- sla
- Readonly reference to Service Level Agreement — The service level agreement for which the time was spent. It is automatically set when this time entry is linked to a request, problem, task, or project task.
- started_at
- Optional datetime — The date and time the work was started.
- task
- Optional reference to Task — The Task field shows the task in which the Time spent field was filled out to cause the time entry to be generated.
- time_allocation
- Optional reference to Time Allocation — The Time allocation field is used to select the time allocation on which the time was spent. Only the time allocations that are linked to the person’s organization can be selected.
- time_spent
- Required integer, — The Time spent field is used to specify the number of minutes that was spent on the selected time allocation. The number of minutes is allowed to be negative only when the correction field is set to
true
. - updated_at
- Readonly datetime — The date and time of the last update of the time entry. If the time entry has no updates it contains the
created_at
value.