Notifications
7 operations in the Tolvi API, version 1. Paths are relative to https://api.tolvi.co.uk. Every amount is integer pence.
List your notifications, newest first
GET/api/v1/notifications
- Scopes
work:read
Parameters
| Name | In | Type | Description |
|---|---|---|---|
unread | query | boolean | |
limit | query | integer | 1 to 100; default 50 |
Responses
200 OK, application/json
Body: object (NotificationPage).
| Field | Type | Description |
|---|---|---|
rowsrequired | array of Notification | |
rows[].idrequired | string (uuid) | |
rows[].typerequired | string (NotificationType) | One of: |
rows[].textrequired | string | |
rows[].engagementIdrequired | string (uuid)nullable | |
rows[].sectionCoderequired | stringnullable | |
rows[].reviewPointIdrequired | string (uuid)nullable | |
rows[].actorIdrequired | string (uuid)nullable | |
rows[].actorName | stringnullable | Who did it, by name; null for Tolvi itself (deadlines, syncs, billing). |
rows[].product | string (NotificationProduct) | The product it came from; suite for firm-wide notices such as billing and AI tokens. One of: |
rows[].subjectId | string (uuid)nullable | The return or set of accounts it is about, for those products. |
rows[].emailrequired | boolean | |
rows[].createdAtrequired | string (date-time) | |
rows[].readAtrequired | string (date-time)nullable | |
unreadrequired | integer |
Errors: 400 Bad request, 401 Unauthorised, 403 Forbidden, 429 Too many requests, as problem details (application/problem+json).
Mark a notification read
POST/api/v1/notifications/{notificationId}/read
- Scopes
work:read
Parameters
| Name | In | Type | Description |
|---|---|---|---|
notificationIdrequired | path | string (uuid) |
Responses
200 OK, application/json
Body: object (Notification).
| Field | Type | Description |
|---|---|---|
idrequired | string (uuid) | |
typerequired | string (NotificationType) | One of: |
textrequired | string | |
engagementIdrequired | string (uuid)nullable | |
sectionCoderequired | stringnullable | |
reviewPointIdrequired | string (uuid)nullable | |
actorIdrequired | string (uuid)nullable | |
actorName | stringnullable | Who did it, by name; null for Tolvi itself (deadlines, syncs, billing). |
product | string (NotificationProduct) | The product it came from; suite for firm-wide notices such as billing and AI tokens. One of: |
subjectId | string (uuid)nullable | The return or set of accounts it is about, for those products. |
emailrequired | boolean | |
createdAtrequired | string (date-time) | |
readAtrequired | string (date-time)nullable |
Errors: 400 Bad request, 401 Unauthorised, 403 Forbidden, 404 Not found, 429 Too many requests, as problem details (application/problem+json).
Get your email preferences
GET/api/v1/email-preferences
- Scopes
work:read
Responses
200 OK, application/json
Body: object (EmailPreferences).
Which emails you get from this firm. The firm’s notification settings decide what can be emailed at all.
| Field | Type | Description |
|---|---|---|
notificationsrequired | boolean | Immediate emails for notifications the firm sends by email (mentions, review hand-offs). Billing problems are always emailed to admins. |
digestrequired | boolean | The daily summary of notifications the firm puts in the digest. |
remindersrequired | boolean | Deadline reminder emails. The in-app reminder still arrives. |
trialrequired | boolean | Tips during a Tolvi trial (getting started, halfway). Notices about the trial ending always arrive. |
Errors: 400 Bad request, 401 Unauthorised, 403 Forbidden, 429 Too many requests, as problem details (application/problem+json).
Change your email preferences
PUT/api/v1/email-preferences
- Scopes
work:read
Request body
Required. application/json: object (EmailPreferencesPatch).
| Field | Type | Description |
|---|---|---|
notifications | boolean | |
digest | boolean | |
reminders | boolean | |
trial | boolean |
Responses
200 OK, application/json
Body: object (EmailPreferences).
Which emails you get from this firm. The firm’s notification settings decide what can be emailed at all.
| Field | Type | Description |
|---|---|---|
notificationsrequired | boolean | Immediate emails for notifications the firm sends by email (mentions, review hand-offs). Billing problems are always emailed to admins. |
digestrequired | boolean | The daily summary of notifications the firm puts in the digest. |
remindersrequired | boolean | Deadline reminder emails. The in-app reminder still arrives. |
trialrequired | boolean | Tips during a Tolvi trial (getting started, halfway). Notices about the trial ending always arrive. |
Errors: 400 Bad request, 401 Unauthorised, 403 Forbidden, 429 Too many requests, as problem details (application/problem+json).
Get email preferences from an email link
GET/api/v1/email/preferences
- Access
- No authentication.
No sign-in: the token in the link identifies the firm and person.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
tokenrequired | query | string | The signed token from the link in an email. |
Responses
200 OK, application/json
Body: object (EmailLinkPreferences).
Preferences opened from the link in an email.
| Field | Type | Description |
|---|---|---|
notificationsrequired | boolean | Immediate emails for notifications the firm sends by email (mentions, review hand-offs). Billing problems are always emailed to admins. |
digestrequired | boolean | The daily summary of notifications the firm puts in the digest. |
remindersrequired | boolean | Deadline reminder emails. The in-app reminder still arrives. |
trialrequired | boolean | Tips during a Tolvi trial (getting started, halfway). Notices about the trial ending always arrive. |
firmNamerequired | string | |
emailrequired | string (email) | |
scoperequired | string (EmailLinkScope) | What this link may change. One of: |
Errors: 400 Bad request, 429 Too many requests, as problem details (application/problem+json).
Change email preferences from an email link
PUT/api/v1/email/preferences
- Access
- No authentication.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
tokenrequired | query | any | The signed token from the link in an email. |
Request body
Required. application/json: object (EmailPreferencesPatch).
| Field | Type | Description |
|---|---|---|
notifications | boolean | |
digest | boolean | |
reminders | boolean | |
trial | boolean |
Responses
200 OK, application/json
Body: object (EmailLinkPreferences).
Preferences opened from the link in an email.
The fields are as shown above.
Errors: 400 Bad request, 429 Too many requests, as problem details (application/problem+json).
One-click unsubscribe (RFC 8058)
POST/api/v1/email/unsubscribe
- Access
- No authentication.
The List-Unsubscribe target. Mail clients POST List-Unsubscribe=One-Click; the body is not needed.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
tokenrequired | query | string | The signed token from the link in an email. |
Responses
200 OK, application/json
Body: object (EmailLinkPreferences).
Preferences opened from the link in an email.
The fields are as shown above.
Errors: 400 Bad request, 429 Too many requests, as problem details (application/problem+json).