---
title: "Add a User"
method: POST
path: "/api/users/add"
tags: ["Users"]
---

# Add a User

`POST /api/users/add`

## Request

- Base URL: `https://app.timetastic.co.uk` (the document declares no server; this is the origin it was published from)
- URL: `https://app.timetastic.co.uk/api/users/add`
- Auth: none declared

Adds a new user to Timetastic, optionally triggering a welcome email.
            
This endpoint is limited to 2 requests per second.
            
Attempts that supply an email address already in use are counted against your organisation. The
count is shared with the edit endpoint, and after 10 of them both start returning 429. The
count expires 24 hours after the *first* failure, not the last, and succeeding in the meantime
does not clear it. Check for an existing user before retrying rather than letting these
accumulate.

## Request body

- TimetasticCoreModelsApiModelsAddUserApiModel
  - `firstName` string, required: The user's first name
  - `lastName` string, required: The user's last name
  - `emailAddress` string, email, nullable: The new user's Email address
  - `leaveYearStart` integer, nullable: The month that the user's leave year starts (1: Jan, 2: Feb…12: Dec). Omitting this will create a user with the same leave year that occurs most often in your Organisation
  - `allowance` number, double, required: The user's annual allowance in days
  - `startDate` string, date-time, nullable: The user's start date. In ISO 8601 format: 2022-02-04T00:00:00
  - `departmentId` integer, required: The ID of the department that this user is in
  - `sendWelcomeEmail` boolean: Whether to send the user an email to set a password and start using Timetastic

## Response `200`

The user was created. Returns the ID of the new user, e.g. `{ "id": 1234 }`.

## Other responses

- `400`: The user could not be created. `errorStatus` says why.
- `401`: The request was not authenticated — the API token is missing or invalid.
- `403`: The authenticated user is not an administrator.
- `429`: Too many recent requests supplied an email address that was already in use. Note the reason is carried in `result` rather than `errorStatus`. Exceeding the endpoint limit of 2 requests per second also returns 429, but as a plain text message from the rate limiter rather than this body.

---

[API](https://skmtc.dev/timetastic/apis/timetastic-api.md) · [All operations](https://skmtc.dev/timetastic/apis/timetastic-api/llms.txt) · [OpenAPI document](https://skmtc.dev/timetastic/apis/timetastic-api/revisions/709ccb0412c3?raw)