Skip to main content
BETA
MenuClose

Review points

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

List review points

GET/api/v1/engagements/{id}/review-points

Scopes
engagements:read

Part of the working_papers product: the firm must have it and you must have access to it.

Parameters

Parameters for GET /api/v1/engagements/{id}/review-points
NameInTypeDescription
idrequiredpathstring (uuid)

Engagement id.

sectionquerystring

One of: A, B, C, D, E, F, G, H, I, J, K, L, M, T, X, Z

statusquerystring

One of: open, answered, cleared, reopened, outstanding

Responses

200 OK, application/json

Body: array of ReviewPoint.

200 OK response for GET /api/v1/engagements/{id}/review-points
FieldTypeDescription
[].​idrequiredstring (uuid)
[].​sectionCoderequiredstringnullable

Null for a point on the engagement as a whole.

[].​categoryrequiredstring (ReviewPointCategory)

One of: query, error, presentation, missing_evidence

[].​statusrequiredstring (ReviewPointStatus)

One of: open, answered, cleared, reopened

[].​raisedAtStageIdrequiredstring
[].​raisedInRoundrequiredinteger

at least 1

[].​raisedByrequiredstring (uuid)nullable
[].​raisedAtrequiredstring (date-time)
[].​clearedByrequiredstring (uuid)nullable
[].​clearedAtrequiredstring (date-time)nullable
[].​sourceMeetingIdstring (uuid)nullable

The meeting whose next step this point came from (Create follow-ups in Tolvi Meetings), if any.

[].​messagesrequiredarray of ReviewPointMessage
[].​messages[].​idrequiredstring (uuid)
[].​messages[].​kindrequiredstring (ReviewPointMessageKind)

One of: raise, comment, answer, clear, reopen

[].​messages[].​authorIdrequiredstring (uuid)nullable
[].​messages[].​bodyrequiredstring
[].​messages[].​mentionsrequiredarray of string (uuid)
[].​messages[].​atrequiredstring (date-time)
[].​messages[].​evidencerequiredarray of Evidence
[].​messages[].​evidence[].​idrequiredstring (uuid)
[].​messages[].​evidence[].​sectionCoderequiredstringnullable
[].​messages[].​evidence[].​checklistItemIdrequiredstring (uuid)nullable
[].​messages[].​evidence[].​reviewPointIdrequiredstring (uuid)nullable
[].​messages[].​evidence[].​reviewPointMessageIdrequiredstring (uuid)nullable
[].​messages[].​evidence[].​fileNamerequiredstring
[].​messages[].​evidence[].​contentTyperequiredstring
[].​messages[].​evidence[].​sizeBytesrequiredinteger

at least 0

[].​messages[].​evidence[].​statusrequiredstring (EvidenceStatus)

pending_upload until POST …/evidence/{evidenceId}/confirm checks the stored file; then pending_scan (malware scan) and available. Only available files can be downloaded or read by Tolvi AI. rejected: the file failed the checks or the scan found malware (see rejectedReason); it can never be downloaded.

One of: pending_upload, pending_scan, available, rejected

[].​messages[].​evidence[].​rejectedReasonrequiredstringnullable

Why a rejected file was rejected, e.g. "malware detected"; null otherwise.

[].​messages[].​evidence[].​uploadedByrequiredstring (uuid)nullable
[].​messages[].​evidence[].​createdAtrequiredstring (date-time)

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

Raise a review point

POST/api/v1/engagements/{id}/review-points

Scopes
review:write and engagements:read
Role
Reviewer or above
Retries
Send an Idempotency-Key to make retries safe.

On reviewed work this withdraws the review sign-off. @mentions are notified.

Needs the Reviewer role or above. Part of the working_papers product: the firm must have it and you must have access to it.

Parameters

Parameters for POST /api/v1/engagements/{id}/review-points
NameInTypeDescription
idrequiredpathstring (uuid)

Engagement id.

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 (RaiseReviewPoint).

Request body for POST /api/v1/engagements/{id}/review-points
FieldTypeDescription
sectionCodestringnullable

Section code; omit or null for the engagement as a whole.

categoryrequiredstring (ReviewPointCategory)

One of: query, error, presentation, missing_evidence

bodyrequiredstring

@Full Name mentions are recognised.

1 to 4000 characters

mentionsarray of string (uuid)

People to mention, in addition to @names in the text.

up to 50 items

Responses

201 Created, application/json

Body: object (ReviewPoint).

201 Created response for POST /api/v1/engagements/{id}/review-points
FieldTypeDescription
idrequiredstring (uuid)
sectionCoderequiredstringnullable

Null for a point on the engagement as a whole.

categoryrequiredstring (ReviewPointCategory)

One of: query, error, presentation, missing_evidence

statusrequiredstring (ReviewPointStatus)

One of: open, answered, cleared, reopened

raisedAtStageIdrequiredstring
raisedInRoundrequiredinteger

at least 1

raisedByrequiredstring (uuid)nullable
raisedAtrequiredstring (date-time)
clearedByrequiredstring (uuid)nullable
clearedAtrequiredstring (date-time)nullable
sourceMeetingIdstring (uuid)nullable

The meeting whose next step this point came from (Create follow-ups in Tolvi Meetings), if any.

messagesrequiredarray of ReviewPointMessage
messages[].​idrequiredstring (uuid)
messages[].​kindrequiredstring (ReviewPointMessageKind)

One of: raise, comment, answer, clear, reopen

messages[].​authorIdrequiredstring (uuid)nullable
messages[].​bodyrequiredstring
messages[].​mentionsrequiredarray of string (uuid)
messages[].​atrequiredstring (date-time)
messages[].​evidencerequiredarray of Evidence
messages[].​evidence[].​idrequiredstring (uuid)
messages[].​evidence[].​sectionCoderequiredstringnullable
messages[].​evidence[].​checklistItemIdrequiredstring (uuid)nullable
messages[].​evidence[].​reviewPointIdrequiredstring (uuid)nullable
messages[].​evidence[].​reviewPointMessageIdrequiredstring (uuid)nullable
messages[].​evidence[].​fileNamerequiredstring
messages[].​evidence[].​contentTyperequiredstring
messages[].​evidence[].​sizeBytesrequiredinteger

at least 0

messages[].​evidence[].​statusrequiredstring (EvidenceStatus)

pending_upload until POST …/evidence/{evidenceId}/confirm checks the stored file; then pending_scan (malware scan) and available. Only available files can be downloaded or read by Tolvi AI. rejected: the file failed the checks or the scan found malware (see rejectedReason); it can never be downloaded.

One of: pending_upload, pending_scan, available, rejected

messages[].​evidence[].​rejectedReasonrequiredstringnullable

Why a rejected file was rejected, e.g. "malware detected"; null otherwise.

messages[].​evidence[].​uploadedByrequiredstring (uuid)nullable
messages[].​evidence[].​createdAtrequiredstring (date-time)

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

Get a review point with its thread

GET/api/v1/engagements/{id}/review-points/{pointId}

Scopes
engagements:read

Part of the working_papers product: the firm must have it and you must have access to it.

Parameters

Parameters for GET /api/v1/engagements/{id}/review-points/{pointId}
NameInTypeDescription
idrequiredpathstring (uuid)

Engagement id.

pointIdrequiredpathstring (uuid)

Responses

200 OK, application/json

Body: object (ReviewPoint).

The fields are as shown above.

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

Comment on a review point

POST/api/v1/engagements/{id}/review-points/{pointId}/comments

Scopes
engagements:write and engagements:read
Retries
Send an Idempotency-Key to make retries safe.

With @mentions and evidence uploaded for the point. Part of the working_papers product: the firm must have it and you must have access to it.

Parameters

Parameters for POST /api/v1/engagements/{id}/review-points/{pointId}/comments
NameInTypeDescription
idrequiredpathstring (uuid)

Engagement id.

pointIdrequiredpathstring (uuid)
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 (ReviewPointReply).

Request body for POST /api/v1/engagements/{id}/review-points/{pointId}/comments
FieldTypeDescription
bodystring

up to 4000 characters

mentionsarray of string (uuid)

up to 50 items

evidenceIdsarray of string (uuid)

Evidence uploaded for this review point, attached to the reply.

up to 20 items

Responses

201 Created, application/json

Body: object (ReviewPoint).

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

Answer a review point

POST/api/v1/engagements/{id}/review-points/{pointId}/answer

Scopes
engagements:write and engagements:read

Moves an open or reopened point to answered. Part of the working_papers product: the firm must have it and you must have access to it.

Parameters

Parameters for POST /api/v1/engagements/{id}/review-points/{pointId}/answer
NameInTypeDescription
idrequiredpathstring (uuid)

Engagement id.

pointIdrequiredpathstring (uuid)

Request body

Required. application/json: object (ReviewPointReply).

Request body for POST /api/v1/engagements/{id}/review-points/{pointId}/answer
FieldTypeDescription
bodystring

up to 4000 characters

mentionsarray of string (uuid)

up to 50 items

evidenceIdsarray of string (uuid)

Evidence uploaded for this review point, attached to the reply.

up to 20 items

Responses

200 OK, application/json

Body: object (ReviewPoint).

The fields are as shown above.

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

Clear a review point

POST/api/v1/engagements/{id}/review-points/{pointId}/clear

Scopes
review:write and engagements:read
Role
Reviewer or above

Only the stage that raised it, or a later one.

Needs the Reviewer role or above. Part of the working_papers product: the firm must have it and you must have access to it.

Parameters

Parameters for POST /api/v1/engagements/{id}/review-points/{pointId}/clear
NameInTypeDescription
idrequiredpathstring (uuid)

Engagement id.

pointIdrequiredpathstring (uuid)

Request body

Required. application/json: object (ReviewPointAction).

Request body for POST /api/v1/engagements/{id}/review-points/{pointId}/clear
FieldTypeDescription
bodystring

Required to reopen.

up to 4000 characters

Responses

200 OK, application/json

Body: object (ReviewPoint).

The fields are as shown above.

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

Reopen a review point

POST/api/v1/engagements/{id}/review-points/{pointId}/reopen

Scopes
review:write and engagements:read
Role
Reviewer or above

An answered or cleared point, with a message saying why.

Needs the Reviewer role or above. Part of the working_papers product: the firm must have it and you must have access to it.

Parameters

Parameters for POST /api/v1/engagements/{id}/review-points/{pointId}/reopen
NameInTypeDescription
idrequiredpathstring (uuid)

Engagement id.

pointIdrequiredpathstring (uuid)

Request body

Required. application/json: object (ReviewPointAction).

Request body for POST /api/v1/engagements/{id}/review-points/{pointId}/reopen
FieldTypeDescription
bodystring

Required to reopen.

up to 4000 characters

Responses

200 OK, application/json

Body: object (ReviewPoint).

The fields are as shown above.

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