Add or update a bookmark

Request

To add or update a bookmark on content for an account, send a PUT request to:

https://<host>:<port>/useractivityvault/v1/clientdata/account/{account}/user/{userId}/bookmarks/{contentId}

When updating an existing bookmark, if you do not supply a value for a parameter that already has a value, it will be set to null.

So the recommended approach is to use a GET request to get the bookmark, make the required changes, then use this modified set of parameters in the body of the PUT request.

Headers

• Authorization: Bearer – bearer token

• Content-Type: application/json

Mandatory arguments

• account – the account ID (in both the path and the body)

• userId – the profile ID (in both the path and the body)

• contentId – the ID of the content for which the bookmark is being added (in both the path and the body)

• contentType – the content's type (in body). This must be one of the following:

  • vod-ed – VOD content

  • vod-ltcu – a live programme being watched as long-term catch-up

  • live-event – a live programme

  • live-stcu-event – a live programme being watched as short-term catch-up

  • npvr-event – a recording of a live programme

• position – the position of the bookmark, in seconds from the beginning of the content (in body)

• tags – for a bookmark that indicates that the user paused the content or playback was otherwise interrupted before finishing watching, a tag of "In Progress" must be added.

• metadata – you can include any additional required information here as key/value pairs, but you must include contentDuration, which is the total duration of the content in seconds.

Other arguments

• pretty – specifies that the output should be pretty-printed (that is, in human-readable format) (query parameter)

• expires – the time (in seconds) after which the bookmark expires (query parameter). This is to save storage space. Default (from configuration): one year.

• deviceId – the ID of the device (in body). Note that only one bookmark can exist for each content ID (per account). If you try to add a new bookmark for content that already has a bookmark (with a new device ID, for example), the existing bookmark is updated. A new bookmark is not created.

• name – a name for the bookmark (in body)

• creationDate – bookmark creation date/time, in ISO 8601 format. If you do not specify this, UAV sets it automatically.

• modifiedDate – bookmark last modified date/time, in ISO 8601 format. If you do not specify this, UAV sets it automatically.

• tenantId – the operator’s tenant ID

Example

A PUT request with this payload adds a bookmark 300 seconds (five minutes) from the beginning for the specified content and account:

{
    "account": "account1234",
    "userId": "Oliver",
    "contentId": "Die Hard",
    "position": 300,
    "tags": [
      "In Progress"
    ],
    "metadata": {
      "contentDuration": 7920
    }
}

Response

A successful request returns an HTTP 200 status.

A bad request returns an HTTP 400 status.

An unauthorised request returns an HTTP 401 status.

Example

{
  "account": "account1234",
  "userId": "Oliver",
  "deviceId": "a624d4",
  "contentId": "Die Hard",
  "name": "",
  "contentType": "vod",
  "position": 300,
  "creationDate": "2025-12-15T16:42:11.095Z",
  "modifiedDate": "2025-12-15T16:42:11.095Z",
  "metadata": {
    "contentDuration": 7920
  },
  "tags": [
    "In Progress"
  ],
  "tenantId": "tenant01"
}

See also

For full details of this API, see the User Activity Vault (UAV) API documentation.