v1

latestOpenAPI 3.1.02026-07-243113441.2 MB

Notifications

Get notifications for company

Returns all notifications relevant for the given company.

scope: notifications:read

get/v1/companies/{company_uuid}/notifications

Path parameters

company_uuidstring required

The UUID of the company for which you would like to return notifications

Query parameters

status'open' | 'expired' | 'resolved'

pageinteger

The page that is requested. When unspecified, will load all objects unless endpoint forces pagination.

perinteger

Number of objects per page. For majority of endpoints will default to 25

Headers

X-Gusto-API-Version'2026-06-15'

Determines the date-based API version associated with your API call. If none is provided, your application's minimum API version is used.

Response

successful

uuidstring required

Unique identifier of a notification.

company_uuidstring required

Unique identifier of the company to which the notification belongs.

titlestring required

The title of the notification. This highlights the actionable component of the notification.

messagestring required

The message of the notification. This provides additional context for the user and recommends a specific action to resolve the notification.

status'open' | 'resolved' | 'expired' required

Represents the notification's status as managed by our system. It is updated based on observable system events and internal business logic, and does not reflect resolution steps taken outside our system. This field is read-only and cannot be modified via the API.

categorystring required

The notification's category.

actionableboolean required

Indicates whether a notification requires action or not. If false, the notification provides critical information only.

can_block_payrollboolean required

Indicates whether a notification may block ability to run payroll. If true, we suggest that these notifications are prioritized to your end users.

published_atstring required

Timestamp of when the notification was published.

due_atstring nullable required

Timestamp of when the notification is due. If the notification has no due date, this field will be null.

template_variablesobject

An object containing template variables used to render the notification. The structure of this object depends on the notification category. Each category defines a fixed set of variable names (keys), which are always present. The values of these variables can vary depending on the specific notification instance.