BAbamboohr
Alerts
Public API

Get Alert Configuration

Changed on

Returns one alert configuration the company has set up: which alert template it uses, when it runs, who receives it, and any custom subject, message, or list-value filters. The response is a single JSON object with no wrapper.

Use this when the configuration's id is already known, either from List Alert Configurations (list-alert-configurations) or from the body Create Alert Configuration (create-alert-configuration) and Replace Alert Configuration (replace-alert-configuration) return. To enumerate or search a company's configured alerts, use list-alert-configurations instead. For the catalog of alert types that can be configured, rather than what this company has configured, use List Alert Templates (list-alert-templates). The bambooAlertId on the returned object identifies the underlying template, not this configuration, so the two identifiers are not interchangeable.

Access is all-or-nothing rather than per-record. An authenticated caller without view access to the company's Email Alerts settings receives 403 rather than a partially redacted object. Only configurations belonging to the authenticated company are reachable, and an id from any other company is indistinguishable from one that never existed.

OAuth Scopes: alerts

get/api/v1/alert-configurations/{id}

Request

Path parameters

idinteger required

Identifier of the alert configuration to return, as emitted in the id field of List Alert Configurations (list-alert-configurations). This is the configuration's own identifier, not the bambooAlertId of the alert template it is based on. No wildcard or 0 sentinel is supported; enumerate configurations with list-alert-configurations instead.

Response

The requested alert configuration, as a single JSON object.

idinteger

The unique identifier of this alert configuration.

bambooAlertIdinteger

The identifier of the alert template this configuration is based on. Resolve template identifiers to a name and group with List Alert Templates (list-alert-templates), which exposes the same identifier as id.

schedule'daily' | 'weekly' | 'monthly' | 'quarterly'

The schedule for the company alert.

dueWithininteger nullable

How far ahead of the due date the alert fires, counted in units of dueInterval. Only meaningful for alert templates that track a due date.

dueInterval'days' | 'weeks' | 'months' nullable

The unit that dueWithin is counted in.

sendToEmployeeboolean

Whether the alert should be sent to employees.

sendToManagerboolean

Whether the alert should be sent to managers.

sendToAdminboolean

Whether the alert should be sent to admins.

editorUserIdinteger nullable

The user ID of the user who last saved this configuration. Set by the server on create and update; a value supplied in a request body is ignored. Null for configurations that have never been edited.

lastEditedstring date-time nullable

When this configuration was last saved, as a UTC timestamp. Read-only: the server sets it on every create and update, so do not send it in a request body. Null for configurations that have never been edited.

customMessagestring nullable

Custom body text for the alert email. Null means the alert's default body is used. Limited to 1024 bytes; multibyte characters consume more than one byte each.

customSubjectstring nullable

Custom subject line for the alert email. Null means the alert's default subject is used. Limited to 250 bytes; multibyte characters consume more than one byte each.

groupBy'department' | 'division' | 'location' | 'jobTitle' nullable

Groups the recipients of a summary-style alert by this employee attribute. Null means no grouping.

limitTrainingToRequiredboolean

Whether the training should be limited to required training.

runAtTimestring nullable

Time of day the alert is sent, formatted as HH:MM:SS such as 07:00:00. Interpreted in runAtTimeZone.

runAtTimeZonestring nullable

IANA time zone name that runAtTime is evaluated in, such as America/Denver. Null means the company's own time zone is used.

includePositionboolean

Whether the alert should include position.

includeLocationboolean

Whether the alert should include location.

additionalRecipientEmailsstring[]

Never persisted by this API. A GET, both the list and the single-read, always returns an empty array, while a create or replace response echoes back whatever was submitted; that echo does not mean the value was stored.

employeeIdsstring[]

Internal employee IDs. Never persisted by this API: a read always returns an empty array, while a create or replace response echoes back whatever was submitted; that echo does not mean the value was stored.

listValueIdsinteger[]

Never persisted by this API. A GET, both the list and the single-read, always returns an empty array, while a create or replace response echoes back whatever was submitted; that echo does not mean the value was stored. Use filterListValueIds to scope an alert by list value.

filterListValueIdsinteger[]

List value IDs the alert is scoped to, such as specific departments or locations. An empty array means the alert is not scoped by list value.

userIdsinteger[]

Never persisted by this API. A GET, both the list and the single-read, always returns an empty array, while a create or replace response echoes back whatever was submitted; that echo does not mean the value was stored.

Example response

{
  "runAtTime": "07:00:00",
  "runAtTimeZone": "America/Denver"
}

Changes

  • 922fc15f43a7Revision changes
    • breaking

      response property lastEdited list-of-types was widened by adding types string to media type application/json of response 200

    • warning

      added the new days enum value to the / response property for the response status

    • warning

      added the new department enum value to the / response property for the response status

    • warning

      added the new division enum value to the / response property for the response status

    • warning

      added the new jobTitle enum value to the / response property for the response status

    • warning

      added the new location enum value to the / response property for the response status

    • warning

      added the new months enum value to the / response property for the response status

    • warning

      added the new weeks enum value to the / response property for the response status

    • info

      api operation id 14e66bfb5f075043221ce1e843c97493 removed and replaced with get-alert-configuration

    • info

      api tag Alerts added

    • info

      api tag Alert Configurations removed

    • info

      media type application/json was changed to a more specific media type application/problem+json for the response status

    • info

      media type application/json was changed to a more specific media type application/problem+json for the response status

    • info

      media type application/json was changed to a more specific media type application/problem+json for the response status

    • info

      added the non-success response with the status