Working paper file
4 operations in the Tolvi API, version 1. Paths are relative to https://api.tolvi.co.uk. Every amount is integer pence.
List the engagement’s working paper file exports, newest first
GET/api/v1/engagements/{id}/exports
- Scopes
engagements:read
Part of the working_papers product: the firm must have it and you must have access to it.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
idrequired | path | string (uuid) | Engagement id. |
Responses
200 OK, application/json
Body: array of WorkingPaperExport.
One generated working paper file (PDF), versioned per engagement. Rendered in the background: poll until status is ready (or failed). A ready file is outdated once a section is signed, approved, returned or reopened, or its content changes, after it was generated.
| Field | Type | Description |
|---|---|---|
[].idrequired | string (uuid) | |
[].engagementIdrequired | string (uuid) | |
[].versionrequired | integer | 1, 2, 3… per engagement. |
[].statusrequired | string (WorkingPaperExportStatus) | One of: |
[].requestedByrequired | string (uuid)nullable | |
[].requestedAtrequired | string (date-time) | |
[].startedAtrequired | string (date-time)nullable | |
[].completedAtrequired | string (date-time)nullable | |
[].errorrequired | stringnullable | Why rendering failed. |
[].fileNamerequired | stringnullable | |
[].sizeBytesrequired | integernullable | |
[].sha256required | stringnullable | Hex SHA-256 of the PDF. |
[].pageCountrequired | integernullable | |
[].outdatedrequired | boolean | Ready, but the engagement has been signed or changed since. |
[].outdatedReasonsrequired | array of string | What changed since the file was generated, oldest first. |
[].draftrequired | stringnullable | Ready, but not fully signed off when generated: the draft notice printed on its cover and footer, such as "Draft – not signed off: 15 of 16 sections not signed off." Null when it was signed off (or generated before this was recorded). |
[].unsignedSectionsrequired | integer | With draft: how many sections were not signed off at every stage (0 when only the engagement approval was missing). at least 0 |
[].options | object (WorkingPaperExportOptions)nullable | What was asked for; null for the whole file. |
[].options.sections | array of string | Section codes (W/P refs) to include, in file order. Omit for every section. up to 30 items |
[].options.evidence | boolean | The appendix listing evidence files with their checksums. Default true. |
[].options.reviewPoints | boolean | Review point threads (the review point log), on each section and the engagement. Default true. |
[].options.auditTrail | boolean | The review history and workflow timeline (the audit trail of sign-offs, approvals, returns and declarations). Default true. |
Errors: 400 Bad request, 401 Unauthorised, 403 Forbidden, 404 Not found, 429 Too many requests, as problem details (application/problem+json).
Export the working paper file
POST/api/v1/engagements/{id}/exports
- Scopes
engagements:read- Retries
- Send an
Idempotency-Keyto make retries safe.
Queues a PDF of the whole file: cover with sign-off summary, index, every section in order (lead schedule, variance notes, tickmarks with legend, checklist, reconciliations, review point threads, sign-offs), journals, tax computation, draft accounts, review history and an appendix of evidence files with checksums. Rendering happens in the background: poll the export until it is ready. While one is queued or rendering, that one is returned. Optionally choose the sections and leave out the evidence appendix, the review point threads or the review history; the cover then says what was left out. A file that is not fully signed off prints with a “Draft – not signed off” banner. Part of the working_papers product: the firm must have it and you must have access to it.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
idrequired | path | string (uuid) | Engagement id. |
Idempotency-Key | header | string | A unique key (1-255 visible characters) to make retries safe. Replayed for 24 hours. 1 to 255 characters |
Request body
Optional. application/json: object (WorkingPaperExportOptions).
What the file contains. Everything is included unless left out here.
| Field | Type | Description |
|---|---|---|
sections | array of string | Section codes (W/P refs) to include, in file order. Omit for every section. up to 30 items |
evidence | boolean | The appendix listing evidence files with their checksums. Default true. |
reviewPoints | boolean | Review point threads (the review point log), on each section and the engagement. Default true. |
auditTrail | boolean | The review history and workflow timeline (the audit trail of sign-offs, approvals, returns and declarations). Default true. |
Responses
202 Accepted, application/json
Body: object (WorkingPaperExport).
One generated working paper file (PDF), versioned per engagement. Rendered in the background: poll until status is ready (or failed). A ready file is outdated once a section is signed, approved, returned or reopened, or its content changes, after it was generated.
| Field | Type | Description |
|---|---|---|
idrequired | string (uuid) | |
engagementIdrequired | string (uuid) | |
versionrequired | integer | 1, 2, 3… per engagement. |
statusrequired | string (WorkingPaperExportStatus) | One of: |
requestedByrequired | string (uuid)nullable | |
requestedAtrequired | string (date-time) | |
startedAtrequired | string (date-time)nullable | |
completedAtrequired | string (date-time)nullable | |
errorrequired | stringnullable | Why rendering failed. |
fileNamerequired | stringnullable | |
sizeBytesrequired | integernullable | |
sha256required | stringnullable | Hex SHA-256 of the PDF. |
pageCountrequired | integernullable | |
outdatedrequired | boolean | Ready, but the engagement has been signed or changed since. |
outdatedReasonsrequired | array of string | What changed since the file was generated, oldest first. |
draftrequired | stringnullable | Ready, but not fully signed off when generated: the draft notice printed on its cover and footer, such as "Draft – not signed off: 15 of 16 sections not signed off." Null when it was signed off (or generated before this was recorded). |
unsignedSectionsrequired | integer | With draft: how many sections were not signed off at every stage (0 when only the engagement approval was missing). at least 0 |
options | object (WorkingPaperExportOptions)nullable | What was asked for; null for the whole file. |
options.sections | array of string | Section codes (W/P refs) to include, in file order. Omit for every section. up to 30 items |
options.evidence | boolean | The appendix listing evidence files with their checksums. Default true. |
options.reviewPoints | boolean | Review point threads (the review point log), on each section and the engagement. Default true. |
options.auditTrail | boolean | The review history and workflow timeline (the audit trail of sign-offs, approvals, returns and declarations). Default true. |
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 one export (poll this while it renders)
GET/api/v1/engagements/{id}/exports/{exportId}
- Scopes
engagements:read
Part of the working_papers product: the firm must have it and you must have access to it.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
idrequired | path | string (uuid) | Engagement id. |
exportIdrequired | path | string (uuid) |
Responses
200 OK, application/json
Body: object (WorkingPaperExport).
One generated working paper file (PDF), versioned per engagement. Rendered in the background: poll until status is ready (or failed). A ready file is outdated once a section is signed, approved, returned or reopened, or its content changes, after it was generated.
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).
Get a short-lived download URL for a ready export
GET/api/v1/engagements/{id}/exports/{exportId}/download
- Scopes
engagements:read
409 while it is still rendering, or if it failed. Part of the working_papers product: the firm must have it and you must have access to it.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
idrequired | path | string (uuid) | Engagement id. |
exportIdrequired | path | string (uuid) |
Responses
200 OK, application/json
Body: object (PresignedUpload).
| Field | Type | Description |
|---|---|---|
urlrequired | string (uri) | |
methodrequired | string (PresignedMethod) | One of: |
headersrequired | object | Headers to send with the request. |
expiresAtrequired | string (date-time) |
Errors: 400 Bad request, 401 Unauthorised, 403 Forbidden, 404 Not found, 429 Too many requests, as problem details (application/problem+json).