Skip to main content
BETA
MenuClose

Invitations

7 operations in the Tolvi API, version 1. Paths are relative to https://api.tolvi.co.uk. Every amount is integer pence.

List the firm’s invitations

GET/api/v1/invitations

Scopes
settings:admin
Role
Firm admin

Responses

200 OK, application/json

Body: array of Invitation.

200 OK response for GET /api/v1/invitations
FieldTypeDescription
[].​idrequiredstring (uuid)
[].​emailrequiredstring (email)
[].​rolerequiredstring (MembershipRole)

One of: owner, admin, staff

[].​staffRolerequiredstring (StaffRole)nullable

One of: partner, manager, reviewer, preparer, admin

[].​statusrequiredstring (InvitationStatus)

One of: pending, accepted, revoked, expired

[].​expiresAtrequiredstring (date-time)
[].​createdAtrequiredstring (date-time)

Errors: 400 Bad request, 401 Unauthorised, 403 Forbidden, 429 Too many requests, as problem details (application/problem+json).

Invite someone to the firm

POST/api/v1/invitations

Scopes
settings:admin
Role
Firm admin
Access
A signed-in Tolvi session only, never an API token.
Retries
Send an Idempotency-Key to make retries safe.

Emails them a single-use link. Web sessions only; you can’t grant a higher role than your own (owners excepted).

Parameters

Parameters for POST /api/v1/invitations
NameInTypeDescription
Idempotency-Keyheaderstring

A unique key (1-255 visible characters) to make retries safe. Replayed for 24 hours.

1 to 255 characters

Request body

Required. application/json: object (CreateInvitationRequest).

Request body for POST /api/v1/invitations
FieldTypeDescription
emailrequiredstring (email)

up to 254 characters

staffRolerequiredstring (StaffRole)

One of: partner, manager, reviewer, preparer, admin

rolestring (MembershipRole)

One of: owner, admin, staff

default "staff"

Responses

201 Created, application/json

Body: object (Invitation).

201 Created response for POST /api/v1/invitations
FieldTypeDescription
idrequiredstring (uuid)
emailrequiredstring (email)
rolerequiredstring (MembershipRole)

One of: owner, admin, staff

staffRolerequiredstring (StaffRole)nullable

One of: partner, manager, reviewer, preparer, admin

statusrequiredstring (InvitationStatus)

One of: pending, accepted, revoked, expired

expiresAtrequiredstring (date-time)
createdAtrequiredstring (date-time)

Errors: 400 Bad request, 401 Unauthorised, 403 Forbidden, 409 Conflict, 422 Unprocessable content, 429 Too many requests, as problem details (application/problem+json).

Revoke a pending invitation

POST/api/v1/invitations/{id}/revoke

Scopes
settings:admin
Role
Firm admin
Retries
Send an Idempotency-Key to make retries safe.

Parameters

Parameters for POST /api/v1/invitations/{id}/revoke
NameInTypeDescription
idrequiredpathstring (uuid)
Idempotency-Keyheaderstring

A unique key (1-255 visible characters) to make retries safe. Replayed for 24 hours.

1 to 255 characters

Responses

200 OK, application/json

Body: object (Invitation).

The fields are as shown above.

Errors: 400 Bad request, 401 Unauthorised, 403 Forbidden, 404 Not found, 409 Conflict, 422 Unprocessable content, 429 Too many requests, as problem details (application/problem+json).

Accept an invitation

POST/api/v1/invitations/accept

Access
A signed-in Tolvi session only (no scope applies).

Needs a sign-in token, but no firm yet.

Request body

Required. application/json: object (AcceptInvitationRequest).

Request body for POST /api/v1/invitations/accept
FieldTypeDescription
tokenrequiredstring

The token from the invitation email.

pattern ^[A-Za-z0-9_-]{43}$

Responses

200 OK, application/json

Body: object (AcceptInvitationResult).

200 OK response for POST /api/v1/invitations/accept
FieldTypeDescription
firmIdrequiredstring (uuid)
firmNamerequiredstring
authOrgIdstringnullable

The firm’s identity-provider organisation, if it has one. Sign in through it to open the firm.

Errors: 400 Bad request, 401 Unauthorised, 403 Forbidden, 429 Too many requests, as problem details (application/problem+json).

Preview an invitation

POST/api/v1/invitations/preview

Access
No authentication.

What the link in an invitation email says, before signing in: the firm, who sent it, the role, when it expires and whether it can still be used (pending, accepted, revoked or expired). The address it was sent to comes back mostly hidden. No sign-in needed: the invitation token goes in the body, never in the URL. 404 for a token Tolvi doesn’t recognise. Rate limited per IP.

Request body

Required. application/json: object (AcceptInvitationRequest).

Request body for POST /api/v1/invitations/preview
FieldTypeDescription
tokenrequiredstring

The token from the invitation email.

pattern ^[A-Za-z0-9_-]{43}$

Responses

200 OK, application/json

Body: object (InvitationPreview).

What an invitation link says before anyone signs in: the firm, who sent it, the role and whether it can still be used.

200 OK response for POST /api/v1/invitations/preview
FieldTypeDescription
statusrequiredstring (InvitationStatus)

One of: pending, accepted, revoked, expired

firmNamerequiredstring
rolerequiredstring (MembershipRole)

One of: owner, admin, staff

staffRolerequiredstring (StaffRole)nullable

One of: partner, manager, reviewer, preparer, admin

invitedByNamerequiredstringnullable
emailHintrequiredstring

The invited address, mostly hidden: “s•••@hartwell.co.uk”. Sign in with the full address.

expiresAtrequiredstring (date-time)
tenantKindstring (TenantKind)

Which kind of tenant it joins: a practice opens in the Tolvi web app, a business in Tolvi Books.

One of: practice, business

appUrlstring

The address of the Tolvi app this invitation opens in (server configuration).

Errors: 400 Bad request, 429 Too many requests, as problem details (application/problem+json).

Accept one of your own pending invitations

POST/api/v1/invitations/{id}/accept-for-me

Access
A signed-in Tolvi session only (no scope applies).

For a signed-in person with no firm yet: accepts an invitation from GET /me/pending-invitations without the emailed token. The invitation must have been sent to your email address, and your sign-in provider must have verified it. Each invitation can be accepted once. Sign-in tokens from the Tolvi web app only.

Parameters

Parameters for POST /api/v1/invitations/{id}/accept-for-me
NameInTypeDescription
idrequiredpathstring (uuid)

Responses

200 OK, application/json

Body: object (AcceptInvitationResult).

200 OK response for POST /api/v1/invitations/{id}/accept-for-me
FieldTypeDescription
firmIdrequiredstring (uuid)
firmNamerequiredstring
authOrgIdstringnullable

The firm’s identity-provider organisation, if it has one. Sign in through it to open the firm.

Errors: 400 Bad request, 401 Unauthorised, 403 Forbidden, 404 Not found, 429 Too many requests, as problem details (application/problem+json).

List invitations waiting for you

GET/api/v1/me/pending-invitations

Access
A signed-in Tolvi session only (no scope applies).

Pending, unexpired invitations sent to your verified email address, with the firm, role and who sent them. Empty when your sign-in provider has not verified your email. Sign-in tokens from the Tolvi web app only.

Responses

200 OK, application/json

Body: array of PendingInvitation.

An invitation waiting for the signed-in person, matched on their verified email address.

200 OK response for GET /api/v1/me/pending-invitations
FieldTypeDescription
[].​idrequiredstring (uuid)

Accept it with POST /invitations/{id}/accept-for-me.

[].​firmNamerequiredstring
[].​rolerequiredstring (MembershipRole)

One of: owner, admin, staff

[].​staffRolerequiredstring (StaffRole)nullable

One of: partner, manager, reviewer, preparer, admin

[].​invitedByNamerequiredstringnullable
[].​expiresAtrequiredstring (date-time)

Errors: 401 Unauthorised, 403 Forbidden, 429 Too many requests, as problem details (application/problem+json).