Create a user

Creates an active user (employee) with its HR settings and returns it.

Creates the login and the employee profile in one call: name, initials, e-mail, legal entity, department, approval manager, rates, calendar, working time, salary group, licence type and extra roles. The new user is active immediately; time zone, language and front page come from account defaults. Run POST /v1/user/validate-new-user first to get every rule violation without side effects. The response is the User representation, which does not echo most of what was sent.

Use it to:

Not for:

Changing an existing user → PUT /v1/user (name, licence, roles, approval manager only)

Rules across fields:

R1: UserRoleIDs must be null or empty unless UserLicenseType is Standard (2).
R2: StandardHourlyRateID and CostPriceID must belong to LegalEntityID.
R3: Neither UserName nor Initials may be used by another user, active or inactive.

Behaviour:

Not idempotent.
Safe to retry only under a condition. A retry after a timeout fails with 20022 if the first call succeeded — check user.list for the initials before retrying.
Duplicates: UserName and Initials must be unused (application check, 20022/20024); nothing else is deduplicated.
Side effect: Inserts the user, its profile, its personal (employee-specific) role and the licence's system role or the requested roles, default page settings and predefined filter views
Side effect: Sets an initial login credential for the user
Side effect: Creates the cost-price drill-down rows and refreshes the platform licence status
Side effect: Updates the allocation-search denormalisation (a failure here is logged and ignored)
On failure: When the insert fails after the user row is written, the call returns 500 Code 100 and the partial user may remain
Changes are visible to the next read immediately.

Call first: GET /v1/legal-entity, GET /v1/department, POST /v1/user/validate-new-user

Next: GET /v1/user/{id}, PUT /v1/user

Not yet documented: behaviour → events emitted; behaviour → side effects; examples.

curl -X POST "https://app3.timelog.com/your-account/api/v1/user/create" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -d '{
  "UserName": "John Doe",
  "FirstName": "John Doe",
  "LastName": "John Doe",
  "Initials": "example_string",
  "Email": "user@example.com",
  "Title": "example_string",
  "EmployeeNo": "example_string",
  "EmploymentDate": "2024-12-25T10:00:00Z",
  "LegalEntityID": 123,
  "DepartmentID": 123,
  "ApprovalManagerID": 123,
  "EmployeeTypeID": 123,
  "StandardHourlyRateID": 123,
  "CostPriceID": 123,
  "PublicHolidayCalendarID": 123,
  "AllowanceLegislationID": 123,
  "NormalWorkingTimeID": 123,
  "SalaryGroupID": 123,
  "UserLicenseType": 42,
  "UserRoleIDs": [
    "null"
  ]
}'

import requests
import json

url = "https://app3.timelog.com/your-account/api/v1/user/create"
headers = {
  "Content-Type": "application/json",
  "Authorization": "Bearer YOUR_API_TOKEN"
}
data = {
  "UserName": "John Doe",
  "FirstName": "John Doe",
  "LastName": "John Doe",
  "Initials": "example_string",
  "Email": "user@example.com",
  "Title": "example_string",
  "EmployeeNo": "example_string",
  "EmploymentDate": "2024-12-25T10:00:00Z",
  "LegalEntityID": 123,
  "DepartmentID": 123,
  "ApprovalManagerID": 123,
  "EmployeeTypeID": 123,
  "StandardHourlyRateID": 123,
  "CostPriceID": 123,
  "PublicHolidayCalendarID": 123,
  "AllowanceLegislationID": 123,
  "NormalWorkingTimeID": 123,
  "SalaryGroupID": 123,
  "UserLicenseType": 42,
  "UserRoleIDs": [
    "null"
  ]
}

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

const response = await fetch("https://app3.timelog.com/your-account/api/v1/user/create", {
  method: "POST",
  headers: {
  "Content-Type": "application/json",
  "Authorization": "Bearer YOUR_API_TOKEN"
},
  body: JSON.stringify({
  "UserName": "John Doe",
  "FirstName": "John Doe",
  "LastName": "John Doe",
  "Initials": "example_string",
  "Email": "user@example.com",
  "Title": "example_string",
  "EmployeeNo": "example_string",
  "EmploymentDate": "2024-12-25T10:00:00Z",
  "LegalEntityID": 123,
  "DepartmentID": 123,
  "ApprovalManagerID": 123,
  "EmployeeTypeID": 123,
  "StandardHourlyRateID": 123,
  "CostPriceID": 123,
  "PublicHolidayCalendarID": 123,
  "AllowanceLegislationID": 123,
  "NormalWorkingTimeID": 123,
  "SalaryGroupID": 123,
  "UserLicenseType": 42,
  "UserRoleIDs": [
    "null"
  ]
})
});

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

package main

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

func main() {
    data := []byte(`{
  "UserName": "John Doe",
  "FirstName": "John Doe",
  "LastName": "John Doe",
  "Initials": "example_string",
  "Email": "user@example.com",
  "Title": "example_string",
  "EmployeeNo": "example_string",
  "EmploymentDate": "2024-12-25T10:00:00Z",
  "LegalEntityID": 123,
  "DepartmentID": 123,
  "ApprovalManagerID": 123,
  "EmployeeTypeID": 123,
  "StandardHourlyRateID": 123,
  "CostPriceID": 123,
  "PublicHolidayCalendarID": 123,
  "AllowanceLegislationID": 123,
  "NormalWorkingTimeID": 123,
  "SalaryGroupID": 123,
  "UserLicenseType": 42,
  "UserRoleIDs": [
    "null"
  ]
}`)

    req, err := http.NewRequest("POST", "https://app3.timelog.com/your-account/api/v1/user/create", 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/user/create')
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 = '{
  "UserName": "John Doe",
  "FirstName": "John Doe",
  "LastName": "John Doe",
  "Initials": "example_string",
  "Email": "user@example.com",
  "Title": "example_string",
  "EmployeeNo": "example_string",
  "EmploymentDate": "2024-12-25T10:00:00Z",
  "LegalEntityID": 123,
  "DepartmentID": 123,
  "ApprovalManagerID": 123,
  "EmployeeTypeID": 123,
  "StandardHourlyRateID": 123,
  "CostPriceID": 123,
  "PublicHolidayCalendarID": 123,
  "AllowanceLegislationID": 123,
  "NormalWorkingTimeID": 123,
  "SalaryGroupID": 123,
  "UserLicenseType": 42,
  "UserRoleIDs": [
    "null"
  ]
}'

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

{
  "Properties": {
    "UserID": 123,
    "ID": "123e4567-e89b-12d3-a456-426614174000",
    "FirstName": "John Doe",
    "LastName": "John Doe",
    "Initials": "example_string",
    "IsActive": true,
    "UserType": "Employee",
    "LegalEntityID": 123,
    "Email": "user@example.com"
  },
  "Links": [
    {
      "Href": "example_string",
      "Rel": "example_string"
    }
  ],
  "Actions": [
    {}
  ]
}

{
  "error": "Bad Request",
  "message": "The request contains invalid parameters or malformed data",
  "code": 400,
  "details": [
    {
      "field": "email",
      "message": "Invalid email format"
    }
  ]
}

POST

/v1/user/create

POST

Base URLstring

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

Value	Name	Meaning
`2`	Standard	Standard user: access to most functionality, depending on the account's licence model. The only value accepted when neither ExternalUserLicense nor TimeExpenseUserLicense is on.
`7`	Limited	Limited user. Accepted only when feature ExternalUserLicense is on; the system role 'Limited user' is assigned and UserRoleIDs must be empty.
`8`	TimeExpense	Time and expense tracking with reports. Accepted only when feature TimeExpenseUserLicense is on; the system role 'Time and expense registrations' is assigned and UserRoleIDs must be empty.
`1`	External	External user (time tracking only). Rejected by this operation.
`3`	Advanced	Advanced user of special licence models. Rejected by this operation.
`4`	ExternalPlus	External user with external disbursement. Rejected by this operation.
`6`	TlpBasicLimited	Limited user of the Basic contract. Rejected by this operation.
`0`	NotSpecified	No licence (no access). Rejected by this operation.

Create a user

Request Preview

Response

Authentication

Body

Responses