BAbamboohr
Alerts
Public API

List Alert Configurations

Changed on

Returns every alert configuration the company has set up: which alert template each one uses, when it runs, who receives it, and any custom subject, message, or list-value filters. The response is a top-level JSON array with no wrapper, empty when the company has no configured alerts, and in no guaranteed order.

Use this to enumerate or search a company's own configured alerts. To read a single configuration whose id is already known, use Get Alert Configuration (get-alert-configuration) 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 each entry returned here is the same identifier that list-alert-templates returns as id.

Access is all-or-nothing rather than per-record. An authenticated caller without view access to the company's Email Alerts settings receives 403 instead of a filtered list, so a successful response always contains the company's complete set.

OAuth Scopes: alerts

get/api/v1/alert-configurations

Request

Response

Array of the company's alert configurations. Empty array when none are configured.

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 items/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 6d0a073cbf3e97fe0409de42c68fe779 removed and replaced with list-alert-configurations

    • 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

      added the non-success response with the status