Notifications
The notification object
| Attribute | Type | Description |
|---|---|---|
id |
integer | Unique ID for the notification. |
notification_type |
string | Type of notification. Known values are timesheet_submitted, timesheet_approved, timesheet_locking, time_tracking_reminder, invoice_paid, pto_request, pto_reviewed, pto_cancelled, expense_request, forecast_access_request, harvest_seat_request, and bulk_action_completed. May be null for retired types. Any other value is uncategorized. |
category |
string | Category of the notification: timesheets, invoices, timeoff, expenses, or account. |
occurred_at |
datetime | Date and time the notification last occurred. Use the ISO 8601 Format. |
read_at |
datetime | Date and time the notification was read, or null if it is unread. Some recurring notifications can become unread again. |
updated_at |
datetime | Date and time the notification was last updated. Use the ISO 8601 Format. |
title |
string | Title of the notification. |
summary |
string | Additional detail for the notification, or null. |
Notification titles and summaries are composed in English by Harvest and may change. Use notification_type and category to identify a notification rather than its title or summary.
Required permissions
Notifications are available to any authenticated user. Every notification endpoint operates only on the notifications of the authenticated caller, and no administrator role is required. Out-of-scope notification IDs return a 404 Not Found status code. An inactive account returns a 403 Forbidden status code.
List all notifications
Beta endpoint. Fully available, but the response shape may still change. Until it is frozen, every response includes
Harvest-Api-Stability: beta.
Returns a list of the authenticated user’s notifications, newest first.
The response contains an object with a notifications property that contains an array of up to per_page notifications. Each entry in the array is a separate notification object. If no more notifications are available, the resulting array will be empty. Several additional pagination properties are included in the response to simplify paginating your notifications.
GET /v2/notifications
| Parameter | Type | Description |
|---|---|---|
updated_since |
datetime | Only return notifications whose updated_at is later than this timestamp. A blank value is ignored. |
cursor |
string | A cursor from a previous response’s links or next_page value. Takes precedence over page. |
page |
integer | The page number to use in pagination. Omitting this parameter, or passing 1, uses cursor-based pagination. |
per_page |
integer | The number of records to return per page. Can range between 1 and 2000. (Default: 2000) |
Example Request:
curl "https://api.harvestapp.com/v2/notifications" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Harvest-Account-Id: $ACCOUNT_ID" \
-H "User-Agent: MyApp ([email protected])"
Example Response:
{
"notifications": [
{
"id": 45321977,
"notification_type": "timesheet_submitted",
"category": "timesheets",
"occurred_at": "2026-10-15T16:04:12Z",
"read_at": null,
"updated_at": "2026-10-15T16:04:12Z",
"title": "Kim Allen submitted a timesheet for approval",
"summary": "Week of October 12, 2026"
},
{
"id": 45321801,
"notification_type": "invoice_paid",
"category": "invoices",
"occurred_at": "2026-10-15T11:22:37Z",
"read_at": "2026-10-15T13:10:00Z",
"updated_at": "2026-10-15T13:10:00Z",
"title": "Invoice INV-00042 was paid",
"summary": "Acme Corporation paid $4,200.00"
}
],
"per_page": 2000,
"total_pages": 1,
"total_entries": 2,
"next_page": null,
"previous_page": null,
"page": 1,
"links": {
"first": "https://api.harvestapp.com/v2/notifications?page=1&per_page=2000&ref=first",
"next": null,
"previous": null,
"last": "https://api.harvestapp.com/v2/notifications?page=1&per_page=2000&ref=last"
}
}Retrieve the unread count
Beta endpoint. Fully available, but the response shape may still change. Until it is frozen, every response includes
Harvest-Api-Stability: beta.
Returns the number of unread notifications for the authenticated user, with a breakdown by category.
This endpoint takes no parameters.
GET /v2/notifications/unread_count
Example Request:
curl "https://api.harvestapp.com/v2/notifications/unread_count" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Harvest-Account-Id: $ACCOUNT_ID" \
-H "User-Agent: MyApp ([email protected])"
Example Response:
{
"total": 5,
"by_category": {
"timesheets": 3,
"timeoff": 1,
"expenses": 1
}
}Categories with no unread notifications are omitted from by_category. If there are no unread notifications, total is 0 and by_category is {}.
Peek at notifications
Beta endpoint. Fully available, but the response shape may still change. Until it is frozen, every response includes
Harvest-Api-Stability: beta.
Returns up to six of the authenticated user’s most recent notifications, along with the unread count. The response has no pagination envelope.
This endpoint takes no parameters.
GET /v2/notifications/peek
Example Request:
curl "https://api.harvestapp.com/v2/notifications/peek" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Harvest-Account-Id: $ACCOUNT_ID" \
-H "User-Agent: MyApp ([email protected])"
Example Response:
{
"notifications": [
{
"id": 45321977,
"notification_type": "timesheet_submitted",
"category": "timesheets",
"occurred_at": "2026-10-15T16:04:12Z",
"read_at": null,
"updated_at": "2026-10-15T16:04:12Z",
"title": "Kim Allen submitted a timesheet for approval",
"summary": "Week of October 12, 2026"
},
{
"id": 45321801,
"notification_type": "invoice_paid",
"category": "invoices",
"occurred_at": "2026-10-15T11:22:37Z",
"read_at": "2026-10-15T13:10:00Z",
"updated_at": "2026-10-15T13:10:00Z",
"title": "Invoice INV-00042 was paid",
"summary": "Acme Corporation paid $4,200.00"
}
],
"unread_count": {
"total": 5,
"by_category": {
"timesheets": 3,
"timeoff": 1,
"expenses": 1
}
}
}Mark a notification as read
Beta endpoint. Fully available, but the response shape may still change. Until it is frozen, every response includes
Harvest-Api-Stability: beta.
Marks a single notification as read and returns the updated unread count. Reading an already-read notification returns the same count without changing the notification.
This endpoint takes no parameters and no request body.
POST /v2/notifications/{NOTIFICATION_ID}/mark_read
Example Request:
curl -X POST "https://api.harvestapp.com/v2/notifications/45321977/mark_read" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Harvest-Account-Id: $ACCOUNT_ID" \
-H "User-Agent: MyApp ([email protected])"
Example Response:
{
"total": 4,
"by_category": {
"timesheets": 2,
"timeoff": 1,
"expenses": 1
}
}The notification ID must be an all-digit value. Any other value, or an ID that does not belong to the authenticated caller, returns a 404 Not Found status code.
Mark all notifications as read
Beta endpoint. Fully available, but the response shape may still change. Until it is frozen, every response includes
Harvest-Api-Stability: beta.
Marks all of the authenticated user’s unread notifications as read and returns the updated unread count. Calling this endpoint when there are no unread notifications returns the same count and is not an error.
This endpoint takes no parameters and no request body.
POST /v2/notifications/mark_all_read
Example Request:
curl -X POST "https://api.harvestapp.com/v2/notifications/mark_all_read" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Harvest-Account-Id: $ACCOUNT_ID" \
-H "User-Agent: MyApp ([email protected])"
Example Response:
{
"total": 0,
"by_category": {}
}Errors
The following errors can be returned by any notification endpoint.
| Status | Description |
|---|---|
400 |
The User-Agent header is missing. The response body is User-Agent header required. |
400 |
The updated_since value is not a valid ISO 8601 datetime. The response body is Invalid updated_since datetime provided: "…". |
400 |
The page value is not a positive integer, or the per_page value is outside the range 1 to 2000. |
401 |
The credentials are missing or invalid: Authentication failed for API request. |
403 |
The account is inactive: Account inactive. |
404 |
The notification ID is not an all-digit value or is out of range, or no notification with that ID exists for the authenticated caller: Record not found. |
415 |
A request body was sent with a media type other than application/json: Content-Type header required to be application/json, got "…". |
422 |
The cursor value is malformed or empty: Invalid cursor parameter…. |