Vacation Tracker Docs
REST API v2API referenceScheduled reports

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
/v2/scheduled-reports

Authorization

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

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v2/scheduled-reports"
{
  "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"
    },
    {
      "id": "scheduledReport-1d93c61e-8a47-4b7f-9d5e-2b7f3f1c2b9e",
      "name": "Los Angeles leave history",
      "reportType": "leaveHistoryReport",
      "period": "LAST_MONTH",
      "locationIds": [
        "location-79c77ac8-e5bf-479f-9488-648a58379ff1"
      ],
      "departmentIds": [],
      "labelIds": [],
      "receivers": [
        "la-office@chaochao.com"
      ],
      "timezone": "America/Los_Angeles",
      "sendDayOfMonth": 2,
      "sendHourUtc": 16,
      "sendMinuteUtc": 0,
      "leaveStatus": [
        "APPROVED",
        "DENIED"
      ],
      "creatorId": "user-63b17e97-d38b-4586-8498-bb4f5d2e2c14"
    }
  ]
}
{
  "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": "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

Delete a notification

This API method deletes a notification of any frequency. Requires `notifications:write`. No request body. The acting user is the key owner, or the `X-On-Behalf-Of` user. It waits for the deletion and returns `204`, or `202 Accepted` with an operation to poll. An acting user who is not an admin can delete only the notifications they own. Errors: `403 ON_BEHALF_OF_NOT_ALLOWED`, `404 RESOURCE_NOT_FOUND` (the notification does not exist, or it is owned by another user and the acting user is not an admin), and the `Idempotency-Key` codes.

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.