Vacation Tracker Docs
REST API v2API referenceDepartments

Get a department

This API method returns a single department with its ID, name, default flag and creation time. Requires `departments:read`. Errors: `404 RESOURCE_NOT_FOUND` (the department does not exist or is outside the key's data reach).

GET
/v2/departments/{id}

Authorization

bearerAuth departments:read
AuthorizationBearer <token>

API key sent as Authorization: Bearer vt_live_<secret>. See the Authentication and Scopes sections at the top of this document for how keys are created, which scopes exist and how the key owner's role limits them.

In: header

Scope: departments:read

Path Parameters

id*string

resource ID.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v2/departments/string"
{
  "data": {
    "id": "team-0a21c25e-6925-4a5b-90ee-ecf82096c4f6",
    "name": "Dev Team",
    "isDefault": false,
    "createdAt": "2022-08-22T15:00:00.000Z"
  }
}
{
  "error": {
    "code": "UNAUTHORIZED",
    "name": "Unauthorized",
    "description": "The API key is missing, malformed or not recognized.",
    "resolution": "Send a valid API key in the Authorization header as Bearer followed by the full vt_live_ key.",
    "requestId": "c6af9ac6-7b61-11e6-9a41-93e8deadbeef"
  }
}

{
  "error": {
    "code": "INSUFFICIENT_SCOPE",
    "name": "InsufficientScope",
    "description": "The API key does not have the scopes this request needs.",
    "resolution": "Add the scopes listed in details.requiredScopes to the key in the Vacation Tracker dashboard.",
    "requestId": "c6af9ac6-7b61-11e6-9a41-93e8deadbeef",
    "details": {
      "requiredScopes": [
        "leaves:write"
      ]
    }
  }
}

{
  "error": {
    "code": "RESOURCE_NOT_FOUND",
    "name": "ResourceNotFound",
    "description": "The requested resource does not exist or is outside the data this key can access.",
    "resolution": "Check the ID of the resource named in details.resource and that the key owner can see it.",
    "requestId": "c6af9ac6-7b61-11e6-9a41-93e8deadbeef"
  }
}
{
  "error": {
    "code": "RATE_LIMITED",
    "name": "RateLimited",
    "description": "Too many requests were sent in a short time.",
    "resolution": "Wait a few seconds and retry, using the same Idempotency-Key for writes.",
    "requestId": "c6af9ac6-7b61-11e6-9a41-93e8deadbeef"
  }
}
{
  "error": {
    "code": "INTERNAL_ERROR",
    "name": "InternalError",
    "description": "Something went wrong on our side.",
    "resolution": "Retry later, and if it keeps happening, contact Vacation Tracker support and quote the requestId.",
    "requestId": "c6af9ac6-7b61-11e6-9a41-93e8deadbeef"
  }
}

Need help?

developers@vacationtracker.io

Create a department

This API method creates a department. Requires `departments:write`. The acting user is the key owner, or the `X-On-Behalf-Of` user. It waits for the department to be created and returns it, with its parent and approvers, with `201`; if that takes longer than the wait window it returns `202 Accepted` with an operation to poll. - `name` and at least one entry in `approvers` are required. Each approver's `levels` defaults to `["FIRST"]`; `SECOND` needs a plan with multi-level approval. - `userIds` moves those users into the new department and defaults to an empty array. `isDefault` defaults to `false`; `true` makes this the company's default department. - `parentId` makes this a sub-department; omit it for a top-level department. - Unknown fields and values of the wrong type fail validation. Errors: `400 VALIDATION_ERROR` (`details.fields`), `400 INVALID_REQUEST_BODY`, `403 ON_BEHALF_OF_NOT_ALLOWED`, `403 FORBIDDEN`, `403 FEATURE_NOT_IN_PLAN` (a `SECOND` approval level without multi-level approval in the plan), `409 DUPLICATE_NAME` (another department already uses the name), `422 UNKNOWN_USER_IDS` (`userIds` or `approvers` name users who are not active users of the company), `422 PLAN_LIMIT_REACHED`, and the `Idempotency-Key` codes.

Update a department

This API method changes a department. Requires `departments:write`. The acting user is the key owner, or the `X-On-Behalf-Of` user. It waits for the change and returns the department, with its parent and approvers, with `200`, or `202 Accepted` with an operation to poll. Send only the fields you want to change. Your changes are merged with the department's current state, members and approvers, so everything you do not send is kept: - `userIds`, when sent, **replaces the full membership**. Any user currently in this department whose ID is missing from the list is moved to the company's default department. - `approvers`, when sent, **replaces the full approver list**. - `isDefault: false` for the current default department fails with `409 DEFAULT_DEPARTMENT_UNSET_FORBIDDEN`; set another department's `isDefault` to `true` instead. - `parentId` moves the department in the hierarchy; a department cannot become a sub-department of itself or of its own sub-departments. Errors: `400 VALIDATION_ERROR` (`details.fields`), `400 INVALID_REQUEST_BODY`, `403 ON_BEHALF_OF_NOT_ALLOWED`, `403 FORBIDDEN`, `403 FEATURE_NOT_IN_PLAN` (a `SECOND` approval level without multi-level approval in the plan), `404 RESOURCE_NOT_FOUND` (the department does not exist or is outside the key's data reach), `409 DEFAULT_DEPARTMENT_UNSET_FORBIDDEN`, `409 DEPARTMENT_CIRCULAR_PARENT`, `409 DUPLICATE_NAME`, `422 UNKNOWN_USER_IDS`, and the `Idempotency-Key` codes.