{
"openapi": "3.0.4",
"info": {
"title": "Timetastic API",
"description": "# Introduction\r\n\r\nπ Welcome to the Timetastic API π\r\n\r\nYou can use the Timetastic API to integrate Timetastic into other software applications and custom workflows.\r\n\r\nThe API is designed to be a predictable and intuitive way to interact with your companyβs Timetastic account.\r\n\r\nLike Timetastic itself, the API is under continuous development, so changes and improvements are to be expected. Be sure to keep an eye on our [Twitter Changelog](https://twitter.com/search?f=tweets&vertical=default&q=timetastic%20%23changelog&src=typd) to receive information on new additions and changes to both Timetastic and the API when we release new features and changes.\r\n\r\n**Get started quickly:**\r\n\r\nThere's an OpenAPI specification at the top of this document so you can get set up and testing early and easily. You can import this collection into [Postman](https://www.postman.com/), [Insomnia](https://insomnia.rest/), [Paw](https://paw.cloud/) or your HTTP/Rest client of choice.\r\n\r\n**Get stuck in:** Read the sections below on Authentication and Rate Limiting, then see what you can do!\r\n\r\n# Rate Limiting\r\n\r\nTo keep things running smoothly, there is a rate limit of 5 requests per second, per API key.\r\n\r\nIf you exceed the limit, you'll get a `429` response code.\r\n\r\nFor successful calls, we set response headers containing information about the rate limitβwhich can help you monitor your usage.\r\n\r\n**Monitoring Usage**\r\n\r\nFor calls that don't get rate limited, you can monitor your usage with the following headers:\r\n\r\n- `X-Rate-Limit-Limit`: The rate limit period (e.g., 1s, 1m)\r\n- `X-Rate-Limit-Remaining`: Number of requests remaining\r\n- `X-Rate-Limit-Reset`: UTC date time (ISO 8601) when the limit resets\r\n\r\n# Authentication\r\n\r\nTo use the API, you need an API token. Only admin users have access to an API token.\r\n\r\nYou can get or renew your API token from Timetastic: [https://app.timetastic.co.uk/api](https://app.timetastic.co.uk/api)\r\n\r\n_The token identifies your user, so you'll have the same permissions as your user account._\r\n\r\n## Example\r\n\r\nTo authorize, use this code:\r\n\r\n```bash\r\ncurl \"https://app.timetastic.co.uk/api/users\" -H \"Authorization: Bearer YOUR_TOKEN\"\r\n```\r\n\r\nReplace `YOUR_TOKEN` with your API key.\r\n\r\n\r\n## Big integrations / building us into your product?\r\nGreat! We're happy to have you. We'd love it if you could do us a huge favour and include either the\r\n`User-Agent` header (for example, `User-Agent: YourApp/1.0`) or an `X-Client-ID` header (for example,\r\n`X-Client-ID: YourApp`) telling us the product/app name so we can see who and how people are using the API.\r\nIt's just for metrics and seeing how popular/well used the API is. Thanks! β€οΈ (Also we have a referral programme so you might want to check that out too: https://timetastic.co.uk/rewards/)",
"version": "v1",
"x-logo": {
"url": "/images/logo-api.svg",
"altText": "Timetastic API"
}
},
"paths": {
"/api/absences": {
"get": {
"tags": [
"Absences"
],
"summary": "Get a chronological list of absences",
"description": "Find out \"who is off\" on a certain day or range of days - whether thats public holidays, bookings, non working days or other events.\r\n Bookings are returned with times matching the user's work schedule so a multiple day booking will show start and end times for that day even if the booking covers multiple days\r\n Limited to 31 days per query. Rate limited to 1 request per second.",
"parameters": [
{
"name": "Start",
"in": "query",
"schema": {
"type": "string",
"format": "date"
}
},
{
"name": "End",
"in": "query",
"schema": {
"type": "string",
"format": "date"
}
},
{
"name": "AbsenceQueryType",
"in": "query",
"description": "\r\n \r\n\r\n AllEvents: Returns Bookings, Non working days, Public Holidays, Locked Dates, Birthdays and Work anniversaries.\r\n \r\nAllAbsences: Returns everything we consider an absence: Bookings, Public Holidays and Non working days\r\n \r\nBookings: Returns Bookings only\r\n \r\nPublicHolidays: returns Public Holidays only\r\n \r\n\r\n\r\n- `0` β **AllEvents**: Locked dates, birthdays, work anniversaries, absences, non working days, public holidays, everything on the wallchart basically\n- `1` β **AllAbsences**: Just absences - non-working days, public holidays, bookings\n- `2` β **Bookings**: Just bookings\n- `3` β **PublicHolidays**: Just public holidays",
"schema": {
"enum": [
0,
1,
2,
3
],
"type": "integer",
"description": "\r\n \r\n\r\n AllEvents: Returns Bookings, Non working days, Public Holidays, Locked Dates, Birthdays and Work anniversaries.\r\n \r\nAllAbsences: Returns everything we consider an absence: Bookings, Public Holidays and Non working days\r\n \r\nBookings: Returns Bookings only\r\n \r\nPublicHolidays: returns Public Holidays only\r\n \r\n\r\n\r\n- `0` β **AllEvents**: Locked dates, birthdays, work anniversaries, absences, non working days, public holidays, everything on the wallchart basically\n- `1` β **AllAbsences**: Just absences - non-working days, public holidays, bookings\n- `2` β **Bookings**: Just bookings\n- `3` β **PublicHolidays**: Just public holidays",
"format": "int32"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Timetastic.Core.Commands.AbsenceDay"
}
}
},
"text/plain": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Timetastic.Core.Commands.AbsenceDay"
}
}
},
"text/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Timetastic.Core.Commands.AbsenceDay"
}
}
}
}
},
"400": {
"description": "If the start and end dates are invalid. Check the end is after the start date and that they don't cover more than 31 days",
"content": {
"application/json": {
"schema": {
"type": "string"
}
},
"text/plain": {
"schema": {
"type": "string"
}
},
"text/json": {
"schema": {
"type": "string"
}
}
}
}
}
}
},
"/api/users/allowances": {
"get": {
"tags": [
"Allowances"
],
"summary": "List all user allowances for all years",
"description": "Get a list of allowances, TOIL and carry forwards for all users for all years.",
"responses": {
"200": {
"description": "The allowances were successfully retrieved",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Timetastic.Core.Models.ApiModels.UsersAllowancesResponse"
}
}
},
"text/plain": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Timetastic.Core.Models.ApiModels.UsersAllowancesResponse"
}
}
},
"text/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Timetastic.Core.Models.ApiModels.UsersAllowancesResponse"
}
}
}
}
},
"400": {
"description": "Validation error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Timetastic.Web.ApiResourceModels.AllowanceError"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/Timetastic.Web.ApiResourceModels.AllowanceError"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/Timetastic.Web.ApiResourceModels.AllowanceError"
}
}
}
},
"404": {
"description": "The requested resource cannot be found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails"
}
}
}
}
}
}
},
"/api/users/allowances/{year}": {
"get": {
"tags": [
"Allowances"
],
"summary": "List all user allowances for a single year",
"description": "Get a list of allowances, TOIL and carry forwards for all users for a year.",
"parameters": [
{
"name": "year",
"in": "path",
"description": "The year to query",
"required": true,
"schema": {
"type": "integer",
"format": "int32"
}
}
],
"responses": {
"200": {
"description": "The allowances were successfully retrieved",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Timetastic.Core.Models.ApiModels.UsersAllowancesResponse"
}
}
},
"text/plain": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Timetastic.Core.Models.ApiModels.UsersAllowancesResponse"
}
}
},
"text/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Timetastic.Core.Models.ApiModels.UsersAllowancesResponse"
}
}
}
}
},
"400": {
"description": "Validation error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Timetastic.Web.ApiResourceModels.AllowanceError"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/Timetastic.Web.ApiResourceModels.AllowanceError"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/Timetastic.Web.ApiResourceModels.AllowanceError"
}
}
}
},
"404": {
"description": "The requested resource cannot be found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails"
}
}
}
}
}
}
},
"/api/users/{userId}/allowances": {
"get": {
"tags": [
"Allowances"
],
"summary": "Get all allowances for a user",
"description": "Get the allowance, TOIL and carry forwards for a user for all years.",
"parameters": [
{
"name": "userId",
"in": "path",
"description": "The id of the user to query",
"required": true,
"schema": {
"type": "integer",
"format": "int32"
}
}
],
"responses": {
"200": {
"description": "The allowances were successfully retrieved",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Timetastic.Core.Models.ApiModels.UserAllowanceResponse"
}
}
},
"text/plain": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Timetastic.Core.Models.ApiModels.UserAllowanceResponse"
}
}
},
"text/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Timetastic.Core.Models.ApiModels.UserAllowanceResponse"
}
}
}
}
},
"400": {
"description": "Validation error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Timetastic.Web.ApiResourceModels.AllowanceError"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/Timetastic.Web.ApiResourceModels.AllowanceError"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/Timetastic.Web.ApiResourceModels.AllowanceError"
}
}
}
},
"403": {
"description": "You don't have permission to view this user's allowances",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails"
}
}
}
},
"404": {
"description": "The requested resource cannot be found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails"
}
}
}
}
}
}
},
"/api/users/{userId}/allowances/{year}": {
"get": {
"tags": [
"Allowances"
],
"summary": "Get allowance for a user for a year",
"description": "Get the allowance, TOIL and carry forwards for a user for a year.",
"parameters": [
{
"name": "userId",
"in": "path",
"description": "The id of the user to query",
"required": true,
"schema": {
"type": "integer",
"format": "int32"
}
},
{
"name": "year",
"in": "path",
"description": "The year to query",
"required": true,
"schema": {
"type": "integer",
"format": "int32"
}
}
],
"responses": {
"200": {
"description": "The allowances were successfully retrieved",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Timetastic.Core.Models.ApiModels.UserAllowanceResponse"
}
}
},
"text/plain": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Timetastic.Core.Models.ApiModels.UserAllowanceResponse"
}
}
},
"text/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Timetastic.Core.Models.ApiModels.UserAllowanceResponse"
}
}
}
}
},
"400": {
"description": "Validation error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Timetastic.Web.ApiResourceModels.AllowanceError"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/Timetastic.Web.ApiResourceModels.AllowanceError"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/Timetastic.Web.ApiResourceModels.AllowanceError"
}
}
}
},
"403": {
"description": "You don't have permission to view this user's allowances",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails"
}
}
}
},
"404": {
"description": "The requested resource cannot be found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails"
}
}
}
}
}
}
},
"/api/users/{userId}/allowances/{year}/allowance": {
"put": {
"tags": [
"Allowances"
],
"summary": "Update Allowance",
"description": "Update a users allowance for a year",
"parameters": [
{
"name": "userId",
"in": "path",
"description": "The id of the user to update",
"required": true,
"schema": {
"type": "integer",
"format": "int32"
}
},
{
"name": "year",
"in": "path",
"description": "The year to update the allowance for",
"required": true,
"schema": {
"type": "integer",
"format": "int32"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Timetastic.Web.Controllers.API.UserAllowanceController+AmountRequest"
}
},
"application/json-patch+json": {
"schema": {
"$ref": "#/components/schemas/Timetastic.Web.Controllers.API.UserAllowanceController+AmountRequest"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/Timetastic.Web.Controllers.API.UserAllowanceController+AmountRequest"
}
},
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/Timetastic.Web.Controllers.API.UserAllowanceController+AmountRequest"
}
}
}
},
"responses": {
"200": {
"description": "The allowance was successfully created/updated"
},
"400": {
"description": "Invalid input data or validation error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Timetastic.Web.ApiResourceModels.AllowanceError"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/Timetastic.Web.ApiResourceModels.AllowanceError"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/Timetastic.Web.ApiResourceModels.AllowanceError"
}
}
}
},
"403": {
"description": "You don't have permission to manage this allowance",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails"
}
}
}
},
"404": {
"description": "The requested resource cannot be found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails"
}
}
}
}
}
}
},
"/api/users/{userId}/allowances/{year}/toil": {
"post": {
"tags": [
"Allowances"
],
"summary": "Add TOIL",
"description": "Add a TOIL for a user for a year",
"parameters": [
{
"name": "userId",
"in": "path",
"description": "The id of the user to add the TOIL for",
"required": true,
"schema": {
"type": "integer",
"format": "int32"
}
},
{
"name": "year",
"in": "path",
"description": "The year to add/update the TOIL for",
"required": true,
"schema": {
"type": "integer",
"format": "int32"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Timetastic.Web.Controllers.API.UserAllowanceController+UpsertToilRequest"
}
},
"application/json-patch+json": {
"schema": {
"$ref": "#/components/schemas/Timetastic.Web.Controllers.API.UserAllowanceController+UpsertToilRequest"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/Timetastic.Web.Controllers.API.UserAllowanceController+UpsertToilRequest"
}
},
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/Timetastic.Web.Controllers.API.UserAllowanceController+UpsertToilRequest"
}
}
}
},
"responses": {
"200": {
"description": "The TOIL was successfully created",
"content": {
"application/json": {
"schema": {
"type": "integer",
"format": "int32"
}
},
"text/plain": {
"schema": {
"type": "integer",
"format": "int32"
}
},
"text/json": {
"schema": {
"type": "integer",
"format": "int32"
}
}
}
},
"400": {
"description": "Invalid input data or validation error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Timetastic.Web.ApiResourceModels.AllowanceError"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/Timetastic.Web.ApiResourceModels.AllowanceError"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/Timetastic.Web.ApiResourceModels.AllowanceError"
}
}
}
},
"403": {
"description": "You don't have permission to manage this TOIL",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails"
}
}
}
},
"404": {
"description": "The requested resource cannot be found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails"
}
}
}
}
}
}
},
"/api/users/{userId}/allowances/{year}/toil/{id}": {
"put": {
"tags": [
"Allowances"
],
"summary": "Update TOIL",
"description": "Update a TOIL for a user for a year",
"parameters": [
{
"name": "userId",
"in": "path",
"description": "The id of the user to update",
"required": true,
"schema": {
"type": "integer",
"format": "int32"
}
},
{
"name": "year",
"in": "path",
"description": "The year to add/update the TOIL for",
"required": true,
"schema": {
"type": "integer",
"format": "int32"
}
},
{
"name": "id",
"in": "path",
"description": "The id of the TOIL to update",
"required": true,
"schema": {
"type": "integer",
"format": "int32"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Timetastic.Web.Controllers.API.UserAllowanceController+UpsertToilRequest"
}
},
"application/json-patch+json": {
"schema": {
"$ref": "#/components/schemas/Timetastic.Web.Controllers.API.UserAllowanceController+UpsertToilRequest"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/Timetastic.Web.Controllers.API.UserAllowanceController+UpsertToilRequest"
}
},
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/Timetastic.Web.Controllers.API.UserAllowanceController+UpsertToilRequest"
}
}
}
},
"responses": {
"200": {
"description": "The TOIL was successfully updated",
"content": {
"application/json": {
"schema": {
"type": "integer",
"format": "int32"
}
},
"text/plain": {
"schema": {
"type": "integer",
"format": "int32"
}
},
"text/json": {
"schema": {
"type": "integer",
"format": "int32"
}
}
}
},
"400": {
"description": "Invalid input data or validation error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Timetastic.Web.ApiResourceModels.AllowanceError"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/Timetastic.Web.ApiResourceModels.AllowanceError"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/Timetastic.Web.ApiResourceModels.AllowanceError"
}
}
}
},
"403": {
"description": "You don't have permission to manage this TOIL",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails"
}
}
}
},
"404": {
"description": "The requested resource cannot be found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails"
}
}
}
}
}
},
"delete": {
"tags": [
"Allowances"
],
"summary": "Delete a users TOIL",
"description": "Deletes a users TOIL entry",
"parameters": [
{
"name": "userId",
"in": "path",
"description": "The id of the user to update",
"required": true,
"schema": {
"type": "integer",
"format": "int32"
}
},
{
"name": "year",
"in": "path",
"description": "The year the TOIL is in",
"required": true,
"schema": {
"type": "integer",
"format": "int32"
}
},
{
"name": "id",
"in": "path",
"description": "The id of the TOIL",
"required": true,
"schema": {
"type": "integer",
"format": "int32"
}
}
],
"responses": {
"200": {
"description": "The TOIL was successfully deleted"
},
"400": {
"description": "Invalid input data or validation error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Timetastic.Web.ApiResourceModels.AllowanceError"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/Timetastic.Web.ApiResourceModels.AllowanceError"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/Timetastic.Web.ApiResourceModels.AllowanceError"
}
}
}
},
"403": {
"description": "You don't have permission to manage this TOIL",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails"
}
}
}
},
"404": {
"description": "The requested resource cannot be found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails"
}
}
}
}
}
}
},
"/api/users/{userId}/allowances/{year}/carryforward": {
"put": {
"tags": [
"Allowances"
],
"summary": "Update carry forward",
"description": "Update a users carry forward for a year",
"parameters": [
{
"name": "userId",
"in": "path",
"description": "The id of the user to update",
"required": true,
"schema": {
"type": "integer",
"format": "int32"
}
},
{
"name": "year",
"in": "path",
"description": "The year to update the carry forward for",
"required": true,
"schema": {
"type": "integer",
"format": "int32"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Timetastic.Web.Controllers.API.UserAllowanceController+CarryForwardRequest"
}
},
"application/json-patch+json": {
"schema": {
"$ref": "#/components/schemas/Timetastic.Web.Controllers.API.UserAllowanceController+CarryForwardRequest"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/Timetastic.Web.Controllers.API.UserAllowanceController+CarryForwardRequest"
}
},
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/Timetastic.Web.Controllers.API.UserAllowanceController+CarryForwardRequest"
}
}
}
},
"responses": {
"200": {
"description": "The carry forward was successfully created/updated"
},
"400": {
"description": "Invalid input data or validation error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Timetastic.Web.ApiResourceModels.AllowanceError"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/Timetastic.Web.ApiResourceModels.AllowanceError"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/Timetastic.Web.ApiResourceModels.AllowanceError"
}
}
}
},
"403": {
"description": "You don't have permission to manage this carry forward",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails"
}
}
}
},
"404": {
"description": "The requested resource cannot be found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails"
}
}
}
}
}
}
},
"/api/departments": {
"get": {
"tags": [
"Departments"
],
"summary": "List all Departments",
"description": "Get a collection of departments for your organisation.",
"responses": {
"200": {
"description": "The departments for your organisation.",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Timetastic.Web.ApiResourceModels.Department"
}
}
},
"text/plain": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Timetastic.Web.ApiResourceModels.Department"
}
}
},
"text/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Timetastic.Web.ApiResourceModels.Department"
}
}
}
}
},
"401": {
"description": "The request was not authenticated β the API token is missing or invalid."
}
}
}
},
"/api/departments/{id}": {
"get": {
"tags": [
"Departments"
],
"summary": "Get a specific Department",
"description": "Gets a department using the ID passed.",
"parameters": [
{
"name": "id",
"in": "path",
"description": "The ID of the department.",
"required": true,
"schema": {
"type": "integer",
"format": "int32"
}
}
],
"responses": {
"200": {
"description": "The department.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Timetastic.Web.ApiResourceModels.Department"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/Timetastic.Web.ApiResourceModels.Department"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/Timetastic.Web.ApiResourceModels.Department"
}
}
}
},
"401": {
"description": "The request was not authenticated β the API token is missing or invalid."
},
"403": {
"description": "The department belongs to another organisation."
},
"404": {
"description": "No department exists with that ID."
}
}
}
},
"/api/departments/add": {
"post": {
"tags": [
"Departments"
],
"summary": "Add Department",
"description": "Adds a new department using the settings provided in the model.\r\n \r\nA rejection returns an `ErrorStatus` and an `ErrorMessage`. `NotPermitted` means the `managerId` is not a\r\nuser in your organisation, or has no email address. `InvalidValue` and `Failed` mean the department itself\r\nwas rejected β check `ErrorMessage`.\r\n \r\nModel validation fails before any of that, and returns a different 400 body: an object keyed by\r\nfield name, each holding an array of messages. Check for `ErrorStatus` to tell the two apart.",
"requestBody": {
"description": "The department settings model.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Timetastic.Web.ViewModels.Settings.DepartmentSetting"
}
},
"application/json-patch+json": {
"schema": {
"$ref": "#/components/schemas/Timetastic.Web.ViewModels.Settings.DepartmentSetting"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/Timetastic.Web.ViewModels.Settings.DepartmentSetting"
}
},
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/Timetastic.Web.ViewModels.Settings.DepartmentSetting"
}
}
}
},
"responses": {
"200": {
"description": "The department was created. Returns its ID.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Timetastic.Web.ApiResourceModels.DepartmentResponse"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/Timetastic.Web.ApiResourceModels.DepartmentResponse"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/Timetastic.Web.ApiResourceModels.DepartmentResponse"
}
}
}
},
"400": {
"description": "The department could not be created.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Timetastic.Web.ApiResourceModels.DepartmentError"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/Timetastic.Web.ApiResourceModels.DepartmentError"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/Timetastic.Web.ApiResourceModels.DepartmentError"
}
}
}
},
"401": {
"description": "The request was not authenticated β the API token is missing or invalid."
}
}
}
},
"/api/departments/delete/{id}": {
"post": {
"tags": [
"Departments"
],
"summary": "Delete department",
"description": "Delete a department from Timetastic. The department must be empty - edit any users with this department ID to allow the department to be deleted.",
"parameters": [
{
"name": "id",
"in": "path",
"description": "The Department ID.",
"required": true,
"schema": {
"type": "integer",
"format": "int32"
}
}
],
"responses": {
"200": {
"description": "If the department was successfully deleted"
},
"400": {
"description": "If the department couldn't be deleted (usually because it contains users)",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Timetastic.Web.ApiResourceModels.DepartmentError"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/Timetastic.Web.ApiResourceModels.DepartmentError"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/Timetastic.Web.ApiResourceModels.DepartmentError"
}
}
}
}
}
}
},
"/api/departments/edit/{id}": {
"post": {
"tags": [
"Departments"
],
"summary": "Edit Department",
"description": "As with the user edit endpoint - pass only the fields you want to update and we'll only update those.\r\n \r\nA rejection returns an `ErrorStatus` and an `ErrorMessage`. `NotPermitted` means the department does not\r\nexist or belongs to another organisation, or you are not allowed to edit it. `NothingToDo` means the\r\nrequest produced no change. `InvalidValue` and `Failed` mean a supplied value was rejected β check\r\n`ErrorMessage`.\r\n \r\nModel validation fails before any of that, and returns a different 400 body: an object keyed by\r\nfield name, each holding an array of messages. Check for `ErrorStatus` to tell the two apart.",
"parameters": [
{
"name": "id",
"in": "path",
"description": "The ID of the department to update.",
"required": true,
"schema": {
"type": "integer",
"format": "int32"
}
}
],
"requestBody": {
"description": "The department update model.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Timetastic.Core.Models.ApiModels.UpdateDepartmentApiModel"
}
},
"application/json-patch+json": {
"schema": {
"$ref": "#/components/schemas/Timetastic.Core.Models.ApiModels.UpdateDepartmentApiModel"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/Timetastic.Core.Models.ApiModels.UpdateDepartmentApiModel"
}
},
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/Timetastic.Core.Models.ApiModels.UpdateDepartmentApiModel"
}
}
}
},
"responses": {
"200": {
"description": "The department was updated."
},
"400": {
"description": "The department could not be updated.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Timetastic.Web.ApiResourceModels.DepartmentError"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/Timetastic.Web.ApiResourceModels.DepartmentError"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/Timetastic.Web.ApiResourceModels.DepartmentError"
}
}
}
},
"401": {
"description": "The request was not authenticated β the API token is missing or invalid."
}
}
}
},
"/api/holidays/{id}": {
"get": {
"tags": [
"Holidays"
],
"summary": "Get a specific Holiday",
"description": "Gets a holiday using the ID passed.",
"parameters": [
{
"name": "id",
"in": "path",
"description": "The ID of the holiday.",
"required": true,
"schema": {
"type": "integer",
"format": "int32"
}
},
{
"name": "filter",
"in": "query",
"schema": {
"type": "string",
"default": ""
}
}
],
"responses": {
"200": {
"description": "The holiday.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Timetastic.Core.Models.ApiModels.HolidayApiModel"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/Timetastic.Core.Models.ApiModels.HolidayApiModel"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/Timetastic.Core.Models.ApiModels.HolidayApiModel"
}
}
}
},
"401": {
"description": "The request was not authenticated β the API token is missing or invalid."
},
"403": {
"description": "You are not allowed to view the holidays of the user this booking belongs to."
},
"404": {
"description": "No holiday exists with that ID."
}
}
},
"post": {
"tags": [
"Holidays"
],
"summary": "Action a Holiday",
"description": "Update a holiday. You can use this to :\r\n1) Approve a pending holiday\r\n2) Decline a pending holiday\r\n3) Cancel a holiday\r\n\r\nNote: This will raise a Webhook event if you have Webhooks configured.\r\n \r\nImportant: an action that is refused still returns 200. Check\r\n`approvalResult` in the response body rather than relying on the status code. Its values are:\r\n \r\n- `Success` β the action was applied.\r\n- `AlreadyActioned` β the holiday has already been approved, declined or cancelled.\r\n- `DoesntExist` β the holiday could not be found when the action was applied.\r\n- `NotAllowed` β you are not allowed to perform that action on this holiday.\r\n- `UnknownError` β the action failed, or no recognised `holidayUpdateAction` was supplied.\r\n \r\n`message` carries a human readable version of the same thing.",
"parameters": [
{
"name": "id",
"in": "path",
"description": "The id of the holiday / a holiday token",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "holidayUpdateAction",
"in": "query",
"description": "The action you want to perform to the holiday",
"schema": {
"enum": [
"Approve",
"Decline",
"Delete",
"DeleteGroup"
],
"type": "string",
"description": "- `Approve`\n- `Decline`\n- `Delete`\n- `DeleteGroup`"
}
}
],
"requestBody": {
"description": "options for reasons and suppressing notifications",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Timetastic.Core.Models.ApiModels.ActionHolidayModel"
}
},
"application/json-patch+json": {
"schema": {
"$ref": "#/components/schemas/Timetastic.Core.Models.ApiModels.ActionHolidayModel"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/Timetastic.Core.Models.ApiModels.ActionHolidayModel"
}
},
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/Timetastic.Core.Models.ApiModels.ActionHolidayModel"
}
}
}
},
"responses": {
"200": {
"description": "The request was processed. Check `approvalResult` in the body β this is also returned when the action was refused.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Timetastic.Web.ApiResourceModels.HolidayActionResult"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/Timetastic.Web.ApiResourceModels.HolidayActionResult"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/Timetastic.Web.ApiResourceModels.HolidayActionResult"
}
}
}
},
"400": {
"description": "The body is a plain string. `\"Holiday not found\"` when no holiday matches the ID or token, and\r\n`\"You don't have permission\"` when you cannot manage that user. You may cancel your own holiday without\r\nmanaging rights, but only while it is still in the future.",
"content": {
"application/json": {
"schema": {
"type": "string"
}
},
"text/plain": {
"schema": {
"type": "string"
}
},
"text/json": {
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "The request was not authenticated β the API token is missing or invalid."
},
"429": {
"description": "The overall API rate limit was exceeded."
}
}
}
},
"/api/holidays": {
"get": {
"tags": [
"Holidays"
],
"summary": "Get a List of Holidays.",
"description": "Query the holidays for your organisation.\r\nThere are many ways to filter the results, all of which are optional.\r\nResults are limited to 100 per request.\r\n \r\nResults are scoped to your organisation, so a filter that matches nothing β including an id\r\nbelonging to another organisation β returns an empty list rather than an error. Note the scope is\r\nyour organisation rather than your own visibility, so this can return absences for people you would\r\nnot see on a wallchart.",
"parameters": [
{
"name": "DepartmentId",
"in": "query",
"description": "Filter holidays by a department",
"schema": {
"type": "integer",
"format": "int32"
}
},
{
"name": "LeaveTypeId",
"in": "query",
"description": "Filter holidays by a leave type",
"schema": {
"type": "integer",
"format": "int32"
}
},
{
"name": "DepartmentManagersOnly",
"in": "query",
"description": "Filter holidays for those for department managers only",
"schema": {
"type": "boolean"
}
},
{
"name": "MyTeamOnly",
"in": "query",
"description": "Filter holidays for those for my team only, based on the user ID you set here.",
"schema": {
"type": "integer",
"format": "int32"
}
},
{
"name": "MyFavouritesOnly",
"in": "query",
"description": "Filter holidays for those for my favourite users only, based on the User Id you set here.",
"schema": {
"type": "integer",
"format": "int32"
}
},
{
"name": "UserIds",
"in": "query",
"description": "Filter holidays to include only these user(s)",
"schema": {
"type": "string"
}
},
{
"name": "ExclusionUserIds",
"in": "query",
"description": "Filter holidays to exclude these user(s)",
"schema": {
"type": "string"
}
},
{
"name": "NonArchivedUsersOnly",
"in": "query",
"description": "Only return holidays for users that haven't been archived",
"schema": {
"type": "boolean"
}
},
{
"name": "Start",
"in": "query",
"description": "Filter all holidays on or after this date",
"schema": {
"type": "string",
"format": "date-time"
}
},
{
"name": "TransactionYear",
"in": "query",
"description": "Filter all holidays in this transaction year. Don't use this if you're not including the transactions in your query.",
"schema": {
"type": "integer",
"format": "int32"
}
},
{
"name": "End",
"in": "query",
"description": "Filter all holidays before and including this date",
"schema": {
"type": "string",
"format": "date-time"
}
},
{
"name": "Status",
"in": "query",
"description": "Filter all holidays for the given status. If none given then all pending and approved holidays are included.\r\nValues are: \r\nPending = 1, Approved = 2, Cancelled = 4, Declined = 8\r\nThis is a bitwise enum, so for example if you want all declined and cancelled you can pass 12 as the status.",
"schema": {
"enum": [
"PendingOrApproved",
"Pending",
"Approved",
"Cancelled",
"Declined",
"Any"
],
"type": "string"
}
},
{
"name": "ApproverId",
"in": "query",
"description": "Filter holidays by the approver",
"schema": {
"type": "integer",
"format": "int32"
}
},
{
"name": "PageNumber",
"in": "query",
"description": "Current page number, if required. Will default to 1 if not supplied",
"schema": {
"type": "integer",
"format": "int32"
}
}
],
"responses": {
"200": {
"description": "The matching holidays. An empty list if nothing matched the filter.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Timetastic.Core.Models.ApiModels.HolidayListResponse"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/Timetastic.Core.Models.ApiModels.HolidayListResponse"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/Timetastic.Core.Models.ApiModels.HolidayListResponse"
}
}
}
},
"401": {
"description": "The request was not authenticated β the API token is missing or invalid."
}
}
},
"post": {
"tags": [
"Holidays"
],
"summary": "Request a Holiday.",
"description": "Use this to submit a leave request to Timetastic.\r\nDepending on your authorisation, you can book for yourself, any other user at your organisation, your department, or the entire organisation.\r\n\r\nNote: This will raise a Webhook event if you have Webhooks configured.\r\n \r\nImportant: a booking that is refused still returns 200. Always check\r\n`success` in the response body rather than relying on the status code. When `success` is `false`,\r\n`response` explains why. Reasons include: the dates contain no working days for that user, the request\r\nis zero length, the end date is before the start date, the user is already off for some of those dates,\r\nthe user has insufficient allowance (or insufficient accrued allowance), the leave type is not active or\r\nits limit has been exceeded, the dates fall before the user's start date or after their end date, the\r\ndates are too far in the future, the leave year's allowance has not been created yet, a maximum-off\r\nlimit would be breached, or the dates are locked.\r\n \r\nThree of those refusals can be retried with an override, and are flagged separately so you can prompt\r\nfor confirmation. Resubmit with the matching request field set to book anyway β each one requires the\r\nappropriate permission:\r\n \r\n- `overrideRequired` (a maximum-off limit) β resubmit with `override`\r\n- `overrideLockedDateRequired` (a locked date) β resubmit with `overrideLockedDays`\r\n- `overrideAccruedAllowanceRequired` (accrued allowance) β resubmit with `overrideAccruedAllowance`\r\n \r\nWhen booking for a department or the whole organisation, `rejections` indicates that some users in the\r\ngroup could not be booked; `response` summarises which.",
"requestBody": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Timetastic.Core.Models.ApiModels.BookHolidayModel"
}
},
"application/json-patch+json": {
"schema": {
"$ref": "#/components/schemas/Timetastic.Core.Models.ApiModels.BookHolidayModel"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/Timetastic.Core.Models.ApiModels.BookHolidayModel"
}
},
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/Timetastic.Core.Models.ApiModels.BookHolidayModel"
}
}
}
},
"responses": {
"200": {
"description": "The request was processed. Check `success` in the body β this is also returned when the booking was refused.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Timetastic.Web.ApiResourceModels.HolidayBookResult"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/Timetastic.Web.ApiResourceModels.HolidayBookResult"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/Timetastic.Web.ApiResourceModels.HolidayBookResult"
}
}
}
},
"400": {
"description": "The request itself was malformed. The body is a plain string. Returned when the request could not be read,\r\nand when a non-administrator tried to book for everyone.",
"content": {
"application/json": {
"schema": {
"type": "string"
}
},
"text/plain": {
"schema": {
"type": "string"
}
},
"text/json": {
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "The request was not authenticated β the API token is missing or invalid."
},
"429": {
"description": "The overall API rate limit was exceeded."
}
}
}
},
"/api/leavetypes": {
"get": {
"tags": [
"LeaveTypes"
],
"summary": "Get a Collection of Leave Types",
"description": "Get a Collection of Leave Types for Your Organisation.",
"parameters": [
{
"name": "includeInactive",
"in": "query",
"description": "Optional. Set to true to also return inactive (deleted) leave types. Defaults to false (active only).",
"schema": {
"type": "boolean",
"default": false
}
}
],
"responses": {
"200": {
"description": "The leave types for your organisation.",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Timetastic.Web.ApiResourceModels.LeaveTypeResponse"
}
}
},
"text/plain": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Timetastic.Web.ApiResourceModels.LeaveTypeResponse"
}
}
},
"text/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Timetastic.Web.ApiResourceModels.LeaveTypeResponse"
}
}
}
}
},
"401": {
"description": "The request was not authenticated β the API token is missing or invalid.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails"
}
}
}
}
}
},
"post": {
"tags": [
"LeaveTypes"
],
"summary": "Create a new leave type",
"description": "Creates a new leave type for your organisation. Only admins can create leave types.",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Timetastic.Web.ApiResourceModels.LeaveTypeRequest"
}
},
"application/json-patch+json": {
"schema": {
"$ref": "#/components/schemas/Timetastic.Web.ApiResourceModels.LeaveTypeRequest"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/Timetastic.Web.ApiResourceModels.LeaveTypeRequest"
}
},
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/Timetastic.Web.ApiResourceModels.LeaveTypeRequest"
}
}
}
},
"responses": {
"200": {
"description": "The leave type was successfully created. Returns the ID of the new leave type.",
"content": {
"application/json": {
"schema": {
"type": "integer",
"format": "int32"
}
},
"text/plain": {
"schema": {
"type": "integer",
"format": "int32"
}
},
"text/json": {
"schema": {
"type": "integer",
"format": "int32"
}
}
}
},
"400": {
"description": "Invalid input data or validation error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Timetastic.Web.ApiResourceModels.LeaveTypeError"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/Timetastic.Web.ApiResourceModels.LeaveTypeError"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/Timetastic.Web.ApiResourceModels.LeaveTypeError"
}
}
}
},
"403": {
"description": "You don't have permission to create leave types",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails"
}
}
}
}
}
}
},
"/api/leavetypes/{id}": {
"get": {
"tags": [
"LeaveTypes"
],
"summary": "Get a Leave Type",
"description": "Gets a leave type using the ID passed.",
"parameters": [
{
"name": "id",
"in": "path",
"description": "The ID of the Leave Type.",
"required": true,
"schema": {
"type": "integer",
"format": "int32"
}
}
],
"responses": {
"200": {
"description": "The leave type.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Timetastic.Web.ApiResourceModels.LeaveTypeResponse"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/Timetastic.Web.ApiResourceModels.LeaveTypeResponse"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/Timetastic.Web.ApiResourceModels.LeaveTypeResponse"
}
}
}
},
"401": {
"description": "The request was not authenticated β the API token is missing or invalid.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails"
}
}
}
},
"403": {
"description": "The leave type belongs to another organisation.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails"
}
}
}
},
"404": {
"description": "No leave type exists with that ID.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails"
}
}
}
}
}
},
"put": {
"tags": [
"LeaveTypes"
],
"summary": "Update a leave type",
"description": "Updates an existing leave type. Only admins can update leave types.",
"parameters": [
{
"name": "id",
"in": "path",
"description": "The ID of the leave type to update",
"required": true,
"schema": {
"type": "integer",
"format": "int32"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Timetastic.Web.ApiResourceModels.LeaveTypeRequest"
}
},
"application/json-patch+json": {
"schema": {
"$ref": "#/components/schemas/Timetastic.Web.ApiResourceModels.LeaveTypeRequest"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/Timetastic.Web.ApiResourceModels.LeaveTypeRequest"
}
},
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/Timetastic.Web.ApiResourceModels.LeaveTypeRequest"
}
}
}
},
"responses": {
"200": {
"description": "The leave type was successfully updated"
},
"400": {
"description": "Invalid input data or validation error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Timetastic.Web.ApiResourceModels.LeaveTypeError"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/Timetastic.Web.ApiResourceModels.LeaveTypeError"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/Timetastic.Web.ApiResourceModels.LeaveTypeError"
}
}
}
},
"403": {
"description": "You don't have permission to update this leave type",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails"
}
}
}
},
"404": {
"description": "The leave type was not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails"
}
}
}
}
}
},
"delete": {
"tags": [
"LeaveTypes"
],
"summary": "Delete a leave type",
"description": "Deletes a leave type. Only admins can delete leave types. You cannot delete the last active leave type.",
"parameters": [
{
"name": "id",
"in": "path",
"description": "The ID of the leave type to delete",
"required": true,
"schema": {
"type": "integer",
"format": "int32"
}
}
],
"responses": {
"200": {
"description": "The leave type was successfully deactivated"
},
"400": {
"description": "Invalid request or validation error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Timetastic.Web.ApiResourceModels.LeaveTypeError"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/Timetastic.Web.ApiResourceModels.LeaveTypeError"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/Timetastic.Web.ApiResourceModels.LeaveTypeError"
}
}
}
},
"403": {
"description": "You don't have permission to delete this leave type",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails"
}
}
}
},
"404": {
"description": "The leave type was not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails"
}
}
}
}
}
}
},
"/api/leavetypes/colors": {
"get": {
"tags": [
"LeaveTypes"
],
"summary": "Get available leave type colors",
"description": "Returns a list of valid color hex codes that can be used when creating or updating leave types.\r\nEach color includes a flag indicating whether it's a dark color for UI purposes.",
"responses": {
"200": {
"description": "The list of available colors",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Timetastic.Web.ApiResourceModels.Colour"
}
}
},
"text/plain": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Timetastic.Web.ApiResourceModels.Colour"
}
}
},
"text/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Timetastic.Web.ApiResourceModels.Colour"
}
}
}
}
},
"401": {
"description": "The request was not authenticated β the API token is missing or invalid.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails"
}
}
}
}
}
}
},
"/api/leavetypes/icons": {
"get": {
"tags": [
"LeaveTypes"
],
"summary": "Get available leave type icons",
"description": "Returns a list of valid icon names that can be used when creating or updating leave types.\r\nAn empty string can also be used for no icon.",
"responses": {
"200": {
"description": "The list of available icons",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Timetastic.Web.ApiResourceModels.Icon"
}
}
},
"text/plain": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Timetastic.Web.ApiResourceModels.Icon"
}
}
},
"text/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Timetastic.Web.ApiResourceModels.Icon"
}
}
}
}
},
"401": {
"description": "The request was not authenticated β the API token is missing or invalid.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails"
}
}
}
}
}
}
},
"/api/lockeddates": {
"get": {
"tags": [
"LockedDates"
],
"summary": "List all Locked Dates",
"description": "Get a collection of all locked dates for your organisation.",
"responses": {
"200": {
"description": "Returns the list of locked dates. An empty list if there are none.",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Timetastic.Core.Models.LockedDate"
}
}
},
"text/plain": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Timetastic.Core.Models.LockedDate"
}
}
},
"text/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Timetastic.Core.Models.LockedDate"
}
}
}
}
},
"401": {
"description": "The request was not authenticated β the API token is missing or invalid.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails"
}
}
}
}
}
},
"post": {
"tags": [
"LockedDates"
],
"summary": "Add a Locked Date",
"description": "Creates a new locked date period. Locked dates prevent employees from booking time off during the specified period.\r\nYou can lock dates at organisation level (all employees), department level, or individual user level.\r\nHigher-level locks supersede lower-level locks (e.g., an organisation lock will supersede existing department or user locks).",
"requestBody": {
"description": "The locked date details including date range, reason, and target (organisation, department, or user).",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Timetastic.Core.Models.ApiModels.AddLockedDateRequest"
}
},
"application/json-patch+json": {
"schema": {
"$ref": "#/components/schemas/Timetastic.Core.Models.ApiModels.AddLockedDateRequest"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/Timetastic.Core.Models.ApiModels.AddLockedDateRequest"
}
},
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/Timetastic.Core.Models.ApiModels.AddLockedDateRequest"
}
}
}
},
"responses": {
"200": {
"description": "The locked date was successfully created",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Timetastic.Web.ApiResourceModels.AddLockedDateResponse"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/Timetastic.Web.ApiResourceModels.AddLockedDateResponse"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/Timetastic.Web.ApiResourceModels.AddLockedDateResponse"
}
}
}
},
"400": {
"description": "Invalid input data or validation error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Timetastic.Web.ApiResourceModels.LockedDateError"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/Timetastic.Web.ApiResourceModels.LockedDateError"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/Timetastic.Web.ApiResourceModels.LockedDateError"
}
}
}
}
}
}
},
"/api/lockeddates/{id}": {
"delete": {
"tags": [
"LockedDates"
],
"summary": "Delete a Locked Date",
"description": "Removes a locked date from the system. Only admins and managers with appropriate permissions can delete locked dates.",
"parameters": [
{
"name": "id",
"in": "path",
"description": "The ID of the locked date to delete.",
"required": true,
"schema": {
"type": "integer",
"format": "int32"
}
}
],
"responses": {
"200": {
"description": "The locked date was successfully deleted",
"content": {
"application/json": {
"schema": {
"enum": [
"Succeeded",
"Failed",
"InvalidValue",
"NothingToDo",
"NotPermitted"
],
"type": "string",
"description": "Standard \"generic\" command operation result. If you need to add more types, you need a new enum\r\n\r\n- `Succeeded`\n- `Failed`\n- `InvalidValue`\n- `NothingToDo`\n- `NotPermitted`"
}
},
"text/plain": {
"schema": {
"enum": [
"Succeeded",
"Failed",
"InvalidValue",
"NothingToDo",
"NotPermitted"
],
"type": "string",
"description": "Standard \"generic\" command operation result. If you need to add more types, you need a new enum\r\n\r\n- `Succeeded`\n- `Failed`\n- `InvalidValue`\n- `NothingToDo`\n- `NotPermitted`"
}
},
"text/json": {
"schema": {
"enum": [
"Succeeded",
"Failed",
"InvalidValue",
"NothingToDo",
"NotPermitted"
],
"type": "string",
"description": "Standard \"generic\" command operation result. If you need to add more types, you need a new enum\r\n\r\n- `Succeeded`\n- `Failed`\n- `InvalidValue`\n- `NothingToDo`\n- `NotPermitted`"
}
}
}
},
"400": {
"description": "Something went wrong while deleting the locked date",
"content": {
"application/json": {
"schema": {
"enum": [
"Succeeded",
"Failed",
"InvalidValue",
"NothingToDo",
"NotPermitted"
],
"type": "string",
"description": "Standard \"generic\" command operation result. If you need to add more types, you need a new enum\r\n\r\n- `Succeeded`\n- `Failed`\n- `InvalidValue`\n- `NothingToDo`\n- `NotPermitted`"
}
},
"text/plain": {
"schema": {
"enum": [
"Succeeded",
"Failed",
"InvalidValue",
"NothingToDo",
"NotPermitted"
],
"type": "string",
"description": "Standard \"generic\" command operation result. If you need to add more types, you need a new enum\r\n\r\n- `Succeeded`\n- `Failed`\n- `InvalidValue`\n- `NothingToDo`\n- `NotPermitted`"
}
},
"text/json": {
"schema": {
"enum": [
"Succeeded",
"Failed",
"InvalidValue",
"NothingToDo",
"NotPermitted"
],
"type": "string",
"description": "Standard \"generic\" command operation result. If you need to add more types, you need a new enum\r\n\r\n- `Succeeded`\n- `Failed`\n- `InvalidValue`\n- `NothingToDo`\n- `NotPermitted`"
}
}
}
}
}
}
},
"/api/publicholidays": {
"get": {
"tags": [
"PublicHolidays"
],
"summary": "Get a List of Public Holidays",
"description": "Get a collection of public holidays for your organisation.\r\n \r\nResults are always scoped to your organisation, so a filter that matches nothing β an unknown country\r\ncode, user or public holiday set, or a user in another organisation β returns an empty list rather than\r\nan error.",
"parameters": [
{
"name": "countryCode",
"in": "query",
"description": "An optional country code to filter the public holidays to.",
"schema": {
"type": "string",
"default": ""
}
},
{
"name": "year",
"in": "query",
"description": "An optional year to filter the public holidays to.",
"schema": {
"type": "integer",
"format": "int32",
"default": 0
}
},
{
"name": "userId",
"in": "query",
"description": "An optional user id to filter the public holidays to.",
"schema": {
"type": "integer",
"format": "int32",
"default": 0
}
},
{
"name": "bankHolidaySetId",
"in": "query",
"description": "An optional bank holiday set to filter the public holidays to.",
"schema": {
"type": "integer",
"format": "int32",
"default": 0
}
},
{
"name": "useOrgLeaveYear",
"in": "query",
"description": "An optional param to specify if we want public holidays for the user's leave year.",
"schema": {
"type": "boolean",
"default": false
}
}
],
"responses": {
"200": {
"description": "The matching public holidays. An empty list if nothing matched the filter.",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Timetastic.Web.ApiResourceModels.PublicHoliday"
}
}
},
"text/plain": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Timetastic.Web.ApiResourceModels.PublicHoliday"
}
}
},
"text/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Timetastic.Web.ApiResourceModels.PublicHoliday"
}
}
}
}
},
"401": {
"description": "The request was not authenticated β the API token is missing or invalid."
}
}
}
},
"/api/publicholidays/{id}": {
"get": {
"tags": [
"PublicHolidays"
],
"summary": "Get a Public Holiday",
"description": "Gets a public holiday using the ID passed.",
"parameters": [
{
"name": "id",
"in": "path",
"description": "The ID of the public holiday.",
"required": true,
"schema": {
"type": "integer",
"format": "int32"
}
}
],
"responses": {
"200": {
"description": "The public holiday.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Timetastic.Web.ApiResourceModels.PublicHoliday"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/Timetastic.Web.ApiResourceModels.PublicHoliday"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/Timetastic.Web.ApiResourceModels.PublicHoliday"
}
}
}
},
"401": {
"description": "The request was not authenticated β the API token is missing or invalid."
},
"403": {
"description": "The public holiday belongs to another organisation."
},
"404": {
"description": "No public holiday exists with that ID."
}
}
}
},
"/api/publicholidays/countries": {
"get": {
"tags": [
"PublicHolidays"
],
"summary": "Get a List of All Countries",
"responses": {
"200": {
"description": "Every country we hold public holidays for, and whether it has regions."
},
"401": {
"description": "The request was not authenticated β the API token is missing or invalid."
}
}
}
},
"/api/users": {
"get": {
"tags": [
"Users"
],
"summary": "Get a Collection of Users",
"description": "Get a Collection of Users for your organisation, optionally filtered by a department.",
"parameters": [
{
"name": "departmentId",
"in": "query",
"description": "An optional department to filter the users",
"schema": {
"type": "integer",
"format": "int32",
"default": 0
}
},
{
"name": "includeArchivedUsers",
"in": "query",
"description": "Whether to include archived users in the search results",
"schema": {
"type": "boolean",
"default": false
}
},
{
"name": "onlyShowArchivedUsers",
"in": "query",
"description": "If archived users are included, should we ONLY show those.",
"schema": {
"type": "boolean",
"default": false
}
}
],
"responses": {
"200": {
"description": "The users you are allowed to see. Department managers only ever see their own departments.",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Timetastic.Web.ApiResourceModels.User"
}
}
},
"text/plain": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Timetastic.Web.ApiResourceModels.User"
}
}
},
"text/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Timetastic.Web.ApiResourceModels.User"
}
}
}
}
},
"401": {
"description": "The request was not authenticated β the API token is missing or invalid."
},
"403": {
"description": "You are neither an administrator nor a department manager, or the `departmentId` filter does not exist or\r\nbelongs to another organisation."
}
}
}
},
"/api/users/{id}": {
"get": {
"tags": [
"Users"
],
"summary": "Get a User",
"description": "Gets a user using the ID passed.",
"parameters": [
{
"name": "id",
"in": "path",
"description": "The ID of the user.",
"required": true,
"schema": {
"type": "integer",
"format": "int32"
}
}
],
"responses": {
"200": {
"description": "The user.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Timetastic.Web.ApiResourceModels.UserDetail"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/Timetastic.Web.ApiResourceModels.UserDetail"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/Timetastic.Web.ApiResourceModels.UserDetail"
}
}
}
},
"401": {
"description": "The request was not authenticated β the API token is missing or invalid."
},
"403": {
"description": "You are not allowed to view that user β including users in another organisation."
},
"404": {
"description": "No user exists with that ID."
}
}
}
},
"/api/users/archive/{id}": {
"post": {
"tags": [
"Users"
],
"summary": "Archive a User",
"description": "Use this to archive a user from Timetastic. They will be immediately logged out and unable to log in.\r\n \r\nThis endpoint is limited to 2 requests per second. An `archiveDate` must be supplied in the body.",
"parameters": [
{
"name": "id",
"in": "path",
"description": "The ID of the user to archive",
"required": true,
"schema": {
"type": "integer",
"format": "int32"
}
}
],
"requestBody": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Timetastic.Core.Models.ApiModels.ArchiveUserApiModel"
}
},
"application/json-patch+json": {
"schema": {
"$ref": "#/components/schemas/Timetastic.Core.Models.ApiModels.ArchiveUserApiModel"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/Timetastic.Core.Models.ApiModels.ArchiveUserApiModel"
}
},
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/Timetastic.Core.Models.ApiModels.ArchiveUserApiModel"
}
}
}
},
"responses": {
"200": {
"description": "The user was archived."
},
"400": {
"description": "The user could not be archived. `errorStatus` says why.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Timetastic.Web.ApiResourceModels.UserError"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/Timetastic.Web.ApiResourceModels.UserError"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/Timetastic.Web.ApiResourceModels.UserError"
}
}
}
},
"401": {
"description": "The request was not authenticated β the API token is missing or invalid."
},
"403": {
"description": "The authenticated user is not an administrator."
},
"429": {
"description": "The endpoint limit of 2 requests per second was exceeded."
}
}
}
},
"/api/users/restore/{id}": {
"post": {
"tags": [
"Users"
],
"summary": "Restore a User",
"description": "Use this to restore a user from Timetastic's Archive - they will be able to log in and use Timetastic as normal.\r\n \r\nThis endpoint is limited to 2 requests per second.\r\n \r\nOn success the body contains `wasEmailInUse`. When this is `true` the user was restored without their\r\noriginal email address, because another active user has since taken it β set a new email address with\r\nthe edit endpoint before they can log in.",
"parameters": [
{
"name": "id",
"in": "path",
"description": "The ID of the user to restore",
"required": true,
"schema": {
"type": "integer",
"format": "int32"
}
}
],
"responses": {
"200": {
"description": "The user was restored, e.g. `{ \"wasEmailInUse\": false }`."
},
"400": {
"description": "The user could not be restored. `errorStatus` says why.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Timetastic.Web.ApiResourceModels.UserError"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/Timetastic.Web.ApiResourceModels.UserError"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/Timetastic.Web.ApiResourceModels.UserError"
}
}
}
},
"401": {
"description": "The request was not authenticated β the API token is missing or invalid."
},
"403": {
"description": "The authenticated user is not an administrator."
},
"429": {
"description": "The endpoint limit of 2 requests per second was exceeded."
}
}
}
},
"/api/users/edit/{id}": {
"post": {
"tags": [
"Users"
],
"summary": "Edit a User",
"description": "Edits an existing user in Timetastic. Allows you to populate more data into a user record after an\r\ninitial ADD operation. You can pass any combination of the following parameters and only those values\r\nwill be changed.\r\n \r\nThis endpoint is limited to 2 requests per second.\r\n \r\nAttempts that supply an email address already in use are counted against your organisation. The\r\ncount is shared with the add endpoint, and after 10 of them both start returning 429. The\r\ncount expires 24 hours after the *first* failure, not the last, and succeeding in the meantime\r\ndoes not clear it. Check for an existing user before retrying rather than letting these\r\naccumulate.",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "integer",
"format": "int32"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Timetastic.Core.Models.ApiModels.EditUserApiModel"
}
},
"application/json-patch+json": {
"schema": {
"$ref": "#/components/schemas/Timetastic.Core.Models.ApiModels.EditUserApiModel"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/Timetastic.Core.Models.ApiModels.EditUserApiModel"
}
},
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/Timetastic.Core.Models.ApiModels.EditUserApiModel"
}
}
}
},
"responses": {
"200": {
"description": "The user was updated."
},
"400": {
"description": "The edit was rejected. `errorStatus` says why.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Timetastic.Web.ApiResourceModels.EditUserError"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/Timetastic.Web.ApiResourceModels.EditUserError"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/Timetastic.Web.ApiResourceModels.EditUserError"
}
}
}
},
"401": {
"description": "The change was not permitted β `errorStatus` says why. An unauthenticated request also returns\r\n401, but with no body at all.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Timetastic.Web.ApiResourceModels.EditUserError"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/Timetastic.Web.ApiResourceModels.EditUserError"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/Timetastic.Web.ApiResourceModels.EditUserError"
}
}
}
},
"403": {
"description": "The authenticated user is not an administrator."
},
"429": {
"description": "Too many recent requests supplied an email address that was already in use. Exceeding the endpoint\r\nlimit of 2 requests per second also returns 429, but as a plain text message from the rate limiter\r\nrather than this body.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Timetastic.Web.ApiResourceModels.EditUserRateLimitedError"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/Timetastic.Web.ApiResourceModels.EditUserRateLimitedError"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/Timetastic.Web.ApiResourceModels.EditUserRateLimitedError"
}
}
}
}
}
}
},
"/api/users/add": {
"post": {
"tags": [
"Users"
],
"summary": "Add a User",
"description": "Adds a new user to Timetastic, optionally triggering a welcome email.\r\n \r\nThis endpoint is limited to 2 requests per second.\r\n \r\nAttempts that supply an email address already in use are counted against your organisation. The\r\ncount is shared with the edit endpoint, and after 10 of them both start returning 429. The\r\ncount expires 24 hours after the *first* failure, not the last, and succeeding in the meantime\r\ndoes not clear it. Check for an existing user before retrying rather than letting these\r\naccumulate.",
"requestBody": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Timetastic.Core.Models.ApiModels.AddUserApiModel"
}
},
"application/json-patch+json": {
"schema": {
"$ref": "#/components/schemas/Timetastic.Core.Models.ApiModels.AddUserApiModel"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/Timetastic.Core.Models.ApiModels.AddUserApiModel"
}
},
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/Timetastic.Core.Models.ApiModels.AddUserApiModel"
}
}
}
},
"responses": {
"200": {
"description": "The user was created. Returns the ID of the new user, e.g. `{ \"id\": 1234 }`."
},
"400": {
"description": "The user could not be created. `errorStatus` says why.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Timetastic.Web.ApiResourceModels.AddUserError"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/Timetastic.Web.ApiResourceModels.AddUserError"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/Timetastic.Web.ApiResourceModels.AddUserError"
}
}
}
},
"401": {
"description": "The request was not authenticated β the API token is missing or invalid."
},
"403": {
"description": "The authenticated user is not an administrator."
},
"429": {
"description": "Too many recent requests supplied an email address that was already in use. Note the reason is\r\ncarried in `result` rather than `errorStatus`. Exceeding the endpoint limit of 2 requests per\r\nsecond also returns 429, but as a plain text message from the rate limiter rather than this body.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Timetastic.Web.ApiResourceModels.AddUserRateLimitedError"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/Timetastic.Web.ApiResourceModels.AddUserRateLimitedError"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/Timetastic.Web.ApiResourceModels.AddUserRateLimitedError"
}
}
}
}
}
}
},
"/api/users/contact/{id}": {
"get": {
"tags": [
"Users"
],
"summary": "Get a User & Contact details",
"description": "Retrieves a specific user. In addition to the user detail, we return their work schedule, their allowances and any details from the Contact tab.\n\n βΉοΈ This endpoint is only accessible if you have a Timetastic Pro account ",
"parameters": [
{
"name": "id",
"in": "path",
"description": "",
"required": true,
"schema": {
"type": "integer",
"format": "int32"
}
}
],
"responses": {
"200": {
"description": "The user, with their work schedule, allowances and contact details.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Timetastic.Web.ApiResourceModels.UserWithContact"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/Timetastic.Web.ApiResourceModels.UserWithContact"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/Timetastic.Web.ApiResourceModels.UserWithContact"
}
}
}
},
"401": {
"description": "The request was not authenticated β the API token is missing or invalid."
},
"403": {
"description": "You are not an administrator, your organisation is not on the Pro plan, or you are not allowed to view that user."
},
"404": {
"description": "No user exists with that ID."
}
}
}
},
"/api/users/{userId}/publicholidays": {
"patch": {
"tags": [
"Users"
],
"summary": "Assign public holidays to a user",
"description": "Use when you want to assign a set of public holidays to a user. Will turn public holidays on for this user if they are not already.\r\n If you pick a country/region code that's already in use by your organisation (which may have customisations from Timetastic's UI) - that set will be used\r\n If you pick a country/region that's not already in use by your organisation you'll get the standard public holidays for that region.",
"parameters": [
{
"name": "userId",
"in": "path",
"description": "The user's ID in Timetastic",
"required": true,
"schema": {
"type": "integer",
"format": "int32"
}
}
],
"requestBody": {
"description": "The country and (optional) region codes to assign.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Timetastic.Web.ApiResourceModels.AssignPublicHolidayModel"
}
},
"application/json-patch+json": {
"schema": {
"$ref": "#/components/schemas/Timetastic.Web.ApiResourceModels.AssignPublicHolidayModel"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/Timetastic.Web.ApiResourceModels.AssignPublicHolidayModel"
}
},
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/Timetastic.Web.ApiResourceModels.AssignPublicHolidayModel"
}
}
}
},
"responses": {
"200": {
"description": "The public holiday set was assigned, or the user already had it."
},
"400": {
"description": "The request was rejected. This response has no body. It is returned when the body is missing or has no\r\n`countryCode`, when the country/region code is not recognised, when the user ID does not exist or belongs\r\nto another organisation, and when you are not allowed to manage that user."
},
"401": {
"description": "The request was not authenticated β the API token is missing or invalid."
}
}
}
},
"/api/webhooks/list/{daysHistory}": {
"get": {
"tags": [
"Webhooks"
],
"summary": "Get Webhook Events",
"description": "Get a list of the recent Webhook items (defaults to the last day).\r\nThe dashboard will show events raised in the last day.\r\nTimetastic retains 30 days of Webhook event history and you can access this via the API.\r\n \r\n`daysHistory` is optional and defaults to 1. It is capped at 30 β a larger value is silently\r\nreduced rather than rejected.",
"parameters": [
{
"name": "daysHistory",
"in": "query",
"schema": {
"type": "integer",
"format": "int32",
"default": 1
}
}
],
"responses": {
"200": {
"description": "The recent webhook events. An empty list if there were none in that window.",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Timetastic.Core.Models.WebhookEvent"
}
}
},
"text/plain": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Timetastic.Core.Models.WebhookEvent"
}
}
},
"text/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Timetastic.Core.Models.WebhookEvent"
}
}
}
}
},
"401": {
"description": "The request was not authenticated β the API token is missing or invalid."
},
"403": {
"description": "The authenticated user is not an administrator."
}
}
}
},
"/api/webhooks": {
"post": {
"tags": [
"Webhooks"
],
"summary": "Webhook Payload",
"description": "This is an example of the payload you'll receive when we make a webhook request to your server.\r\nAnything other than a 2xx response will be treated as a failure and redirects will not be followed.\r\n \r\nThis entry documents the payload we send to *you*. It is not a callable Timetastic endpoint.",
"responses": {
"200": {
"description": "The shape of the payload we POST to your webhook URL. Shown for reference only; this endpoint\r\nnever returns it.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Timetastic.Core.QueueModels.WebhookPayload"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/Timetastic.Core.QueueModels.WebhookPayload"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/Timetastic.Core.QueueModels.WebhookPayload"
}
}
}
},
"404": {
"description": "Always. There is nothing to call here."
}
}
}
}
},
"components": {
"schemas": {
"Microsoft.AspNetCore.Mvc.ProblemDetails": {
"type": "object",
"properties": {
"type": {
"type": "string",
"nullable": true
},
"title": {
"type": "string",
"nullable": true
},
"status": {
"type": "integer",
"format": "int32",
"nullable": true
},
"detail": {
"type": "string",
"nullable": true
},
"instance": {
"type": "string",
"nullable": true
}
},
"additionalProperties": { }
},
"Timetastic.Core.Commands.Absence": {
"type": "object",
"properties": {
"absenceType": {
"enum": [
"Booking",
"PublicHoliday",
"NonWorkingDay",
"LockedDate",
"Birthday",
"WorkAnniversary"
],
"type": "string",
"description": "Whether it's an absence, locked date, public holiday, etc.\r\n\r\n- `Booking`\n- `PublicHoliday`\n- `NonWorkingDay`\n- `LockedDate`\n- `Birthday`\n- `WorkAnniversary`"
},
"start": {
"type": "string",
"description": "Start date/time of the event (for non working days this is based off the user's work schedule so you get the exact time the user isn't working)",
"format": "date-time"
},
"end": {
"type": "string",
"description": "End date/time of the event (for non working days this is based off the user's work schedule so you get the exact time the user isn't working)",
"format": "date-time"
},
"detail": {
"type": "string",
"description": "Leave Type name, locked date summary, public holiday name",
"nullable": true
},
"entityId": {
"type": "integer",
"description": "Holiday ID, Locked Date ID etc.",
"format": "int32",
"nullable": true
},
"userId": {
"type": "integer",
"description": "The userID this relates to",
"format": "int32",
"nullable": true
},
"userName": {
"type": "string",
"description": "The user's name as displayed in Timetastic",
"nullable": true
},
"startUtc": {
"type": "string",
"description": "UTC equivalent of Start, using the organisation timezone.",
"format": "date-time",
"nullable": true
},
"endUtc": {
"type": "string",
"description": "UTC equivalent of End, using the organisation timezone.",
"format": "date-time",
"nullable": true
}
},
"additionalProperties": false
},
"Timetastic.Core.Commands.AbsenceDay": {
"type": "object",
"properties": {
"date": {
"type": "string",
"format": "date"
},
"absences": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Timetastic.Core.Commands.Absence"
},
"nullable": true
}
},
"additionalProperties": false
},
"Timetastic.Core.Models.ApiModels.ActionHolidayModel": {
"type": "object",
"properties": {
"reason": {
"type": "string",
"description": "An optional reason for rejecting a leave request.",
"nullable": true
},
"suppressEmails": {
"type": "boolean",
"description": "Set to true to suppress notifications and emails to users when actioning holiday requests."
}
},
"additionalProperties": false
},
"Timetastic.Core.Models.ApiModels.AddLockedDateRequest": {
"required": [
"from",
"reason",
"recordId",
"recordType",
"to"
],
"type": "object",
"properties": {
"from": {
"type": "string",
"format": "date-time"
},
"to": {
"type": "string",
"format": "date-time"
},
"reason": {
"maxLength": 2000,
"minLength": 1,
"type": "string"
},
"recordId": {
"type": "integer",
"format": "int32"
},
"recordType": {
"enum": [
1,
2,
3
],
"type": "integer",
"description": "- `1` β **Organisation**\n- `2` β **Department**\n- `3` β **User**",
"format": "int32"
}
},
"additionalProperties": false
},
"Timetastic.Core.Models.ApiModels.AddUserApiModel": {
"required": [
"allowance",
"departmentId",
"firstName",
"lastName"
],
"type": "object",
"properties": {
"firstName": {
"minLength": 1,
"type": "string",
"description": "The user's first name"
},
"lastName": {
"minLength": 1,
"type": "string",
"description": "The user's last name"
},
"emailAddress": {
"type": "string",
"description": "The new user's Email address",
"format": "email",
"nullable": true
},
"leaveYearStart": {
"maximum": 12,
"minimum": 1,
"type": "integer",
"description": "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",
"format": "int32",
"nullable": true
},
"allowance": {
"maximum": 366,
"minimum": 0,
"type": "number",
"description": "The user's annual allowance in days",
"format": "double"
},
"startDate": {
"type": "string",
"description": "The user's start date. In ISO 8601 format: 2022-02-04T00:00:00",
"format": "date-time",
"nullable": true
},
"departmentId": {
"maximum": 2147483647,
"minimum": 1,
"type": "integer",
"description": "The ID of the department that this user is in",
"format": "int32"
},
"sendWelcomeEmail": {
"type": "boolean",
"description": "Whether to send the user an email to set a password and start using Timetastic"
}
},
"additionalProperties": false
},
"Timetastic.Core.Models.ApiModels.ArchiveUserApiModel": {
"type": "object",
"properties": {
"archiveDate": {
"type": "string",
"description": "The Date this user left your organisation.Must be in the past (UTC). Timetastic will display this on the archived user's profile and in reports",
"format": "date-time"
}
},
"additionalProperties": false
},
"Timetastic.Core.Models.ApiModels.BookHolidayModel": {
"type": "object",
"properties": {
"from": {
"type": "string",
"description": "The start date of the request. Don't include any time information.",
"format": "date-time"
},
"to": {
"type": "string",
"description": "The end date of the requeset. Don't include any time information.",
"format": "date-time"
},
"fromTime": {
"type": "string",
"description": "Use in conjuction with the From to denote the part of day that the leave request starts.\r\nAM: Starts in the morning of the day.\r\nPM: Starts at lunchtime of the day.\r\nNumber: Alternatively, for hourly bookings, you can specify a time, expressed as minutes since midnight.",
"nullable": true
},
"toTime": {
"type": "string",
"description": "Use in conjuction with the To to denote the part of day that the leave request ends.\r\nAM: Ends at the end of the the morning (lunchtime).\r\nPM: Ends at the end of the day.\r\nNumber: Alternatively, for hourly bookings, you can specify a time, expressed as minutes since midnight.",
"nullable": true
},
"leaveTypeId": {
"type": "integer",
"description": "The leave type for the request",
"format": "int32"
},
"reason": {
"type": "string",
"description": "An optional reason for the request.",
"nullable": true
},
"userOrDepartmentId": {
"type": "integer",
"description": "The ID of the user or department you are making the request for. Use in conjunction with BookFor.",
"format": "int32"
},
"bookFor": {
"enum": [
"User",
"Department",
"Everyone"
],
"type": "string",
"description": "Flag to set if you are booking for a user, department, or everyone.\r\n\r\n- `User`\n- `Department`\n- `Everyone`"
},
"suppressEmails": {
"type": "boolean",
"description": "If you are an admin, you can request that emails are suppressed for this request.\r\nThis will prevent any leave request emails from being sent when the request is processed."
},
"override": {
"type": "boolean",
"description": "If you are an admin, and the booking would be rejected because it exceeds the max-off limit for this department,\r\nsetting override allows you to make the booking despite that limit."
},
"bookAsRequestee": {
"type": "boolean",
"description": "If you are an admin, set this to true to make the leave request as though it were being made by the requestee (the person you are booking for).\r\nThis ensures the normal approval flow will happen.\r\nThe default is false - leave requests will be booked by the admin user account making the API call."
},
"overrideLockedDays": {
"type": "boolean",
"description": "If you are an admin, and the booking would be rejected because it covers locked dates\r\nsetting OverrideLockedDays allows you to make the booking ignoring existing locks."
},
"overrideAccruedAllowance": {
"type": "boolean",
"description": "If you are an admin, and the booking would be rejected because it doesn't have enough accrued allowance, but has enough annual allowance.\r\nsetting OverrideAccruedAllowance allows you to make the booking ignoring accrued allowance."
},
"attachmentId": {
"type": "integer",
"description": "If you've added an attachment, assign it to this booking by passing the ID here.",
"format": "int32",
"nullable": true
}
},
"additionalProperties": false,
"description": "Represent a leave booking request"
},
"Timetastic.Core.Models.ApiModels.EditUserApiModel": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"description": "The unique Id for this user",
"format": "int32"
},
"emailAddress": {
"type": "string",
"description": "The user's email address. To clear a user's email address you must pass a blank string to this parameter: \"\"",
"nullable": true
},
"firstname": {
"maxLength": 35,
"minLength": 1,
"type": "string",
"description": "The user's first name",
"nullable": true
},
"lastname": {
"maxLength": 35,
"minLength": 1,
"type": "string",
"description": "The user's last name",
"nullable": true
},
"startDate": {
"type": "string",
"description": "The user's start date",
"format": "date-time",
"nullable": true
},
"birthday": {
"type": "string",
"description": "The user's date of birth",
"format": "date-time",
"nullable": true
},
"departmentId": {
"maximum": 2147483647,
"minimum": 1,
"type": "integer",
"description": "The ID of the department that this user is in",
"format": "int32",
"nullable": true
},
"admin": {
"type": "boolean",
"description": "Whether the user is a Timetastic Admin (User must have an email address to set this)",
"nullable": true
},
"director": {
"type": "boolean",
"nullable": true
},
"approverId": {
"type": "integer",
"description": "The user's Approver - set this to 0 to default the user's approver to their department boss",
"format": "int32",
"nullable": true
},
"publicHolidaySetId": {
"type": "integer",
"description": "The user's public holiday SetId. HasPublicHolidays will need to be enabled for this to update the user. See Public Holidays for details on \"sets\"",
"format": "int32",
"nullable": true
},
"jobTitle": {
"type": "string",
"nullable": true
},
"payrollId": {
"type": "string",
"nullable": true
},
"address1": {
"type": "string",
"nullable": true
},
"address2": {
"type": "string",
"nullable": true
},
"city": {
"type": "string",
"nullable": true
},
"postCode": {
"type": "string",
"nullable": true
},
"telephone1": {
"type": "string",
"nullable": true
},
"telephone2": {
"type": "string",
"nullable": true
},
"country": {
"type": "string",
"nullable": true
},
"emergencyContactName": {
"type": "string",
"nullable": true
},
"emergencyContactPhone": {
"type": "string",
"nullable": true
},
"hasPublicHolidays": {
"type": "boolean",
"description": "Whether the user has public holidays enabled. If you're setting public holidays for a new user or user that's not had public holidays enabled before you'll also need to pass a valid PublicHolidaySetId in the same request",
"nullable": true
}
},
"additionalProperties": false
},
"Timetastic.Core.Models.ApiModels.HolidayApiModel": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"description": "The unique Id for this holiday",
"format": "int32"
},
"dateRangeString": {
"type": "string",
"description": "A formatted string representation of the holiday date range",
"nullable": true
},
"startDateString": {
"type": "string",
"description": "A formatted string representation of the holiday start date",
"nullable": true
},
"endDateString": {
"type": "string",
"description": "A formatted string representation of the holiday end date",
"nullable": true
},
"startDate": {
"type": "string",
"description": "Start of the holiday. Use in conjunction with the start type to determine the holiday start",
"format": "date-time"
},
"adjustedStartDateUtc": {
"type": "string",
"description": "UTC equivalent of the actual start of the booking period, adjusted for the organisation timezone and user work schedule.\r\nFor daily bookings this reflects the start of the working day/period.",
"format": "date-time",
"nullable": true
},
"startType": {
"enum": [
"Morning",
"Afternoon",
"Hours"
],
"type": "string",
"description": "Morning - Booked for the morning of the start date\r\nAfternoon - Booked after the morning of the start date (starts at lunchtime)\r\nHours - This is an hourly booking, use the time in the Start.\r\n\r\n- `Morning`\n- `Afternoon`\n- `Hours`"
},
"endDate": {
"type": "string",
"description": "End of the holiday. Use in conjunction with the end type to determine the holiday end",
"format": "date-time"
},
"adjustedEndDateUtc": {
"type": "string",
"description": "UTC equivalent of the actual end of the booking period, adjusted for the organisation timezone and user work schedule.",
"format": "date-time",
"nullable": true
},
"endType": {
"enum": [
"Morning",
"Afternoon",
"Hours"
],
"type": "string",
"description": "Used to define the time the holiday ends:\r\nMorning - Ends after the morning of the last day (lunchtime)\r\nAfternoon - Ends at the end of the last day (whole day booked)\r\nHours - This is an hourly booking, use the time in the Start.\r\n\r\n- `Morning`\n- `Afternoon`\n- `Hours`"
},
"userId": {
"type": "integer",
"description": "The user this leave is for",
"format": "int32"
},
"userName": {
"type": "string",
"description": "The user name this leave is for",
"nullable": true
},
"requestedById": {
"type": "integer",
"description": "The user who requested this leave",
"format": "int32"
},
"leaveTypeId": {
"type": "integer",
"format": "int32"
},
"duration": {
"type": "number",
"format": "double"
},
"deduction": {
"type": "number",
"format": "double"
},
"actionerId": {
"type": "integer",
"format": "int32"
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"updatedAt": {
"type": "string",
"format": "date-time"
},
"reason": {
"type": "string",
"description": "The reason for the holiday. Only visible if the requestor has permissions to see this",
"nullable": true
},
"declineReason": {
"type": "string",
"description": "The reason for declining (or cancelling) the holiday. Only visible if the requestor has permissions to see this",
"nullable": true
},
"status": {
"enum": [
"Pending",
"Approved",
"Cancelled",
"Declined"
],
"type": "string",
"description": "The status of this holiday\r\n\r\n- `Pending`\n- `Approved`\n- `Cancelled`\n- `Declined`"
},
"autoApproved": {
"type": "boolean",
"description": "Whether this holiday was automatically approved (for example, if booked by an Admin user)"
},
"bookingUnit": {
"enum": [
"Days",
"Hours"
],
"type": "string",
"description": "Whether the holiday was booked in day(s) or hours.\r\n\r\n- `Days`\n- `Hours`"
},
"leaveType": {
"type": "string",
"nullable": true
}
},
"additionalProperties": false,
"description": "A representation of a holiday"
},
"Timetastic.Core.Models.ApiModels.HolidayListResponse": {
"type": "object",
"properties": {
"holidays": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Timetastic.Core.Models.ApiModels.HolidayApiModel"
},
"nullable": true
},
"totalRecords": {
"type": "integer",
"format": "int32"
},
"pageNumber": {
"type": "integer",
"format": "int32"
},
"nextPageLink": {
"type": "string",
"nullable": true
},
"previousPageLink": {
"type": "string",
"nullable": true
}
},
"additionalProperties": false,
"description": "A wrapped list of holidays."
},
"Timetastic.Core.Models.ApiModels.Toil": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"format": "int32",
"nullable": true
},
"amount": {
"type": "number",
"format": "double",
"nullable": true
},
"description": {
"type": "string",
"nullable": true
}
},
"additionalProperties": false
},
"Timetastic.Core.Models.ApiModels.Toils": {
"type": "object",
"properties": {
"total": {
"type": "number",
"format": "double"
},
"toil": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Timetastic.Core.Models.ApiModels.Toil"
},
"nullable": true
}
},
"additionalProperties": false
},
"Timetastic.Core.Models.ApiModels.UpdateDepartmentApiModel": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "The Department name",
"nullable": true
},
"managerId": {
"maximum": 2147483647,
"minimum": 1,
"type": "integer",
"description": "The userId of the Manager for this department",
"format": "int32",
"nullable": true
},
"maxOff": {
"maximum": 20,
"minimum": 0,
"type": "integer",
"description": "The maximum number of users that can be absent in this department at once. Set to 0 to disable Maximum absent and have no limit.",
"format": "int32",
"nullable": true
}
},
"additionalProperties": false
},
"Timetastic.Core.Models.ApiModels.UserAllowanceResponse": {
"type": "object",
"properties": {
"year": {
"type": "integer",
"format": "int32"
},
"allowance": {
"type": "number",
"format": "double"
},
"toils": {
"$ref": "#/components/schemas/Timetastic.Core.Models.ApiModels.Toils"
},
"carryForward": {
"type": "number",
"format": "double"
}
},
"additionalProperties": false
},
"Timetastic.Core.Models.ApiModels.UsersAllowancesResponse": {
"type": "object",
"properties": {
"userId": {
"type": "integer",
"format": "int32"
},
"userAllowances": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Timetastic.Core.Models.ApiModels.UserAllowanceResponse"
},
"nullable": true
}
},
"additionalProperties": false
},
"Timetastic.Core.Models.LockedDate": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"format": "int32"
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"createdById": {
"type": "integer",
"format": "int32"
},
"reason": {
"type": "string",
"nullable": true
},
"startTime": {
"type": "string",
"format": "date-time"
},
"endTime": {
"type": "string",
"format": "date-time"
},
"organisationId": {
"type": "integer",
"format": "int32"
},
"recordId": {
"type": "integer",
"format": "int32"
},
"recordType": {
"enum": [
1,
2,
3
],
"type": "integer",
"description": "- `1` β **Organisation**\n- `2` β **Department**\n- `3` β **User**",
"format": "int32"
}
},
"additionalProperties": false
},
"Timetastic.Core.Models.WebhookEvent": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"description": "The Event ID",
"format": "int32"
},
"organisationId": {
"type": "integer",
"description": "Your Organisation ID",
"format": "int32"
},
"recordId": {
"type": "integer",
"description": "The recordID associated with this event",
"format": "int32"
},
"userId": {
"type": "integer",
"description": "The UserID that raised this event",
"format": "int32"
},
"retryCount": {
"type": "integer",
"description": "How many attempts to deliver this event there have been",
"format": "int32"
},
"eventType": {
"enum": [
0,
1,
2,
3,
4,
5,
6
],
"type": "integer",
"description": "The Event Type ID\r\n\r\n- `0` β **TestEvent**\n- `1` β **AbsenceRequested**\n- `2` β **AbsenceApproved**\n- `3` β **AbsenceDeclined**\n- `4` β **AbsenceCancelled**\n- `5` β **AbsenceBooked**\n- `6` β **AbsenceUpdated**",
"format": "int32"
},
"expiresAt": {
"type": "string",
"description": "The Expiry Date and Time (UTC)",
"format": "date-time"
},
"timestamp": {
"type": "string",
"description": "When the Event was raised (UTC)",
"format": "date-time"
},
"isProcessed": {
"type": "boolean",
"description": "true if your server has responded success, otherwise false"
},
"lastProcessedAt": {
"type": "string",
"description": "The UTC Time that the event was last attempted",
"format": "date-time",
"nullable": true
},
"lastResponseCode": {
"type": "integer",
"description": "The HTTP Code we last received from your server (trimmed to 4000 characters)",
"format": "int32"
},
"lastResponseDetail": {
"type": "string",
"description": "The HTTP Content we last received from your server",
"nullable": true
},
"nextAttempt": {
"type": "string",
"description": "The scheduled time this event will be next attempted (there may be a short delay if many events are queued)",
"format": "date-time",
"readOnly": true
},
"url": {
"type": "string",
"description": "The URL assigned to this event",
"nullable": true
},
"type": {
"enum": [
0
],
"type": "integer",
"description": "Used internally for the type of webhook we're sending. For your requests this will always be 0\r\n\r\n- `0` β **Timetastic**",
"format": "int32"
}
},
"additionalProperties": false
},
"Timetastic.Core.QueueModels.WebhookPayload": {
"type": "object",
"properties": {
"eventId": {
"type": "integer",
"description": "Event ID is how we reference individual events. They are globally unique per event",
"format": "int32"
},
"eventType": {
"enum": [
"TestEvent",
"AbsenceRequested",
"AbsenceApproved",
"AbsenceDeclined",
"AbsenceCancelled",
"AbsenceBooked",
"AbsenceUpdated"
],
"type": "string",
"description": "The type of event we're raising - The recordID will be related to this\r\n\r\n- `TestEvent`\n- `AbsenceRequested`\n- `AbsenceApproved`\n- `AbsenceDeclined`\n- `AbsenceCancelled`\n- `AbsenceBooked`\n- `AbsenceUpdated`"
},
"url": {
"type": "string",
"description": "The URL We're posting to",
"nullable": true
},
"recordId": {
"type": "integer",
"description": "The related record the event concerns. This is currently just the HolidayID as Webhooks only reference bookings for now.",
"format": "int32"
},
"timestamp": {
"type": "string",
"description": "When did the event happen (UTC)",
"format": "date-time"
},
"performingUser": {
"$ref": "#/components/schemas/Timetastic.Core.QueueModels.WebhookUser"
},
"recordData": {
"$ref": "#/components/schemas/Timetastic.Core.Models.ApiModels.HolidayApiModel"
}
},
"additionalProperties": false
},
"Timetastic.Core.QueueModels.WebhookUser": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"description": "The user's ID",
"format": "int32"
},
"firstname": {
"type": "string",
"description": "User's firstname",
"nullable": true
},
"surname": {
"type": "string",
"description": "User's surname/lastname",
"nullable": true
},
"fullname": {
"type": "string",
"description": "User's Full name",
"nullable": true
}
},
"additionalProperties": false,
"description": "A slimmed down user object for just passing the ID and name back to reduce the JSON payload."
},
"Timetastic.Web.ApiResourceModels.AddLockedDateResponse": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"format": "int32"
},
"createdOverExistingBookings": {
"type": "boolean"
}
},
"additionalProperties": false
},
"Timetastic.Web.ApiResourceModels.AddUserError": {
"type": "object",
"properties": {
"errorStatus": {
"enum": [
2,
3,
5,
8
],
"type": "integer",
"description": "Why the user could not be added.\r\n\r\n- `2` β **Failed**: The user could not be created. Common causes are a departmentId that belongs to another organisation, and a recently created account that has hit its temporary user limit.\n- `3` β **InvalidValue**: A supplied value was rejected: an email address already in use by another Timetastic user, an email address on a blocked domain, a blank first or last name, or a start date outside the current or next leave year.\n- `5` β **NotPermitted**: You are not allowed to add users to that department.\n- `8` β **InvalidEmail**: The email address failed format validation.",
"format": "int32"
},
"errorMessage": {
"type": "string",
"description": "A human readable description of what went wrong.",
"nullable": true
}
},
"additionalProperties": false,
"description": "Returned when a request to add a user is rejected."
},
"Timetastic.Web.ApiResourceModels.AddUserRateLimitedError": {
"type": "object",
"properties": {
"result": {
"enum": [
6
],
"type": "integer",
"description": "Always `6`.\r\n\r\n- `6` β **RateLimited**: Your organisation has supplied an email address that was already in use 10 times, so adding and editing users are both blocked until 24 hours after the first of those failures.",
"format": "int32"
},
"errorMessage": {
"type": "string",
"description": "A human readable description of what went wrong.",
"nullable": true
}
},
"additionalProperties": false,
"description": "Returned when adding a user is blocked because your organisation has supplied an email address\r\nthat was already in use too many times."
},
"Timetastic.Web.ApiResourceModels.AllowanceError": {
"type": "object",
"properties": {
"errorStatus": {
"type": "string",
"nullable": true
},
"errorMessage": {
"type": "string",
"nullable": true
}
},
"additionalProperties": false
},
"Timetastic.Web.ApiResourceModels.AssignPublicHolidayModel": {
"type": "object",
"properties": {
"regionCode": {
"type": "string",
"description": "The full ISO-3166-1 alpha-2 region code for the region (e.g AndalucΓa, Spain: \"ES-AN\", Scotland, UK: \"GB-SCT\")",
"nullable": true
},
"countryCode": {
"type": "string",
"description": "The ISO 3166-1 alpha-2 country code for the country (e.g. Spain: \"ES\")",
"nullable": true
}
},
"additionalProperties": false
},
"Timetastic.Web.ApiResourceModels.Colour": {
"type": "object",
"properties": {
"value": {
"type": "string",
"nullable": true
},
"isDark": {
"type": "boolean"
}
},
"additionalProperties": false
},
"Timetastic.Web.ApiResourceModels.Department": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"description": "The unique Id for this department",
"format": "int32"
},
"organisationId": {
"type": "integer",
"description": "The organisation Id of this department",
"format": "int32"
},
"name": {
"type": "string",
"description": "The department's name",
"nullable": true
},
"managerId": {
"type": "integer",
"format": "int32"
},
"bossId": {
"type": "integer",
"description": "The department's boss",
"format": "int32",
"deprecated": true
},
"createdAt": {
"type": "string",
"description": "When the department was created",
"format": "date-time"
},
"updatedAt": {
"type": "string",
"description": "When the department was last updated",
"format": "date-time"
},
"archived": {
"type": "boolean",
"description": "Whether the department is archived (deleted)"
},
"userCount": {
"type": "integer",
"description": "User count",
"format": "int32"
},
"maxOff": {
"type": "integer",
"description": "The maximum number of staff allowed off at any one time",
"format": "int32"
}
},
"additionalProperties": false,
"description": "A representation of a department"
},
"Timetastic.Web.ApiResourceModels.DepartmentError": {
"type": "object",
"properties": {
"errorStatus": {
"enum": [
1,
2,
3,
4
],
"type": "integer",
"description": "The reason a department operation failed.\r\n\r\n- `1` β **Failed**: The operation failed for an unspecified reason. Inspect ErrorMessage.\n- `2` β **InvalidValue**: The request contained an invalid value (e.g. attempting to delete a department that still has users).\n- `3` β **NothingToDo**: The request produced no change.\n- `4` β **NotPermitted**: The caller is not permitted to perform this operation.",
"format": "int32"
},
"errorMessage": {
"type": "string",
"nullable": true
}
},
"additionalProperties": false,
"description": "Represents an error response for department operations."
},
"Timetastic.Web.ApiResourceModels.DepartmentResponse": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"format": "int32"
}
},
"additionalProperties": false,
"description": "Represents the API response containing the identifier of a created department."
},
"Timetastic.Web.ApiResourceModels.EditUserError": {
"type": "object",
"properties": {
"errorStatus": {
"enum": [
2,
6,
8
],
"type": "integer",
"description": "Why the user could not be edited.\r\n\r\n- `2` β **Failed**: The edit was rejected; errorMessage says why. Common causes are: the user is archived and must be unarchived first, the email address is already in use, removing the last remaining administrator, un-admining yourself, clearing the email address of a user who needs one, making a user both an admin and a director, setting admin or director on a user with no email address, and a start date outside the current or next leave year.\n- `6` β **NotPermitted**: Returned with a 401. The user ID does not exist or belongs to another organisation, or you tried to set a Pro-only field without a Timetastic Pro account.\n- `8` β **InvalidEmail**: The email address failed format validation.",
"format": "int32"
},
"errorMessage": {
"type": "string",
"description": "A human readable description of what went wrong.",
"nullable": true
}
},
"additionalProperties": false,
"description": "Returned when a request to edit a user is rejected."
},
"Timetastic.Web.ApiResourceModels.EditUserRateLimitedError": {
"type": "object",
"properties": {
"errorStatus": {
"enum": [
11
],
"type": "integer",
"description": "Always `11`.\r\n\r\n- `11` β **RateLimited**: Your organisation has supplied an email address that was already in use 10 times, so adding and editing users are both blocked until 24 hours after the first of those failures.",
"format": "int32"
},
"errorMessage": {
"type": "string",
"description": "A human readable description of what went wrong.",
"nullable": true
}
},
"additionalProperties": false,
"description": "Returned when editing a user is blocked because your organisation has supplied an email address\r\nthat was already in use too many times."
},
"Timetastic.Web.ApiResourceModels.HolidayActionResult": {
"type": "object",
"properties": {
"approvalResult": {
"enum": [
"Success",
"AlreadyActioned",
"DoesntExist",
"UnknownError",
"NotAllowed"
],
"type": "string",
"description": "- `Success`\n- `AlreadyActioned`\n- `DoesntExist`\n- `UnknownError`\n- `NotAllowed`"
},
"message": {
"type": "string",
"nullable": true
}
},
"additionalProperties": false,
"description": "Contains the results of updating a holiday request"
},
"Timetastic.Web.ApiResourceModels.HolidayBookResult": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"description": "Whether the booking request was successfull or not"
},
"response": {
"type": "string",
"description": "A response message from the booking request",
"nullable": true
},
"rejections": {
"type": "boolean",
"description": "Whether there were any rejections with the booking, if it was against a department"
},
"autoApproved": {
"type": "boolean",
"description": "Whether the request was automatically approved or not"
},
"holidayId": {
"type": "integer",
"description": "The ID of the newly created holiday",
"format": "int32"
},
"overrideRequired": {
"type": "boolean",
"description": "Whether the holiday can be force-added (as in bypassing the max off limit)"
},
"overrideLockedDateRequired": {
"type": "boolean",
"description": "Whether the holiday can be force-added (overriding any locked dates)"
},
"overrideAccruedAllowanceRequired": {
"type": "boolean",
"description": "Whether the holiday can be force-added (as in bypassing the accrued allowance)"
}
},
"additionalProperties": false,
"description": "Contains the results of a holiday book operation"
},
"Timetastic.Web.ApiResourceModels.Icon": {
"type": "object",
"properties": {
"value": {
"type": "string",
"nullable": true
}
},
"additionalProperties": false
},
"Timetastic.Web.ApiResourceModels.LeaveAllowance": {
"type": "object",
"properties": {
"year": {
"type": "integer",
"description": "The year (taking into account the organisation start date)",
"format": "int32"
},
"allowance": {
"type": "number",
"description": "The starting allowance, including any days in lieu",
"format": "double"
},
"remaining": {
"type": "number",
"description": "The remaining amount",
"format": "double"
},
"used": {
"type": "number",
"description": "The used amount",
"format": "double"
}
},
"additionalProperties": false,
"description": "An allowance breakdown for a year"
},
"Timetastic.Web.ApiResourceModels.LeaveTypeError": {
"type": "object",
"properties": {
"errorStatus": {
"type": "string",
"nullable": true
},
"errorMessage": {
"type": "string",
"nullable": true
}
},
"additionalProperties": false
},
"Timetastic.Web.ApiResourceModels.LeaveTypeRequest": {
"required": [
"name"
],
"type": "object",
"properties": {
"name": {
"maxLength": 50,
"minLength": 1,
"type": "string"
},
"deducted": {
"type": "boolean"
},
"requiresApproval": {
"type": "boolean"
},
"includeMaxOff": {
"type": "boolean"
},
"isPrivate": {
"type": "boolean"
},
"color": {
"type": "string",
"nullable": true
},
"icon": {
"type": "string",
"nullable": true
},
"calendarVisibility": {
"enum": [
1,
2,
3
],
"type": "integer",
"description": "- `1` β **Busy**\n- `2` β **Available**\n- `3` β **OutOfOffice**",
"format": "int32"
},
"limitHours": {
"type": "number",
"format": "double",
"nullable": true
},
"limitDays": {
"type": "number",
"format": "double",
"nullable": true
}
},
"additionalProperties": false
},
"Timetastic.Web.ApiResourceModels.LeaveTypeResponse": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"format": "int32"
},
"name": {
"type": "string",
"nullable": true
},
"organisationId": {
"type": "integer",
"format": "int32"
},
"deducted": {
"type": "boolean",
"description": "Does this leave type deduct from your allowance"
},
"requiresApproval": {
"type": "boolean",
"description": "Does this leave type require approval, or it is automatically approved"
},
"includeMaxOff": {
"type": "boolean",
"description": "Is this leave type considered in maximum absent restrictions"
},
"isPrivate": {
"type": "boolean",
"description": "Is this leave type private"
},
"active": {
"type": "boolean",
"description": "Is this leave type active?"
},
"isInUse": {
"type": "boolean",
"description": "Is this leave type in use for holiday bookings"
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"updatedAt": {
"type": "string",
"format": "date-time"
},
"color": {
"type": "string",
"description": "The assigned colour for this leave type",
"nullable": true
},
"icon": {
"type": "string",
"description": "The assigned icon for this leave type",
"nullable": true
},
"calendarVisibility": {
"enum": [
1,
2,
3
],
"type": "integer",
"description": "Whether this leave type is set to \"Busy\" or \"Available\" on external calendars\r\n\r\n- `1` β **Busy**\n- `2` β **Available**\n- `3` β **OutOfOffice**",
"format": "int32"
},
"limitHours": {
"type": "number",
"description": "The limit in hours for this leave type",
"format": "double",
"nullable": true
},
"limitDays": {
"type": "number",
"description": "The limit in days for this leave type",
"format": "double",
"nullable": true
}
},
"additionalProperties": false,
"description": "A representation of a leave type"
},
"Timetastic.Web.ApiResourceModels.LockedDateError": {
"type": "object",
"properties": {
"errorStatus": {
"enum": [
0,
1,
2,
3,
4,
5,
6
],
"type": "integer",
"description": "- `0` β **Succeeded**\n- `1` β **SucceededOverHolidays**\n- `2` β **Failed**\n- `3` β **InvalidValue**\n- `4` β **NothingToDo**\n- `5` β **NotPermitted**\n- `6` β **DatesAlreadyLocked**",
"format": "int32"
},
"errorMessage": {
"type": "string",
"nullable": true
}
},
"additionalProperties": false
},
"Timetastic.Web.ApiResourceModels.PublicHoliday": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"description": "The unique Id for this public holiday",
"format": "int32"
},
"name": {
"type": "string",
"description": "The name of the holiday",
"nullable": true
},
"date": {
"type": "string",
"description": "The public holiday date",
"format": "date-time"
},
"formattedDate": {
"type": "string",
"description": "A formatted string representation of the public holiday date",
"nullable": true
},
"createdAt": {
"type": "string",
"description": "When the public holiday was created",
"format": "date-time"
},
"updatedAt": {
"type": "string",
"description": "When the public holiday was last updated",
"format": "date-time"
},
"countryCode": {
"type": "string",
"description": "The country code associated with this public holiday",
"nullable": true
},
"bankHolidaySetId": {
"type": "integer",
"description": "The \"set\" (group of public holidays) that this public holiday belongs to",
"format": "int32"
},
"bankHolidaySetName": {
"type": "string",
"description": "The name of the country and region for this bank holiday set. If a custom set, the name of the set.",
"nullable": true
}
},
"additionalProperties": false,
"description": "A representation of a public holiday"
},
"Timetastic.Web.ApiResourceModels.User": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"description": "The unique Id for this user",
"format": "int32"
},
"firstname": {
"type": "string",
"description": "The user's first name",
"nullable": true
},
"surname": {
"type": "string",
"description": "The user's surname",
"nullable": true
},
"email": {
"type": "string",
"description": "The user's email",
"nullable": true
},
"admin": {
"type": "boolean",
"description": "Whether this user is an admin"
},
"director": {
"type": "boolean",
"description": "Whether this user is set as a Director"
},
"accountOwner": {
"type": "boolean",
"description": "Whether this user is an Account Owner"
},
"organisationId": {
"type": "integer",
"description": "The organisation Id of this user",
"format": "int32"
},
"departmentId": {
"type": "integer",
"description": "The department Id of this user",
"format": "int32"
},
"allowanceUnit": {
"enum": [
"Days",
"Hours"
],
"type": "string",
"description": "The allowance unit for the user - Days or Hours\r\n\r\n- `Days`\n- `Hours`"
},
"managerOfDepartments": {
"type": "array",
"items": {
"type": "integer",
"format": "int32"
},
"description": "A comma-separated list of department ids that this user is a manager of",
"nullable": true
},
"bossOfDepartments": {
"type": "array",
"items": {
"type": "integer",
"format": "int32"
},
"nullable": true,
"deprecated": true
},
"endDate": {
"type": "string",
"description": "If set, the date that the user was archived",
"format": "date-time",
"nullable": true
},
"departmentName": {
"type": "string",
"description": "The name of the department this user belongs to",
"nullable": true
},
"gravatar": {
"type": "string",
"description": "The URL of the avatar/gravatar resource for this user",
"nullable": true
},
"allowanceRemaining": {
"type": "number",
"description": "The allowance remaining for this user, for the current year",
"format": "double"
},
"hasLoggedOn": {
"type": "boolean",
"description": "Whether this user has logged on"
},
"isArchived": {
"type": "boolean",
"description": "Whether this user is archived"
},
"approverId": {
"type": "integer",
"description": "If the user has a specific approver set, this is the Id of that user",
"format": "int32"
},
"isApprover": {
"type": "boolean"
},
"deptManagerId": {
"type": "integer",
"description": "The Id of the user who is the manager of the department this user belongs to",
"format": "int32"
},
"deptBossId": {
"type": "integer",
"description": "We no longer use the word Boss - this parameter may be removed in future, use deptManagerId",
"format": "int32",
"deprecated": true
},
"birthday": {
"type": "string",
"description": "The birthday of this user",
"format": "date-time",
"nullable": true
},
"startDate": {
"type": "string",
"description": "The start date for this user",
"format": "date-time",
"nullable": true
},
"hasPublicHolidays": {
"type": "boolean",
"description": "If this user has public holidays"
},
"userInitials": {
"type": "string",
"description": "The user initials",
"nullable": true
},
"countryCode": {
"type": "string",
"description": "The country code this user has public holidays for (ZZ if custom location)",
"nullable": true
},
"currentYearAllowance": {
"type": "number",
"description": "The allowance for this user, for the current leave year",
"format": "double"
},
"nextYearAllowance": {
"type": "number",
"description": "The allowance for this user, for the next leave year",
"format": "double"
},
"userLinkedWithGoogle": {
"type": "boolean"
},
"userManagedExternally": {
"type": "boolean"
},
"mfaEnabled": {
"type": "boolean"
},
"inviteSentTimeUtc": {
"type": "string",
"format": "date-time",
"nullable": true
},
"inviteSentTimeHumanised": {
"type": "string",
"nullable": true
},
"yearStart": {
"type": "integer",
"description": "The month that the user's leave year starts (1 being January to 12 being December)",
"format": "int32"
},
"accrualSystem": {
"type": "boolean"
},
"isEmailConfirmed": {
"type": "boolean"
}
},
"additionalProperties": false,
"description": "A representation of a user. For more details about the user (working time, and allowances), get a user by id."
},
"Timetastic.Web.ApiResourceModels.UserDetail": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"description": "The unique Id for this user",
"format": "int32"
},
"firstname": {
"type": "string",
"description": "The user's first name",
"nullable": true
},
"surname": {
"type": "string",
"description": "The user's surname",
"nullable": true
},
"email": {
"type": "string",
"description": "The user's email",
"nullable": true
},
"admin": {
"type": "boolean",
"description": "Whether this user is an admin"
},
"director": {
"type": "boolean",
"description": "Whether this user is set as a Director"
},
"accountOwner": {
"type": "boolean",
"description": "Whether this user is an Account Owner"
},
"organisationId": {
"type": "integer",
"description": "The organisation Id of this user",
"format": "int32"
},
"departmentId": {
"type": "integer",
"description": "The department Id of this user",
"format": "int32"
},
"allowanceUnit": {
"enum": [
"Days",
"Hours"
],
"type": "string",
"description": "The allowance unit for the user - Days or Hours\r\n\r\n- `Days`\n- `Hours`"
},
"managerOfDepartments": {
"type": "array",
"items": {
"type": "integer",
"format": "int32"
},
"description": "A comma-separated list of department ids that this user is a manager of",
"nullable": true
},
"bossOfDepartments": {
"type": "array",
"items": {
"type": "integer",
"format": "int32"
},
"nullable": true,
"deprecated": true
},
"endDate": {
"type": "string",
"description": "If set, the date that the user was archived",
"format": "date-time",
"nullable": true
},
"departmentName": {
"type": "string",
"description": "The name of the department this user belongs to",
"nullable": true
},
"gravatar": {
"type": "string",
"description": "The URL of the avatar/gravatar resource for this user",
"nullable": true
},
"allowanceRemaining": {
"type": "number",
"description": "The allowance remaining for this user, for the current year",
"format": "double"
},
"hasLoggedOn": {
"type": "boolean",
"description": "Whether this user has logged on"
},
"isArchived": {
"type": "boolean",
"description": "Whether this user is archived"
},
"approverId": {
"type": "integer",
"description": "If the user has a specific approver set, this is the Id of that user",
"format": "int32"
},
"isApprover": {
"type": "boolean"
},
"deptManagerId": {
"type": "integer",
"description": "The Id of the user who is the manager of the department this user belongs to",
"format": "int32"
},
"deptBossId": {
"type": "integer",
"description": "We no longer use the word Boss - this parameter may be removed in future, use deptManagerId",
"format": "int32",
"deprecated": true
},
"birthday": {
"type": "string",
"description": "The birthday of this user",
"format": "date-time",
"nullable": true
},
"startDate": {
"type": "string",
"description": "The start date for this user",
"format": "date-time",
"nullable": true
},
"hasPublicHolidays": {
"type": "boolean",
"description": "If this user has public holidays"
},
"userInitials": {
"type": "string",
"description": "The user initials",
"nullable": true
},
"countryCode": {
"type": "string",
"description": "The country code this user has public holidays for (ZZ if custom location)",
"nullable": true
},
"currentYearAllowance": {
"type": "number",
"description": "The allowance for this user, for the current leave year",
"format": "double"
},
"nextYearAllowance": {
"type": "number",
"description": "The allowance for this user, for the next leave year",
"format": "double"
},
"userLinkedWithGoogle": {
"type": "boolean"
},
"userManagedExternally": {
"type": "boolean"
},
"mfaEnabled": {
"type": "boolean"
},
"inviteSentTimeUtc": {
"type": "string",
"format": "date-time",
"nullable": true
},
"inviteSentTimeHumanised": {
"type": "string",
"nullable": true
},
"yearStart": {
"type": "integer",
"description": "The month that the user's leave year starts (1 being January to 12 being December)",
"format": "int32"
},
"accrualSystem": {
"type": "boolean"
},
"isEmailConfirmed": {
"type": "boolean"
},
"workingDays": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Timetastic.Web.ApiResourceModels.WorkingDay"
},
"description": "This is maintained for backwards compatibility, and now lists the working\r\ndays for the current schedule.",
"nullable": true
},
"workSchedules": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Timetastic.Web.ApiResourceModels.WorkSchedule"
},
"nullable": true
},
"allowances": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Timetastic.Web.ApiResourceModels.LeaveAllowance"
},
"nullable": true
}
},
"additionalProperties": false
},
"Timetastic.Web.ApiResourceModels.UserError": {
"type": "object",
"properties": {
"errorStatus": {
"enum": [
1
],
"type": "integer",
"description": "Why the request failed.\r\n\r\n- `1` β **Failed**: The request was rejected. When archiving: the user does not exist, belongs to another organisation, or is already archived, or the archive date is missing or out of range. When restoring: the user does not exist, belongs to another organisation, or is already active.",
"format": "int32"
},
"errorMessage": {
"type": "string",
"description": "A human readable description of what went wrong.",
"nullable": true
}
},
"additionalProperties": false,
"description": "Returned when a request to archive or restore a user is rejected."
},
"Timetastic.Web.ApiResourceModels.UserWithContact": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"description": "The unique Id for this user",
"format": "int32"
},
"firstname": {
"type": "string",
"description": "The user's first name",
"nullable": true
},
"surname": {
"type": "string",
"description": "The user's surname",
"nullable": true
},
"email": {
"type": "string",
"description": "The user's email",
"nullable": true
},
"admin": {
"type": "boolean",
"description": "Whether this user is an admin"
},
"director": {
"type": "boolean",
"description": "Whether this user is set as a Director"
},
"accountOwner": {
"type": "boolean",
"description": "Whether this user is an Account Owner"
},
"organisationId": {
"type": "integer",
"description": "The organisation Id of this user",
"format": "int32"
},
"departmentId": {
"type": "integer",
"description": "The department Id of this user",
"format": "int32"
},
"allowanceUnit": {
"enum": [
"Days",
"Hours"
],
"type": "string",
"description": "The allowance unit for the user - Days or Hours\r\n\r\n- `Days`\n- `Hours`"
},
"managerOfDepartments": {
"type": "array",
"items": {
"type": "integer",
"format": "int32"
},
"description": "A comma-separated list of department ids that this user is a manager of",
"nullable": true
},
"bossOfDepartments": {
"type": "array",
"items": {
"type": "integer",
"format": "int32"
},
"nullable": true,
"deprecated": true
},
"endDate": {
"type": "string",
"description": "If set, the date that the user was archived",
"format": "date-time",
"nullable": true
},
"departmentName": {
"type": "string",
"description": "The name of the department this user belongs to",
"nullable": true
},
"gravatar": {
"type": "string",
"description": "The URL of the avatar/gravatar resource for this user",
"nullable": true
},
"allowanceRemaining": {
"type": "number",
"description": "The allowance remaining for this user, for the current year",
"format": "double"
},
"hasLoggedOn": {
"type": "boolean",
"description": "Whether this user has logged on"
},
"isArchived": {
"type": "boolean",
"description": "Whether this user is archived"
},
"approverId": {
"type": "integer",
"description": "If the user has a specific approver set, this is the Id of that user",
"format": "int32"
},
"isApprover": {
"type": "boolean"
},
"deptManagerId": {
"type": "integer",
"description": "The Id of the user who is the manager of the department this user belongs to",
"format": "int32"
},
"deptBossId": {
"type": "integer",
"description": "We no longer use the word Boss - this parameter may be removed in future, use deptManagerId",
"format": "int32",
"deprecated": true
},
"birthday": {
"type": "string",
"description": "The birthday of this user",
"format": "date-time",
"nullable": true
},
"startDate": {
"type": "string",
"description": "The start date for this user",
"format": "date-time",
"nullable": true
},
"hasPublicHolidays": {
"type": "boolean",
"description": "If this user has public holidays"
},
"userInitials": {
"type": "string",
"description": "The user initials",
"nullable": true
},
"countryCode": {
"type": "string",
"description": "The country code this user has public holidays for (ZZ if custom location)",
"nullable": true
},
"currentYearAllowance": {
"type": "number",
"description": "The allowance for this user, for the current leave year",
"format": "double"
},
"nextYearAllowance": {
"type": "number",
"description": "The allowance for this user, for the next leave year",
"format": "double"
},
"userLinkedWithGoogle": {
"type": "boolean"
},
"userManagedExternally": {
"type": "boolean"
},
"mfaEnabled": {
"type": "boolean"
},
"inviteSentTimeUtc": {
"type": "string",
"format": "date-time",
"nullable": true
},
"inviteSentTimeHumanised": {
"type": "string",
"nullable": true
},
"yearStart": {
"type": "integer",
"description": "The month that the user's leave year starts (1 being January to 12 being December)",
"format": "int32"
},
"accrualSystem": {
"type": "boolean"
},
"isEmailConfirmed": {
"type": "boolean"
},
"workingDays": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Timetastic.Web.ApiResourceModels.WorkingDay"
},
"description": "This is maintained for backwards compatibility, and now lists the working\r\ndays for the current schedule.",
"nullable": true
},
"workSchedules": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Timetastic.Web.ApiResourceModels.WorkSchedule"
},
"nullable": true
},
"allowances": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Timetastic.Web.ApiResourceModels.LeaveAllowance"
},
"nullable": true
},
"jobTitle": {
"type": "string",
"description": "The user's job title",
"nullable": true
},
"payrollId": {
"type": "string",
"description": "The user's payroll ID (will be included in reports)",
"nullable": true
},
"address1": {
"type": "string",
"description": "First line of the address",
"nullable": true
},
"address2": {
"type": "string",
"description": "Address line 2",
"nullable": true
},
"city": {
"type": "string",
"description": "Address line 3 / City",
"nullable": true
},
"postCode": {
"type": "string",
"description": "Address line 4 / PostCode",
"nullable": true
},
"telephone1": {
"type": "string",
"description": "Primary contact number",
"nullable": true
},
"telephone2": {
"type": "string",
"description": "Secondary contact number",
"nullable": true
},
"country": {
"type": "string",
"description": "String: ALPHA-2 country code",
"nullable": true
},
"emergencyContactName": {
"type": "string",
"description": "Name of emergency contact",
"nullable": true
},
"emergencyContactPhone": {
"type": "string",
"description": "Contact number of emergency contact",
"nullable": true
}
},
"additionalProperties": false
},
"Timetastic.Web.ApiResourceModels.WorkSchedule": {
"type": "object",
"properties": {
"start": {
"type": "string",
"format": "date-time"
},
"days": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Timetastic.Web.ApiResourceModels.WorkingDay"
},
"nullable": true
}
},
"additionalProperties": false
},
"Timetastic.Web.ApiResourceModels.WorkingDay": {
"type": "object",
"properties": {
"dayOfWeek": {
"enum": [
"Sunday",
"Monday",
"Tuesday",
"Wednesday",
"Thursday",
"Friday",
"Saturday"
],
"type": "string",
"description": "- `Sunday`\n- `Monday`\n- `Tuesday`\n- `Wednesday`\n- `Thursday`\n- `Friday`\n- `Saturday`"
},
"fromTimeAm": {
"type": "integer",
"description": "The AM from time, expressed as minutes since midnight",
"format": "int32"
},
"toTimeAm": {
"type": "integer",
"description": "The AM to time, expressed as minutes since midnight",
"format": "int32"
},
"fromTimePm": {
"type": "integer",
"description": "The PM from time, expressed as minutes since midnight",
"format": "int32"
},
"toTimePm": {
"type": "integer",
"description": "The PM to time, expressed as minutes since midnight",
"format": "int32"
},
"workingAm": {
"type": "boolean",
"description": "Whether the user is working AM"
},
"workingPm": {
"type": "boolean",
"description": "Whether the user is working PM"
}
},
"additionalProperties": false,
"description": "Working Day details for the user."
},
"Timetastic.Web.Controllers.API.UserAllowanceController+AmountRequest": {
"required": [
"amount"
],
"type": "object",
"properties": {
"amount": {
"maximum": 8784,
"minimum": 0,
"type": "number",
"format": "double"
}
},
"additionalProperties": false
},
"Timetastic.Web.Controllers.API.UserAllowanceController+CarryForwardRequest": {
"required": [
"amount"
],
"type": "object",
"properties": {
"amount": {
"maximum": 5000,
"minimum": 0,
"type": "number",
"format": "double"
}
},
"additionalProperties": false
},
"Timetastic.Web.Controllers.API.UserAllowanceController+UpsertToilRequest": {
"required": [
"amount"
],
"type": "object",
"properties": {
"amount": {
"maximum": 5000,
"minimum": -5000,
"type": "number",
"format": "double"
},
"description": {
"maxLength": 1000,
"minLength": 0,
"type": "string",
"nullable": true
}
},
"additionalProperties": false
},
"Timetastic.Web.ViewModels.Settings.DepartmentSetting": {
"required": [
"managerId",
"name"
],
"type": "object",
"properties": {
"name": {
"minLength": 1,
"type": "string",
"description": "The Department name"
},
"managerId": {
"type": "integer",
"description": "The userId of the Manager for this department",
"format": "int32"
},
"maxOff": {
"type": "integer",
"description": "The maximum absent setting for this department",
"format": "int32"
}
},
"additionalProperties": false
}
},
"securitySchemes": {
"Bearer": {
"type": "http",
"description": "Organisation API token: `Authorization: Bearer `",
"scheme": "bearer"
},
"AgendrixHmac": {
"type": "apiKey",
"description": "HMAC-SHA256 signature: `appkey:signature:nonce:timestamp`",
"name": "X-AGX-Authentication",
"in": "header"
}
}
},
"tags": [
{
"name": "Absences",
"description": "Get upcoming absences; Bookings, non working days, public holidays or other Timetastic Events like Locked Dates, Birthdays or Work Anniversaries\r\n \r\nUse this endpoint if you're updating your own dashboard, internal calendar or 3rd party app and only want to know what's coming up soon without querying multiple endpoints in our API"
},
{
"name": "Departments",
"description": "Access all the departments at your organisation."
},
{
"name": "Holidays",
"description": "View, book, or action holidays at your organisation.\r\n \r\nUsing the ```holidays``` endpoint, you can query for all types of leave bookings in Timetastic.\r\nYou can also use this endpoint to update (approve or decline) holidays and to request new time off.\r\n \r\nNote: **Holidays** in the context of this API actually refer to any absence.\r\nWe apologize for any confusion, but the API was first built in 2014 and to update the endpoints would risk a large amount of breaking changes."
},
{
"name": "LeaveTypes",
"description": "Access all the leave types in your organisation"
},
{
"name": "LockedDates",
"description": "Manage locked dates (date periods where employees cannot book time off)."
},
{
"name": "PublicHolidays",
"description": "Access all the public holidays at your organisation."
},
{
"name": "Allowances",
"description": "Access and manage user allowance information."
}
]
}