Validate a new task allocation (dry run)
Checks whether an allocation with this body could be created on the task, without creating it.
Same path parameter and body as POST /v1/task/{taskID}/allocation, and the same checks up to the write: body rules, task exists (404), project access (403), period rules, task is a leaf and open, hourly rate valid (or a default resolvable), user exists and is active, no existing allocation (409). Answers 200 with null. Checks that only the save performs — Allocation.Validate, the save's own rate resolution for an omitted HourlyRateID, project save rules — are not run (the XML comment says so), so a 200 is not a full guarantee.
Use it to:
- Pre-check a staffing import row before creating allocations
Not for:
- Creating →
POST /v1/task/{taskID}/allocation
Rules across fields:
- R1: Effective period must not end before it starts (400).
- R2: At most one allocation per (user, task) (409).
Behaviour:
- Idempotent.
- Safe to retry.
- Changes are visible to the next read immediately.
Call first: GET /v1/task, GET /v1/user
Next: POST /v1/task/{taskID}/allocation
See also: GET /v1/task/{taskID}/allocation
Not yet documented: examples.
curl -X POST "https://app3.timelog.com/your-account/api/v1/task/123/allocation/validate-new-allocation" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-d '{
"UserID": 123,
"AllocatedHours": 3.14,
"HourlyRateID": "null",
"StartDate": "null",
"EndDate": "null"
}'
import requests
import json
url = "https://app3.timelog.com/your-account/api/v1/task/123/allocation/validate-new-allocation"
headers = {
"Content-Type": "application/json",
"Authorization": "Bearer YOUR_API_TOKEN"
}
data = {
"UserID": 123,
"AllocatedHours": 3.14,
"HourlyRateID": "null",
"StartDate": "null",
"EndDate": "null"
}
response = requests.post(url, headers=headers, json=data)
print(response.json())
const response = await fetch("https://app3.timelog.com/your-account/api/v1/task/123/allocation/validate-new-allocation", {
method: "POST",
headers: {
"Content-Type": "application/json",
"Authorization": "Bearer YOUR_API_TOKEN"
},
body: JSON.stringify({
"UserID": 123,
"AllocatedHours": 3.14,
"HourlyRateID": "null",
"StartDate": "null",
"EndDate": "null"
})
});
const data = await response.json();
console.log(data);
package main
import (
"fmt"
"net/http"
"bytes"
"encoding/json"
)
func main() {
data := []byte(`{
"UserID": 123,
"AllocatedHours": 3.14,
"HourlyRateID": "null",
"StartDate": "null",
"EndDate": "null"
}`)
req, err := http.NewRequest("POST", "https://app3.timelog.com/your-account/api/v1/task/123/allocation/validate-new-allocation", 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/task/123/allocation/validate-new-allocation')
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 = '{
"UserID": 123,
"AllocatedHours": 3.14,
"HourlyRateID": "null",
"StartDate": "null",
"EndDate": "null"
}'
response = http.request(request)
puts response.body
"null"
{
"error": "Bad Request",
"message": "The request contains invalid parameters or malformed data",
"code": 400,
"details": [
{
"field": "email",
"message": "Invalid email format"
}
]
}
{
"error": "Unauthorized",
"message": "Authentication required. Please provide a valid API token",
"code": 401
}
{
"error": "Forbidden",
"message": "You don't have permission to access this resource",
"code": 403
}
{
"error": "Not Found",
"message": "The requested resource was not found",
"code": 404
}
{
"error": "Conflict",
"message": "The request conflicts with the current state of the resource",
"code": 409,
"details": "Resource already exists"
}
/v1/task/{taskID}/allocation/validate-new-allocationTarget server for requests. Edit to use your own host.
OAuth 2.0 bearer token, sent as Authorization: Bearer <token>. JWT and reference tokens are both accepted. The token must carry the required scope (default tlp).
The token's sub claim is the acting user. A token WITHOUT sub (client-credentials) acts as the system service user. If the sub user cannot log in (inactive, locked, deleted), the request is rejected with 401 — it is no longer let through without a user.
> Not yet documented: how to obtain a token.
> Not yet documented: token lifetime.
Authorization: Bearer <token>. JWT and reference tokens are both accepted. The token must carry the required scope (default tlp).
The token's sub claim is the acting user. A token WITHOUT sub (client-credentials) acts as the system service user. If the sub user cannot log in (inactive, locked, deleted), the request is rejected with 401 — it is no longer let through without a user.
> Not yet documented: how to obtain a token.
> Not yet documented: token lifetime.The task to check. Route constraint :int.
The media type of the request body
The USER to allocate (a user ID, not an employee ID). Must be an existing, active user without an allocation on the task.
Refers to UserRead.UserID. Look up valid values with GET /v1/user.
Contains personal data.
- 0 or omitted — 400 Code 200 (NotEmpty).
- Unknown user — 400 'No user found with ID: {0}'.
- Deactivated user — 400 'User with ID {0} is not active'.
- The user already has an allocation on the task (any status) — 409 Code 102 '… already has an allocation on task … Update it with PUT v1/allocation/{allocationID} instead.'
Read back as AllocationRead.UserID.
Valid values come from GET /v1/user.
Hours the user is planned to work on the task. Unit: hours - Null / omitted — 400 Code 200 (NotNull). - Negative — 400 Code 200 (>= 0). 0 is accepted (an allocation that only lets the user register).
The contract hourly rate of the allocation. Omit it to let TimeLog resolve the default rate for the user.
Refers to ContractHourlyRateID.
- 0 or negative — 400 Code 200 (> 0 when present).
- > 0 and not a rate of the task's contract, or inactive — 400 with the violation message (37944 text) or 'The contract hourly rate with ID {0} is not active'.
- Omitted — Resolved on save: fixed-price task on a Calculated project → the system hourly rate; time & material / Allocated → the task's rate, else the employee's resource-group rate, else the project's standard rate, else the employee's standard rate.
- Omitted and no default can be resolved — 400 'No default hourly rate could be resolved for task with ID {0}. Supply HourlyRateID or add a rate to the contract.' — predicted by the adapter before the save, and mapped from the save's pre-write violations (HourlyRateIsNotvalidOnTask, TimeRegistrationCannotBeCreatedWithInvalidAllocationHourlyRateID) after it.
> Not yet documented: values → lookup op.
> Not yet documented: behaviour.
First day of the allocation period. Conditional. Only allowed when the account feature 'Enable start and end date on allocations' (AllocationDates) is active, and never on a recurring task. Optional then; omitted = the task's StartDate. Time zone: none — the time part is dropped (.Date) - Feature AllocationDates off — 400 Code 200 'StartDate cannot be set because the feature … is not active'. - Recurring task — 400 'StartDate and EndDate cannot be set on task with ID {0}; allocations on recurring tasks have no period'. - Omitted (only EndDate sent) — The task's StartDate; the effective span is checked (400 when EndDate is then before it). - Outside the task's dates — Accepted. With feature ChangeTaskDateBasedAllocation the task's dates follow the allocations; otherwise an 'allocation exceeds task dates' notification is sent.
Last day of the allocation period. Conditional. Same as StartDate. Omitted = the task's EndDate. Time zone: none — the time part is dropped (.Date) - Both dates sent and EndDate < StartDate — 400 Code 200 (GreaterThanOrEqualTo). - Effective span (missing date taken from the task) ends before it starts — 400 'EndDate (yyyy-MM-dd) cannot be before StartDate (yyyy-MM-dd)'.
Request Preview
Response
Response will appear here after sending the request
Authentication
Bearer token. OAuth 2.0 bearer token, sent as Authorization: Bearer <token>. JWT and reference tokens are both accepted. The token must carry the required scope (default tlp).
The token's sub claim is the acting user. A token WITHOUT sub (client-credentials) acts as the system service user. If the sub user cannot log in (inactive, locked, deleted), the request is rejected with 401 — it is no longer let through without a user.
Not yet documented: how to obtain a token.
Not yet documented: token lifetime.
Path Parameters
The task to check. Route constraint :int.
Body
The USER to allocate (a user ID, not an employee ID). Must be an existing, active user without an allocation on the task.
Refers to UserRead.UserID. Look up valid values with GET /v1/user.
Contains personal data.
-
0 or omitted — 400 Code 200 (NotEmpty).
-
Unknown user — 400 'No user found with ID: {0}'.
-
Deactivated user — 400 'User with ID {0} is not active'.
-
The user already has an allocation on the task (any status) — 409 Code 102 '… already has an allocation on task … Update it with PUT v1/allocation/{allocationID} instead.'
Read back as AllocationRead.UserID.
Valid values come from GET /v1/user.
Hours the user is planned to work on the task.
Unit: hours
-
Null / omitted — 400 Code 200 (NotNull).
-
Negative — 400 Code 200 (>= 0).
0 is accepted (an allocation that only lets the user register).
The contract hourly rate of the allocation. Omit it to let TimeLog resolve the default rate for the user.
Refers to ContractHourlyRateID.
-
0 or negative — 400 Code 200 (> 0 when present).
-
0 and not a rate of the task's contract, or inactive — 400 with the violation message (37944 text) or 'The contract hourly rate with ID {0} is not active'.
-
Omitted — Resolved on save: fixed-price task on a Calculated project → the system hourly rate; time & material / Allocated → the task's rate, else the employee's resource-group rate, else the project's standard rate, else the employee's standard rate.
-
Omitted and no default can be resolved — 400 'No default hourly rate could be resolved for task with ID {0}. Supply HourlyRateID or add a rate to the contract.' — predicted by the adapter before the save, and mapped from the save's pre-write violations (HourlyRateIsNotvalidOnTask, TimeRegistrationCannotBeCreatedWithInvalidAllocationHourlyRateID) after it.
Not yet documented: values → lookup op.
Not yet documented: behaviour.
First day of the allocation period.
Conditional. Only allowed when the account feature 'Enable start and end date on allocations' (AllocationDates) is active, and never on a recurring task. Optional then; omitted = the task's StartDate.
Time zone: none — the time part is dropped (.Date)
-
Feature AllocationDates off — 400 Code 200 'StartDate cannot be set because the feature … is not active'.
-
Recurring task — 400 'StartDate and EndDate cannot be set on task with ID {0}; allocations on recurring tasks have no period'.
-
Omitted (only EndDate sent) — The task's StartDate; the effective span is checked (400 when EndDate is then before it).
-
Outside the task's dates — Accepted. With feature ChangeTaskDateBasedAllocation the task's dates follow the allocations; otherwise an 'allocation exceeds task dates' notification is sent.
Last day of the allocation period.
Conditional. Same as StartDate. Omitted = the task's EndDate.
Time zone: none — the time part is dropped (.Date)
-
Both dates sent and EndDate < StartDate — 400 Code 200 (GreaterThanOrEqualTo).
-
Effective span (missing date taken from the task) ends before it starts — 400 'EndDate (yyyy-MM-dd) cannot be before StartDate (yyyy-MM-dd)'.
Responses
Success without content: HTTP 200 with the literal JSON body null. The literal null (TafSuccessResult).