Vacation Tracker Docs
REST API v2API referenceNotifications

Get a notification

This API method returns a single notification, with the fields of its `frequency`. Requires `notifications:read`. Errors: `404 RESOURCE_NOT_FOUND` (the notification does not exist, or it is owned by another user and the key owner is not an admin).

GET
/v2/notifications/{id}

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

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/notifications/string"

{
  "data": {
    "id": "notification-2b7f0e4a-1d93-4c61-8a47-3f1c2b9e4d5e",
    "name": "Daily team summary",
    "frequency": "DAILY",
    "enabled": true,
    "ownerId": "user-63b17e97-d38b-4586-8498-bb4f5d2e2c14",
    "timezone": "Europe/Belgrade",
    "hour": 9,
    "minute": 0,
    "locale": "en",
    "locationIds": [],
    "departmentIds": [],
    "labelIds": [],
    "destinations": [
      {
        "platform": "slack",
        "addresses": [
          "C04ABCDEF12"
        ],
        "channelName": "general"
      }
    ],
    "sendOnDays": [
      1,
      2,
      3,
      4,
      5
    ],
    "groupBy": "TEAM",
    "sendEmpty": false
  }
}

{
  "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 notification

This API method creates a notification. Requires `notifications:write`. The acting user is the key owner, or the `X-On-Behalf-Of` user; it must be an approver or an admin, and becomes the notification's owner (`ownerId`). It waits for the notification to be created and returns it with `201`, or `202 Accepted` with an operation to poll. `frequency` selects the kind, and `CreateNotificationRequest` lists one request schema per frequency: - `DAILY` sends a summary of who is off on the days in `sendOnDays`; it needs `groupBy` and `sendEmpty`. - `WEEKLY` sends a summary of the current or the next week on `day`; it needs `firstDayOfWeek`, `day`, `currentWeek`, `groupBy` and `sendEmpty`. - `BIRTHDAY` announces birthdays; it needs `sendOnNonWorkingDays`, and each `microsoft` or `slack` destination needs a `channelName`. Every kind needs `name`, `timezone`, `hour`, `minute` and at least one destination: - `hour` and `minute` are local to `timezone`; they are not converted to UTC. - `locale` defaults to `en`. `locationIds`, `departmentIds` and `labelIds` default to empty arrays, which means everyone. - `enabled` defaults to `true`. A `DAILY` or `WEEKLY` notification can only be created enabled; sending `enabled: false` fails validation. - An `email` destination takes one or more email addresses in `addresses`; a `microsoft` or `slack` destination takes exactly one channel ID. `msGroup` is accepted only for `microsoft`, and `channelName` is not accepted for `email`. - `name` fails validation when it looks like HTML or script. Fields of another frequency and unknown fields fail validation. Errors: `400 VALIDATION_ERROR` (`details.fields`), `400 INVALID_REQUEST_BODY`, `403 ON_BEHALF_OF_NOT_ALLOWED`, `403 FORBIDDEN` (the acting user may not create notifications), and the `Idempotency-Key` codes.

Update a notification

This API method changes a notification. Requires `notifications:write`. The acting user is the key owner, or the `X-On-Behalf-Of` user. It waits for the change and returns the notification with `200`, or `202 Accepted` with an operation to poll. Send only the fields you want to change; at least one field is required. Your changes are merged with the notification's current values and the result is validated like a create for its frequency, so everything you do not send is kept: - `enabled: false` pauses the notification and `enabled: true` resumes it. - `frequency` can switch between `DAILY` and `WEEKLY` (send the fields the new frequency needs), but a notification can never switch to or from `BIRTHDAY`: that fails with `400 NOTIFICATION_FREQUENCY_CHANGE_NOT_ALLOWED`. Fields that do not belong to the resulting frequency are ignored. - `destinations`, `locationIds`, `departmentIds`, `labelIds` and `sendOnDays`, when sent, **replace** the current list. - `hour` and `minute` are local to `timezone`. An acting user who is not an admin can change only the notifications they own; other notifications return `404 RESOURCE_NOT_FOUND`. Errors: `400 VALIDATION_ERROR` (`details.fields`), `400 NOTIFICATION_FREQUENCY_CHANGE_NOT_ALLOWED`, `400 INVALID_REQUEST_BODY`, `403 ON_BEHALF_OF_NOT_ALLOWED`, `404 RESOURCE_NOT_FOUND`, and the `Idempotency-Key` codes.