Vacation Tracker Docs
REST API v2API referenceScheduled reports

Create a scheduled report

This API method creates a report that is emailed to `receivers` every month. Requires `notifications:write`. The acting user is the key owner, or the `X-On-Behalf-Of` user, and becomes the report's creator (`creatorId`). It must be an admin, or a location admin who manages every location in `locationIds`; a location admin must send at least one location. It waits for the report to be created and returns it with `201`, or `202 Accepted` with an operation to poll. - `name`, `reportType`, `receivers` (at least one email address), `timezone`, `sendDayOfMonth`, `sendHourUtc` and `sendMinuteUtc` are required. - `sendHourUtc` and `sendMinuteUtc` are in **UTC**, not in `timezone`; convert local times yourself. `timezone` is used for the dates in the report. - `period` defaults to `LAST_MONTH`, its only value. - `leaveStatus` lists the leave statuses a `leaveHistoryReport` includes: `APPROVED`, `DENIED`, `EXPIRED` and `CANCELLED`. - `locationIds`, `departmentIds` and `labelIds` default to empty arrays, which means everyone. - `name` fails validation when it looks like HTML or script; unknown fields fail validation. Errors: `400 VALIDATION_ERROR` (`details.fields`), `400 INVALID_REQUEST_BODY`, `403 SCHEDULED_REPORTS_NOT_AVAILABLE`, `403 ON_BEHALF_OF_NOT_ALLOWED`, `403 FORBIDDEN` (the acting user is neither an admin nor a location admin, or `locationIds` is empty or includes a location they do not manage), and the `Idempotency-Key` codes.

POST
/v2/scheduled-reports

Authorization

bearerAuth notifications:write
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: notifications:write

Header Parameters

Idempotency-Key?string

optional key (1 to 255 printable ASCII characters) that makes a write request safe to retry. Keys are retained for 24 hours per API key. Retrying with the same key and the same request within those 24 hours replays the original response (with the Idempotent-Replayed header). Reusing the key with a different request returns 422 IDEMPOTENCY_KEY_REUSED; retrying while the first request is still running returns 409 IDEMPOTENCY_REQUEST_IN_PROGRESS; an invalid key returns 400 INVALID_IDEMPOTENCY_KEY.

Length1 <= length <= 255
X-On-Behalf-Of?string

ID of the user the write is performed for. Requires the users:act-on-behalf scope, and the key owner must manage the target user; otherwise the request fails with 403 ON_BEHALF_OF_NOT_ALLOWED. Ignored on GET requests.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/v2/scheduled-reports" \  -H "Content-Type: application/json" \  -d '{    "name": "Monthly balances",    "reportType": "leaveBalanceReport",    "receivers": [      "hr@chaochao.com"    ],    "timezone": "Europe/Belgrade",    "sendDayOfMonth": 1,    "sendHourUtc": 7,    "sendMinuteUtc": 30  }'
{
  "data": {
    "id": "scheduledReport-8a47c61e-2b7f-4d5e-9c61-3f1c2b9e1d93",
    "name": "Monthly balances",
    "reportType": "leaveBalanceReport",
    "period": "LAST_MONTH",
    "locationIds": [],
    "departmentIds": [],
    "labelIds": [],
    "receivers": [
      "hr@chaochao.com"
    ],
    "timezone": "Europe/Belgrade",
    "sendDayOfMonth": 1,
    "sendHourUtc": 7,
    "sendMinuteUtc": 30,
    "creatorId": "user-63b17e97-d38b-4586-8498-bb4f5d2e2c14"
  }
}
{
  "operation": {
    "id": "pa_3f1c2b9e-8a47-4d5e-9c61-2b7f0e4a1d93",
    "status": "PENDING",
    "url": "/v2/operations/pa_3f1c2b9e-8a47-4d5e-9c61-2b7f0e4a1d93"
  }
}
{
  "error": {
    "code": "VALIDATION_ERROR",
    "name": "ValidationError",
    "description": "A query parameter, body field or header failed validation.",
    "resolution": "Fix the fields listed in details.fields and send the request again.",
    "requestId": "c6af9ac6-7b61-11e6-9a41-93e8deadbeef",
    "details": {
      "fields": [
        {
          "path": "startDate",
          "message": "\"startDate\" is required"
        }
      ]
    }
  }
}
{
  "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": "CONFLICT",
    "name": "Conflict",
    "description": "The request conflicts with the current state of the resource.",
    "resolution": "Read the resource again and retry with up-to-date values.",
    "requestId": "c6af9ac6-7b61-11e6-9a41-93e8deadbeef"
  }
}

{
  "error": {
    "code": "LEAVE_NEGATIVE_BALANCE",
    "name": "LeaveNegativeBalance",
    "description": "The user does not have enough balance for this leave.",
    "resolution": "Shorten the leave, use a different leave type, or ask an admin to adjust the quota.",
    "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

List scheduled reports

This API method returns the scheduled reports the key can see, in one response without pagination. Requires `notifications:read`. Admins see every scheduled report; location admins see only the reports whose `locationIds` is not empty and lists only locations they manage. A key owner who is neither an admin nor a location admin fails with `403 FORBIDDEN`. Scheduled reports need the Complete plan. On any other plan every scheduled-report operation fails with `403 SCHEDULED_REPORTS_NOT_AVAILABLE`.

Get a scheduled report

This API method returns a single scheduled report. Requires `notifications:read`. Errors: `403 SCHEDULED_REPORTS_NOT_AVAILABLE` (the company is not on the Complete plan), `403 FORBIDDEN` (the key owner is neither an admin nor a location admin), and `404 RESOURCE_NOT_FOUND` (the report does not exist, or the key owner is a location admin and the report has no locations or includes a location they do not manage).