Settings
24 operations in the Tolvi API, version 1. Paths are relative to https://api.tolvi.co.uk. Every amount is integer pence.
Get the firm’s mapping rules, in order
GET/api/v1/settings/mapping-rules
- Scopes
engagements:read
Part of the working_papers product: the firm must have it and you must have access to it.
Responses
200 OK, application/json
Body: object (MappingRules).
| Field | Type | Description |
|---|---|---|
rulesrequired | array of MappingRule | up to 500 items |
rules[].kindrequired | string (MappingRuleKind) | One of: |
rules[].patternrequired | string | A name pattern (case-insensitive wildcards: * any characters, ? one character, | alternatives, ^ start, $ end; not a regular expression) or a code range "4000-4899". up to 200 characters |
rules[].lineIdrequired | string (LeadLineId) | One of: |
Errors: 400 Bad request, 401 Unauthorised, 403 Forbidden, 429 Too many requests, as problem details (application/problem+json).
Replace the firm’s mapping rules
PUT/api/v1/settings/mapping-rules
- Scopes
settings:admin- Role
- Firm admin
Applied after client memory and before the built-in matcher. Part of the working_papers product: the firm must have it and you must have access to it.
Request body
Required. application/json: object (MappingRules).
| Field | Type | Description |
|---|---|---|
rulesrequired | array of MappingRule | up to 500 items |
rules[].kindrequired | string (MappingRuleKind) | One of: |
rules[].patternrequired | string | A name pattern (case-insensitive wildcards: * any characters, ? one character, | alternatives, ^ start, $ end; not a regular expression) or a code range "4000-4899". up to 200 characters |
rules[].lineIdrequired | string (LeadLineId) | One of: |
Responses
200 OK, application/json
Body: object (MappingRules).
| Field | Type | Description |
|---|---|---|
rulesrequired | array of MappingRule | up to 500 items |
rules[].kindrequired | string (MappingRuleKind) | One of: |
rules[].patternrequired | string | A name pattern (case-insensitive wildcards: * any characters, ? one character, | alternatives, ^ start, $ end; not a regular expression) or a code range "4000-4899". up to 200 characters |
rules[].lineIdrequired | string (LeadLineId) | One of: |
Errors: 400 Bad request, 401 Unauthorised, 403 Forbidden, 429 Too many requests, as problem details (application/problem+json).
Get the firm’s checklist template for every section
GET/api/v1/settings/checklists
- Scopes
engagements:read
Part of the working_papers product: the firm must have it and you must have access to it.
Responses
200 OK, application/json
Body: array of ChecklistTemplate.
The firm’s steps for one section; an empty list restores the built-in steps.
| Field | Type | Description |
|---|---|---|
[].sectionCoderequired | string | |
[].itemsrequired | array of string | up to 100 items |
[].builtinrequired | boolean | Tolvi’s built-in wording (the firm has not set its own). |
Errors: 400 Bad request, 401 Unauthorised, 403 Forbidden, 429 Too many requests, as problem details (application/problem+json).
Set the firm’s checklist for a section
PUT/api/v1/settings/checklists/{code}
- Scopes
settings:admin- Role
- Firm admin
Used for engagements started from now on. Part of the working_papers product: the firm must have it and you must have access to it.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
coderequired | path | string | Section code (W/P ref), e.g. C. One of: |
Request body
Required. application/json: object (SetChecklistTemplate).
| Field | Type | Description |
|---|---|---|
itemsrequired | array of string | up to 100 items |
Responses
200 OK, application/json
Body: object (ChecklistTemplate).
The firm’s steps for one section; an empty list restores the built-in steps.
| Field | Type | Description |
|---|---|---|
sectionCoderequired | string | |
itemsrequired | array of string | up to 100 items |
builtinrequired | boolean | Tolvi’s built-in wording (the firm has not set its own). |
Errors: 400 Bad request, 401 Unauthorised, 403 Forbidden, 404 Not found, 429 Too many requests, as problem details (application/problem+json).
Get the firm’s settings
GET/api/v1/settings
- Scopes
settings:read
Firm details, thresholds, reminders, default workflows, workflow templates, notifications, sync, security, capacity and AI.
Responses
200 OK, application/json
Body: object (FirmSettings).
| Field | Type | Description |
|---|---|---|
firmNamerequired | string | |
onboardedrequired | boolean | |
onboardedAtrequired | string (date-time)nullable | |
firmrequired | object (FirmDetails) | |
firm.name | string | up to 200 characters |
firm.tagline | string | up to 200 characters |
firm.offices | array of string | up to 50 items |
thresholdsrequired | object (FirmThresholds) | Movements at or above both thresholds need an explanation. New engagements copy these. |
thresholds.absolutePencerequired | integer | Integer pence (GBP). at least 0 |
thresholds.percentrequired | integer | 0 to 1000 |
approvalsrequired | object (ApprovalSettings) | Who approves accounts and returns in Accounts, Corporation Tax and Self Assessment. |
approvals.approverRolerequired | string (ApproverRole) | The lowest role that may approve: partners only, or managers and partners. One of: |
reminderDaysrequired | array of integer | |
defaultWorkflowsrequired | object (DefaultWorkflows) | Workflow template id (a preset or the firm’s own) by entity type. |
defaultWorkflows.LTD_FRS102_1Arequired | string | |
defaultWorkflows.LTD_FRS105_MICROrequired | string | |
defaultWorkflows.LLPrequired | string | |
defaultWorkflows.SOLE_TRADERrequired | string | |
defaultWorkflows.PARTNERSHIPrequired | string | |
defaultWorkflows.INDIVIDUAL | string | |
defaultWorkflows.TRUSTrequired | string | |
defaultWorkflows.ESTATErequired | string | |
defaultWorkflows.CHARITY_UNINCORPORATEDrequired | string | |
defaultWorkflows.CHARITY_TRUSTrequired | string | |
defaultWorkflows.CIOrequired | string | |
defaultWorkflows.SCIOrequired | string | |
defaultWorkflows.CHARITABLE_COMPANYrequired | string | |
notificationsrequired | object (NotificationPrefs) | Channels per notification type. Mentions and assignments are always in-app. |
notifications.mentionrequired | object (NotificationChannels) | |
notifications.mention.apprequired | boolean | |
notifications.mention.emailrequired | boolean | |
notifications.mention.digestrequired | boolean | |
notifications.rprequired | object (NotificationChannels) | |
notifications.rp.apprequired | boolean | |
notifications.rp.emailrequired | boolean | |
notifications.rp.digestrequired | boolean | |
notifications.clearedrequired | object (NotificationChannels) | |
notifications.cleared.apprequired | boolean | |
notifications.cleared.emailrequired | boolean | |
notifications.cleared.digestrequired | boolean | |
notifications.reviewrequired | object (NotificationChannels) | |
notifications.review.apprequired | boolean | |
notifications.review.emailrequired | boolean | |
notifications.review.digestrequired | boolean | |
notifications.syncrequired | object (NotificationChannels) | |
notifications.sync.apprequired | boolean | |
notifications.sync.emailrequired | boolean | |
notifications.sync.digestrequired | boolean | |
notifications.assignrequired | object (NotificationChannels) | |
notifications.assign.apprequired | boolean | |
notifications.assign.emailrequired | boolean | |
notifications.assign.digestrequired | boolean | |
notifications.deadlinerequired | object (NotificationChannels) | |
notifications.deadline.apprequired | boolean | |
notifications.deadline.emailrequired | boolean | |
notifications.deadline.digestrequired | boolean | |
notifications.filing | object (NotificationChannels) | HMRC’s reply to a return. |
notifications.filing.apprequired | boolean | |
notifications.filing.emailrequired | boolean | |
notifications.filing.digestrequired | boolean | |
syncrequired | object (SyncSettings) | |
sync.frequencyrequired | string (SyncFrequency) | One of: |
sync.timerequired | string | pattern ^([01]\d|2[0-3]):[0-5]\d$; example "02:00" |
sync.ignoreUnderPencerequired | integer | Integer pence (GBP). at least 0 |
sync.comparePriorYearrequired | boolean | |
sync.onChangerequired | string (SyncOnChange) | One of: |
sync.digestrequired | string (SyncDigest) | One of: |
emailrequired | object (EmailSettings) | When the daily digest and deadline reminders go out, in the firm’s local time. |
email.timeZonerequired | string | IANA time zone, e.g. Europe/London. up to 64 characters |
email.digestHourrequired | integer | Local hour (0–23) from which the digest and reminders are sent. 0 to 23 |
securityrequired | object (SecuritySettings) | |
security.mfarequired | boolean | Enforced: sign-in tokens must show a second factor (amr / acr). |
security.ssorequired | boolean | |
security.timeoutMinutesrequired | integer | Enforced: people sign in again this long after they last signed in (auth_time). 5 to 1440 |
security.retentionYearsrequired | integer | Not yet enforced: no deletion job runs yet, so records are currently kept indefinitely. 6 to 20 |
capacityrequired | object (Capacity) | Open engagements a person can hold, by role (null: no limit). |
capacity.preparerrequired | integernullable | |
capacity.reviewerrequired | integernullable | |
capacity.managerrequired | integernullable | |
capacity.partnerrequired | integernullable | |
airequired | object (AiSettings) | Tolvi AI controls: on/off, per-feature switches, monthly limits and who can buy tokens. |
ai.enabledrequired | boolean | |
ai.featuresrequired | object (AiFeatureSwitches) | |
ai.features.explain_movementsrequired | boolean | |
ai.features.suggest_mappingsrequired | boolean | |
ai.features.review_assistantrequired | boolean | |
ai.features.check_evidencerequired | boolean | |
ai.features.explain_sync_changesrequired | boolean | |
ai.features.ask_tolvirequired | boolean | |
ai.features.draft_client_queriesrequired | boolean | |
ai.features.summarise_meeting | boolean | Meetings: summary and actions after each recorded meeting. Optional when saving (unchanged if left out). |
ai.features.sa_assistant | boolean | Self Assessment: AI Mode. Optional when saving (unchanged if left out). |
ai.features.sa_read_document | boolean | Self Assessment: reading uploaded documents in AI Mode. Optional when saving (unchanged if left out). |
ai.features.accounts_draft_note | boolean | Accounts: drafting note wording for a person to check. Optional when saving (unchanged if left out). |
ai.defaultMonthlyLimitrequired | integernullable | Tolvi AI tokens per person per UK calendar month; null for no limit. at least 0 |
ai.userLimitsrequired | object | Per-person limits by user id (null: no limit). |
ai.buyersrequired | string (TokenBuyers) | One of: |
ai.autoTopUprequired | object (AutoTopUp) | |
ai.autoTopUp.enabledrequired | boolean | |
ai.autoTopUp.belowTokensrequired | integer | at least 0 |
ai.autoTopUp.packIdrequired | string (TokenPackId) | One of: |
workflowsrequired | array of WorkflowTemplate | |
workflows[].idrequired | string | A preset id (preset-…) or the firm template’s uuid. |
workflows[].namerequired | string | |
workflows[].builtinrequired | boolean | A Tolvi preset (read only). |
workflows[].versionrequired | integer | |
workflows[].stagesrequired | array of WorkflowTemplateStage | |
workflows[].stages[].id | string | Stage id (read only). |
workflows[].stages[].namerequired | string | up to 100 characters |
workflows[].stages[].rolerequired | string (WorkflowStageRole) | One of: |
workflows[].stages[].mustDifferrequired | boolean | Must be a different person from every earlier stage. |
workflows[].stages[].scope | string (StageScope) | Default both. One of: |
Errors: 400 Bad request, 401 Unauthorised, 403 Forbidden, 429 Too many requests, as problem details (application/problem+json).
Update the firm’s name, tagline and offices
PATCH/api/v1/settings/firm
- Scopes
settings:admin- Role
- Firm admin
- Access
- A signed-in Tolvi session only, never an API token.
Request body
Required. application/json: object (FirmDetails).
| Field | Type | Description |
|---|---|---|
name | string | up to 200 characters |
tagline | string | up to 200 characters |
offices | array of string | up to 50 items |
Responses
Errors: 400 Bad request, 401 Unauthorised, 403 Forbidden, 429 Too many requests, as problem details (application/problem+json).
Set the review thresholds new engagements use
PUT/api/v1/settings/thresholds
- Scopes
settings:admin- Role
- Firm admin
Request body
Required. application/json: object (FirmThresholds).
Movements at or above both thresholds need an explanation. New engagements copy these.
| Field | Type | Description |
|---|---|---|
absolutePencerequired | integer | Integer pence (GBP). at least 0 |
percentrequired | integer | 0 to 1000 |
Responses
Errors: 400 Bad request, 401 Unauthorised, 403 Forbidden, 429 Too many requests, as problem details (application/problem+json).
Set who approves accounts and returns
PUT/api/v1/settings/approvals
- Scopes
settings:admin- Role
- Firm admin
- Access
- A signed-in Tolvi session only, never an API token.
Firm admins, signed in. Partners by default, or managers and partners. Applies to Accounts, Corporation Tax and Self Assessment from the next approval, and approvals already given stand. Never available to API keys or connected assistants.
Request body
Required. application/json: object (ApprovalSettings).
Who approves accounts and returns in Accounts, Corporation Tax and Self Assessment.
| Field | Type | Description |
|---|---|---|
approverRolerequired | string (ApproverRole) | The lowest role that may approve: partners only, or managers and partners. One of: |
Responses
Errors: 400 Bad request, 401 Unauthorised, 403 Forbidden, 429 Too many requests, as problem details (application/problem+json).
Set deadline reminder days
PUT/api/v1/settings/reminders
- Scopes
settings:admin- Role
- Firm admin
Request body
Required. application/json: object (Reminders).
| Field | Type | Description |
|---|---|---|
reminderDaysrequired | array of integer | Days before the filing deadline to remind whoever’s turn it is. up to 10 items |
Responses
Errors: 400 Bad request, 401 Unauthorised, 403 Forbidden, 429 Too many requests, as problem details (application/problem+json).
Set the default workflow for each entity type
PUT/api/v1/settings/default-workflows
- Scopes
settings:admin- Role
- Firm admin
- Access
- A signed-in Tolvi session only, never an API token.
Request body
Required. application/json: object (DefaultWorkflows).
Workflow template id (a preset or the firm’s own) by entity type.
| Field | Type | Description |
|---|---|---|
LTD_FRS102_1Arequired | string | |
LTD_FRS105_MICROrequired | string | |
LLPrequired | string | |
SOLE_TRADERrequired | string | |
PARTNERSHIPrequired | string | |
INDIVIDUAL | string | |
TRUSTrequired | string | |
ESTATErequired | string | |
CHARITY_UNINCORPORATEDrequired | string | |
CHARITY_TRUSTrequired | string | |
CIOrequired | string | |
SCIOrequired | string | |
CHARITABLE_COMPANYrequired | string |
Responses
Errors: 400 Bad request, 401 Unauthorised, 403 Forbidden, 429 Too many requests, as problem details (application/problem+json).
Set the firm’s notification channels
PUT/api/v1/settings/notifications
- Scopes
settings:admin- Role
- Firm admin
Mentions and assignments always arrive in-app.
Request body
Required. application/json: object (NotificationPrefs).
Channels per notification type. Mentions and assignments are always in-app.
| Field | Type | Description |
|---|---|---|
mentionrequired | object (NotificationChannels) | |
mention.apprequired | boolean | |
mention.emailrequired | boolean | |
mention.digestrequired | boolean | |
rprequired | object (NotificationChannels) | |
rp.apprequired | boolean | |
rp.emailrequired | boolean | |
rp.digestrequired | boolean | |
clearedrequired | object (NotificationChannels) | |
cleared.apprequired | boolean | |
cleared.emailrequired | boolean | |
cleared.digestrequired | boolean | |
reviewrequired | object (NotificationChannels) | |
review.apprequired | boolean | |
review.emailrequired | boolean | |
review.digestrequired | boolean | |
syncrequired | object (NotificationChannels) | |
sync.apprequired | boolean | |
sync.emailrequired | boolean | |
sync.digestrequired | boolean | |
assignrequired | object (NotificationChannels) | |
assign.apprequired | boolean | |
assign.emailrequired | boolean | |
assign.digestrequired | boolean | |
deadlinerequired | object (NotificationChannels) | |
deadline.apprequired | boolean | |
deadline.emailrequired | boolean | |
deadline.digestrequired | boolean | |
filing | object (NotificationChannels) | HMRC’s reply to a return. |
filing.apprequired | boolean | |
filing.emailrequired | boolean | |
filing.digestrequired | boolean |
Responses
Errors: 400 Bad request, 401 Unauthorised, 403 Forbidden, 429 Too many requests, as problem details (application/problem+json).
Set sync settings
PUT/api/v1/settings/sync
- Scopes
settings:admin- Role
- Firm admin
Request body
Required. application/json: object (SyncSettings).
| Field | Type | Description |
|---|---|---|
frequencyrequired | string (SyncFrequency) | One of: |
timerequired | string | pattern ^([01]\d|2[0-3]):[0-5]\d$; example "02:00" |
ignoreUnderPencerequired | integer | Integer pence (GBP). at least 0 |
comparePriorYearrequired | boolean | |
onChangerequired | string (SyncOnChange) | One of: |
digestrequired | string (SyncDigest) | One of: |
Responses
Errors: 400 Bad request, 401 Unauthorised, 403 Forbidden, 429 Too many requests, as problem details (application/problem+json).
Set when digests and deadline reminders are emailed
PUT/api/v1/settings/email
- Scopes
settings:admin- Role
- Firm admin
The firm’s time zone and the local hour the daily digest and deadline reminders go out.
Request body
Required. application/json: object (EmailSettings).
When the daily digest and deadline reminders go out, in the firm’s local time.
| Field | Type | Description |
|---|---|---|
timeZonerequired | string | IANA time zone, e.g. Europe/London. up to 64 characters |
digestHourrequired | integer | Local hour (0–23) from which the digest and reminders are sent. 0 to 23 |
Responses
Errors: 400 Bad request, 401 Unauthorised, 403 Forbidden, 429 Too many requests, as problem details (application/problem+json).
Set security settings
PUT/api/v1/settings/security
- Scopes
settings:admin- Role
- Firm admin
- Access
- A signed-in Tolvi session only, never an API token.
Request body
Required. application/json: object (SecuritySettings).
| Field | Type | Description |
|---|---|---|
mfarequired | boolean | Enforced: sign-in tokens must show a second factor (amr / acr). |
ssorequired | boolean | |
timeoutMinutesrequired | integer | Enforced: people sign in again this long after they last signed in (auth_time). 5 to 1440 |
retentionYearsrequired | integer | Not yet enforced: no deletion job runs yet, so records are currently kept indefinitely. 6 to 20 |
Responses
Errors: 400 Bad request, 401 Unauthorised, 403 Forbidden, 429 Too many requests, as problem details (application/problem+json).
Set capacity by role
PUT/api/v1/settings/capacity
- Scopes
settings:admin- Role
- Firm admin
Request body
Required. application/json: object (Capacity).
Open engagements a person can hold, by role (null: no limit).
| Field | Type | Description |
|---|---|---|
preparerrequired | integernullable | |
reviewerrequired | integernullable | |
managerrequired | integernullable | |
partnerrequired | integernullable |
Responses
Errors: 400 Bad request, 401 Unauthorised, 403 Forbidden, 429 Too many requests, as problem details (application/problem+json).
Set Tolvi AI controls
PUT/api/v1/settings/ai
- Scopes
settings:admin- Role
- Firm admin
- Access
- A signed-in Tolvi session only, never an API token.
On/off, per-feature switches, monthly limits, who can buy tokens and auto top-up.
Request body
Required. application/json: object (AiSettings).
Tolvi AI controls: on/off, per-feature switches, monthly limits and who can buy tokens.
| Field | Type | Description |
|---|---|---|
enabledrequired | boolean | |
featuresrequired | object (AiFeatureSwitches) | |
features.explain_movementsrequired | boolean | |
features.suggest_mappingsrequired | boolean | |
features.review_assistantrequired | boolean | |
features.check_evidencerequired | boolean | |
features.explain_sync_changesrequired | boolean | |
features.ask_tolvirequired | boolean | |
features.draft_client_queriesrequired | boolean | |
features.summarise_meeting | boolean | Meetings: summary and actions after each recorded meeting. Optional when saving (unchanged if left out). |
features.sa_assistant | boolean | Self Assessment: AI Mode. Optional when saving (unchanged if left out). |
features.sa_read_document | boolean | Self Assessment: reading uploaded documents in AI Mode. Optional when saving (unchanged if left out). |
features.accounts_draft_note | boolean | Accounts: drafting note wording for a person to check. Optional when saving (unchanged if left out). |
defaultMonthlyLimitrequired | integernullable | Tolvi AI tokens per person per UK calendar month; null for no limit. at least 0 |
userLimitsrequired | object | Per-person limits by user id (null: no limit). |
buyersrequired | string (TokenBuyers) | One of: |
autoTopUprequired | object (AutoTopUp) | |
autoTopUp.enabledrequired | boolean | |
autoTopUp.belowTokensrequired | integer | at least 0 |
autoTopUp.packIdrequired | string (TokenPackId) | One of: |
Responses
Errors: 400 Bad request, 401 Unauthorised, 403 Forbidden, 429 Too many requests, as problem details (application/problem+json).
Get onboarding progress
GET/api/v1/settings/onboarding
- Scopes
work:read
Responses
200 OK, application/json
Body: object (OnboardingStatus).
| Field | Type | Description |
|---|---|---|
onboardedrequired | boolean | |
onboardedAtrequired | string (date-time)nullable | |
stepsrequired | object (OnboardingSteps) | |
steps.firmDetailsrequired | boolean | |
steps.thresholdsrequired | boolean | |
steps.workflowrequired | boolean | |
steps.teamrequired | boolean | Someone else has joined. |
steps.clientsrequired | boolean | At least one client. |
steps.colleagueInvitedrequired | boolean | Someone else has joined, or has been invited (and the invitation not withdrawn). |
steps.bookkeepingConnectedrequired | boolean | At least one client is connected to its bookkeeping software (Xero, QuickBooks, Sage or FreeAgent). |
steps.engagementStartedrequired | boolean | At least one engagement has been started. |
Errors: 400 Bad request, 401 Unauthorised, 403 Forbidden, 429 Too many requests, as problem details (application/problem+json).
Complete or skip onboarding
POST/api/v1/settings/onboarding
- Scopes
settings:admin- Role
- Firm admin
- Access
- A signed-in Tolvi session only, never an API token.
complete finishes first-run setup and clears its saved progress. skip (“Finish later”) lets the firm into Tolvi and keeps the progress, so setup resumes where it was left.
Request body
Required. application/json: object (CompleteOnboarding).
| Field | Type | Description |
|---|---|---|
actionrequired | string (OnboardingAction) | One of: |
firmName | string | up to 200 characters |
offices | array of string | up to 50 items |
thresholds | object (FirmThresholds) | Movements at or above both thresholds need an explanation. New engagements copy these. |
thresholds.absolutePencerequired | integer | Integer pence (GBP). at least 0 |
thresholds.percentrequired | integer | 0 to 1000 |
defaultWorkflowId | string | Becomes the default workflow for every entity type. |
Responses
Errors: 400 Bad request, 401 Unauthorised, 403 Forbidden, 429 Too many requests, as problem details (application/problem+json).
Get first-run setup progress
GET/api/v1/settings/onboarding/progress
- Scopes
settings:admin- Role
- Firm admin
- Access
- A signed-in Tolvi session only, never an API token.
The step to resume at, how clients are being brought in and the invitations queued to send at the end. Firm admins, signed in to the web app.
Responses
200 OK, application/json
Body: object (OnboardingProgress).
First-run setup saved as it goes, so it resumes where it was left. Firm details, thresholds and workflows are saved to the settings themselves; this keeps the step reached, how clients are being brought in, and the invitations queued to send on the last step.
| Field | Type | Description |
|---|---|---|
steprequired | string (OnboardingStep) | The step to resume at. One of: |
clientSourcerequired | string (OnboardingClientSource)nullable | How clients are being brought in; null until chosen. One of: |
invitationsrequired | array of QueuedInvitation | up to 50 items |
invitations[].emailrequired | string (email) | up to 254 characters |
invitations[].staffRolerequired | string (StaffRole) | One of: |
updatedAtrequired | string (date-time)nullable | When it was last saved; null when nothing has been saved yet. |
Errors: 400 Bad request, 401 Unauthorised, 403 Forbidden, 429 Too many requests, as problem details (application/problem+json).
Save first-run setup progress
PUT/api/v1/settings/onboarding/progress
- Scopes
settings:admin- Role
- Firm admin
- Access
- A signed-in Tolvi session only, never an API token.
Saves the step reached and the invitations queued so far; nothing is sent. The invitations go out when setup finishes, one POST /invitations each. Firm admins, signed in to the web app.
Request body
Required. application/json: object (SaveOnboardingProgress).
| Field | Type | Description |
|---|---|---|
steprequired | string (OnboardingStep) | The step to resume at. One of: |
clientSource | string (OnboardingClientSource)nullable | How clients are being brought in; null until chosen. One of: |
invitations | array of QueuedInvitation | Replaces the queued invitations when given. up to 50 items |
invitations[].emailrequired | string (email) | up to 254 characters |
invitations[].staffRolerequired | string (StaffRole) | One of: |
Responses
200 OK, application/json
Body: object (OnboardingProgress).
First-run setup saved as it goes, so it resumes where it was left. Firm details, thresholds and workflows are saved to the settings themselves; this keeps the step reached, how clients are being brought in, and the invitations queued to send on the last step.
The fields are as shown above.
Errors: 400 Bad request, 401 Unauthorised, 403 Forbidden, 429 Too many requests, as problem details (application/problem+json).
List workflow templates (presets and the firm’s own)
GET/api/v1/settings/workflows
- Scopes
settings:read
Responses
200 OK, application/json
Body: array of WorkflowTemplate.
| Field | Type | Description |
|---|---|---|
[].idrequired | string | A preset id (preset-…) or the firm template’s uuid. |
[].namerequired | string | |
[].builtinrequired | boolean | A Tolvi preset (read only). |
[].versionrequired | integer | |
[].stagesrequired | array of WorkflowTemplateStage | |
[].stages[].id | string | Stage id (read only). |
[].stages[].namerequired | string | up to 100 characters |
[].stages[].rolerequired | string (WorkflowStageRole) | One of: |
[].stages[].mustDifferrequired | boolean | Must be a different person from every earlier stage. |
[].stages[].scope | string (StageScope) | Default both. One of: |
Errors: 400 Bad request, 401 Unauthorised, 403 Forbidden, 429 Too many requests, as problem details (application/problem+json).
Replace the firm’s workflow templates
PUT/api/v1/settings/workflows
- Scopes
settings:admin- Role
- Firm admin
- Access
- A signed-in Tolvi session only, never an API token.
Validated with @tolvi/workflow. Engagements already started keep the template they started with.
Request body
Required. application/json: object (SetWorkflowTemplates).
The firm’s templates (presets are always available). Templates left out are archived.
| Field | Type | Description |
|---|---|---|
templatesrequired | array of WorkflowTemplateInput | up to 20 items |
templates[].id | string (uuid) | Keep to update an existing template. |
templates[].namerequired | string | up to 100 characters |
templates[].stagesrequired | array of WorkflowTemplateStage | 1 to 8 items |
templates[].stages[].id | string | Stage id (read only). |
templates[].stages[].namerequired | string | up to 100 characters |
templates[].stages[].rolerequired | string (WorkflowStageRole) | One of: |
templates[].stages[].mustDifferrequired | boolean | Must be a different person from every earlier stage. |
templates[].stages[].scope | string (StageScope) | Default both. One of: |
Responses
Errors: 400 Bad request, 401 Unauthorised, 403 Forbidden, 429 Too many requests, as problem details (application/problem+json).
List the firm’s people with their roles, capacity and open work
GET/api/v1/members
- Scopes
settings:read
Responses
200 OK, application/json
Body: array of Member.
| Field | Type | Description |
|---|---|---|
[].idrequired | string (uuid) | |
[].namerequired | string | |
[].emailrequired | string | |
[].initialsrequired | string | |
[].rolerequired | string (MembershipRole) | One of: |
[].staffRolerequired | string (StaffRole)nullable | One of: |
[].isAdminrequired | boolean | |
[].capacityrequired | integernullable | |
[].openEngagementsrequired | integer | Open engagements where it is their turn. |
[].openOnTeam | integer | Open engagements they are on in any role (preparer, reviewer, manager or partner), each counted once. |
[].openByRole | object (OpenByRole) | Open engagements they are on, by role. |
[].openByRole.preparerrequired | integer | |
[].openByRole.reviewerrequired | integer | |
[].openByRole.managerrequired | integer | |
[].openByRole.partnerrequired | integer | |
[].joinedAtrequired | string (date-time) |
Errors: 400 Bad request, 401 Unauthorised, 403 Forbidden, 429 Too many requests, as problem details (application/problem+json).
Remove someone from the firm
DELETE/api/v1/members/{userId}
- Scopes
settings:admin- Role
- Firm admin
- Access
- A signed-in Tolvi session only, never an API token.
They lose access at once and leave the firm’s sign-in organisation. Only an owner can remove an owner; you can’t remove yourself.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
userIdrequired | path | string (uuid) |
Responses
204 No content
Removed.
Errors: 400 Bad request, 401 Unauthorised, 403 Forbidden, 404 Not found, 429 Too many requests, as problem details (application/problem+json).