BAbamboohr
Alerts
Public API

Replace Alert Configuration

Changed on

Overwrites the alert configuration identified by {id} and returns the stored configuration as a single JSON object. Each call replaces the whole configuration: a property left out of the request body is reset to its default rather than kept at its current value, so send the full desired state and not only the properties that changed. Read the current state with Get Alert Configuration (get-alert-configuration) first when only part of a configuration should change. The response echoes the values submitted rather than re-reading the saved row, so read the configuration back with get-alert-configuration when the persisted state needs to be confirmed.

Use this to change a configuration the company already has. To add one, use Create Alert Configuration (create-alert-configuration) instead; to find out what is already configured, use List Alert Configurations (list-alert-configurations). bambooAlertId names the alert template the configuration is built on, comes from List Alert Templates (list-alert-templates), and is required on every call even when the template is not changing.

The configuration stays live throughout and sends on whatever schedule the call leaves it with, so an update that omits the sendTo* properties can re-enable delivery to recipients the previous state excluded. Changing bambooAlertId re-points this configuration at a different alert template rather than adding a second one, and no endpoint deletes an alert configuration once it exists. The returned object also carries additionalRecipientEmails, employeeIds, listValueIds, and userIds; this API never stores those, so scope an alert's audience with filterListValueIds and the sendTo* properties instead.

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 partial success.

OAuth Scopes: alerts.write

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

Request

Path parameters

idinteger required

Identifier of the alert configuration to overwrite, 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. The path value is authoritative; no wildcard or 0 sentinel is supported.

Request body

bambooAlertIdinteger required

Identifier of the alert template this configuration is based on, taken from the id field of List Alert Templates (list-alert-templates). The template catalog is global rather than per-company, and an identifier that is not in the catalog is rejected. 0 is rejected as a missing value; there is no sentinel for "any alert".

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

How often the alert runs.

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. Omitted on a replace resets this to null.

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

The unit that dueWithin is counted in. Omitted on a replace resets this to null.

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.

customMessagestring nullable

Custom body text for the alert email. Limited to 1024 bytes; multibyte characters consume more than one byte each. Null uses the alert template's default body, and omitting it on a replace resets this to null.

customSubjectstring nullable

Custom subject line for the alert email. Limited to 250 bytes; multibyte characters consume more than one byte each. Null uses the alert template's default subject, and omitting it on a replace resets this to null.

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

Groups the recipients of a summary-style alert by this employee attribute. Null applies no grouping, and omitting it on a replace resets this to null.

limitTrainingToRequiredboolean

Whether the training covered by a training alert should be limited to required training.

runAtTimestring nullable

Time of day the alert is sent, formatted as HH:MM:SS and interpreted in runAtTimeZone. Minutes and seconds are not optional: an HH:MM value is rejected. Omitted on a replace resets this to null.

runAtTimeZonestring nullable

IANA time zone name that runAtTime is evaluated in, such as America/Denver. Abbreviations such as MST are rejected. Null evaluates runAtTime in the company's own time zone, and omitting it on a replace resets this to null.

includePositionboolean

Whether the alert should include position.

includeLocationboolean

Whether the alert should include location.

filterListValueIdsinteger[]

List value IDs the alert is scoped to. Accepted values are the options[].id values of the employee filter list fields: Department, Division, Location, Job Title, Employment Status, and Status, plus Employment Type and Team on accounts where those fields are enabled. Look the IDs up with Account Information > List List Fields (list-list-fields); an ID belonging to any other list field is rejected. An empty array leaves the alert unscoped, and omitting it on a replace clears all list-value scoping. This is the only recipient-scoping property the API stores.

Example request

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

Response

The replaced 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

      request property / was restricted to a list of enum values

    • breaking

      request property / was restricted to a list of enum values

    • breaking

      the request property became required

    • breaking

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

    • warning

      the / request property's max was set to 32767.00

    • warning

      removed the request property

    • warning

      removed the request property

    • warning

      removed the request property

    • warning

      removed the request property

    • warning

      removed the request property

    • warning

      removed the request property

    • warning

      removed the request property

    • 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 eb42aa2fa339ba5c08b147fc13c6a79e removed and replaced with replace-alert-configuration

    • info

      api tag Alerts added

    • info

      api tag Alert Configurations removed

    • info

      the request property default value false was added

    • info

      the request property default value false was added

    • info

      the request property default value true was added

    • info

      the request property default value daily was added

    • info

      the request property default value false was added

    • info

      the request property default value true was added

    • info

      the request property default value false was added

    • info

      added the new days enum value to the request property /

    • info

      added the new department enum value to the request property /

    • info

      added the new division enum value to the request property /

    • info

      added the new jobTitle enum value to the request property /

    • info

      added the new location enum value to the request property /

    • info

      added the new months enum value to the request property /

    • info

      added the new weeks enum value to the request property /

    • 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