BAbamboohr
Alerts
Public API

Create Alert Configuration

Changed on

Creates an alert configuration for the authenticated company from one of BambooHR's alert templates, and returns the stored configuration, including its server-assigned id, as a single JSON object.

Use this to add a configuration the company does not have yet. To overwrite one that already exists, use Replace Alert Configuration (replace-alert-configuration) instead; to see what is already configured, use List Alert Configurations (list-alert-configurations). bambooAlertId names the alert template the configuration is built on and comes from List Alert Templates (list-alert-templates). An alert configuration sends scheduled email to people; to receive a programmatic HTTP callback when employee data changes instead, use Webhooks > Create Webhook (create-webhook).

The configuration is live as soon as it is created and begins sending on the schedule it defines. Nothing limits a template to one configuration, so repeating this call with the same bambooAlertId adds a second configuration rather than replacing the first, 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

post/api/v1/alert-configurations

Request

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 created 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 201

    • 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 a05e93bc2eb9c39a40fbd71e6e07f3c6 removed and replaced with create-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