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….

Still have questions? We’re happy to help!

Contact Us