Book workload for an employee on a task

Asks Resource Planner to book (plan) a number of hours for an employee on a task over a date range.

TimeLog itself stores nothing; there is no booking ID in the response and no REST v1 operation to read, change or delete the booking afterwards. What Resource Planner does with it — how Hours is spread over the days, whether an existing booking for the same employee / task / period is replaced or added to, whether the employee is added to the project team (a TimeLog allocation) — is decided in that service and is not established here (see gaps). Note EmployeeId is an EMPLOYEE ID, not the user ID used by the other Employees operations.

Use it to:

A staffing or PSA tool pushes planned hours for a person on a task into TimeLog Resource Planner.

Not for:

Registering actual time — use the TimeRegistration service.

Rules across fields:

R1: EndDate must be on or after StartDate.

Behaviour:

Side effect: TimeLog: none — validations are reads; the only action is the HTTP PUT to Resource Planner.
Side effect: Resource Planner: a workload booking for EmployeeId on TaskId / its project over StartDate..EndDate with Hours (semantics owned by RP, see gaps).
On failure: On a 500 caused by an RP timeout or dropped connection the booking may or may not have been stored by RP — and there is no read operation to check.
Consistency: Visibility of the booking in Resource Planner views is RP-side and not established.

Call first: GET /v1/task/{taskID}

See also: POST /v1/task/{taskID}/allocation

Not yet documented: behaviour → duplicate handling; behaviour → idempotent; behaviour → safe to retry; behaviour → side effects; examples (success).

curl -X POST "https://app3.timelog.com/your-account/api/v1/workload/book" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -d '{
  "StartDate": "2024-12-25T10:00:00Z",
  "EndDate": "2024-12-25T10:00:00Z",
  "Hours": 3.14,
  "EmployeeId": 123,
  "TaskId": 123
}'

import requests
import json

url = "https://app3.timelog.com/your-account/api/v1/workload/book"
headers = {
  "Content-Type": "application/json",
  "Authorization": "Bearer YOUR_API_TOKEN"
}
data = {
  "StartDate": "2024-12-25T10:00:00Z",
  "EndDate": "2024-12-25T10:00:00Z",
  "Hours": 3.14,
  "EmployeeId": 123,
  "TaskId": 123
}

response = requests.post(url, headers=headers, json=data)
print(response.json())

const response = await fetch("https://app3.timelog.com/your-account/api/v1/workload/book", {
  method: "POST",
  headers: {
  "Content-Type": "application/json",
  "Authorization": "Bearer YOUR_API_TOKEN"
},
  body: JSON.stringify({
  "StartDate": "2024-12-25T10:00:00Z",
  "EndDate": "2024-12-25T10:00:00Z",
  "Hours": 3.14,
  "EmployeeId": 123,
  "TaskId": 123
})
});

const data = await response.json();
console.log(data);

package main

import (
    "fmt"
    "net/http"
    "bytes"
    "encoding/json"
)

func main() {
    data := []byte(`{
  "StartDate": "2024-12-25T10:00:00Z",
  "EndDate": "2024-12-25T10:00:00Z",
  "Hours": 3.14,
  "EmployeeId": 123,
  "TaskId": 123
}`)

    req, err := http.NewRequest("POST", "https://app3.timelog.com/your-account/api/v1/workload/book", bytes.NewBuffer(data))
    if err != nil {
        panic(err)
    }

    req.Header.Set("Content-Type", "application/json")
    req.Header.Set("Authorization", "Bearer YOUR_API_TOKEN")

    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()

    fmt.Println("Response Status:", resp.Status)
}

require 'net/http'
require 'json'

uri = URI('https://app3.timelog.com/your-account/api/v1/workload/book')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Post.new(uri)
request['Content-Type'] = 'application/json'
request['Authorization'] = 'Bearer YOUR_API_TOKEN'
request.body = '{
  "StartDate": "2024-12-25T10:00:00Z",
  "EndDate": "2024-12-25T10:00:00Z",
  "Hours": 3.14,
  "EmployeeId": 123,
  "TaskId": 123
}'

response = http.request(request)
puts response.body

{}

{
  "Code": 200,
  "Details": [
    "'Employee Id' must not be empty.",
    "'Employee Id' must be greater than '0'.",
    "'Task Id' must not be empty.",
    "'Task Id' must be greater than '0'.",
    "'Hours' must not be empty.",
    "'Hours' must be greater than '0'.",
    "StartDate is not a valid date.",
    "EndDate is not a valid date."
  ],
  "Message": "Invalid model state error.",
  "Parameters": "model: {"StartDate":"0001-01-01T00:00:00","EndDate":"0001-01-01T00:00:00","Hours":0.0,"EmployeeId":0,"TaskId":0}",
  "Url": "https://app{server-number}.timelog.com/{account}/api/v1/workload/book"
}

{
  "Code": 100,
  "Details": [],
  "Message": "Unknown error occur in system, please contact system administrator.",
  "Parameters": "model: null",
  "Url": "https://app{server-number}.timelog.com/{account}/api/v1/workload/book"
}

POST

/v1/workload/book

POST

Base URLstring

Target server for requests. Edit to use your own host.

Book workload for an employee on a task

Request Preview

Response

Authentication

Body

Responses