Corporation Tax

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

List returns

GET/api/v1/corporation-tax/returns

Scopes: corporation_tax:read

Every company’s returns, latest period first. Filter by client or status. Part of the corporation_tax product: the firm must have it and you must have access to it.

Parameters

Parameters for GET /api/v1/corporation-tax/returns
Name	In	Type	Description
`status`	query	`string`	One of: `draft`, `in_review`, `approved`, `filing`, `filed`
`clientId`	query	`string (uuid)`

Responses

200 OK, `application/json`

Body: object (CtReturnList).

200 OK response for GET /api/v1/corporation-tax/returns
Field	Type	Description
`items`required	`array of CtReturnRow`
`items[].id`required	`string (uuid)`
`items[].clientId`required	`string (uuid)`
`items[].clientName`required	`string`
`items[].groupId`required	`string (uuid)`	Shared by the returns of one period of account.
`items[].periodOfAccountStart`required	`string (date)`	example "2026-03-31"
`items[].periodOfAccountEnd`required	`string (date)`	example "2026-03-31"
`items[].periodStart`required	`string (date)`	example "2026-03-31"
`items[].periodEnd`required	`string (date)`	example "2026-03-31"
`items[].periodIndex`required	`integer`	This return’s place among the accounting periods, from 0.
`items[].periodCount`required	`integer`
`items[].status`required	`string (CtReturnStatus)`	One of: `draft`, `in_review`, `approved`, `filing`, `filed`
`items[].source`required	`string (CtSource)`	One of: `typed`, `working_papers`, `accounts`
`items[].dueDate`required	`string (date)`	When the return is due (FA 1998 Sch 18 para 14). example "2026-03-31"
`items[].openReviewPoints`required	`integer`
`items[].taxDue`required	`integer`nullable	Tax still to pay on this return, in integer pence, negative when overpaid. Null until it has figures the tax engine can work out.
`items[].clientConfirmationCurrent`required	`boolean`	The client confirmed these figures, not earlier ones.
`items[].lastSubmissionStatus`required	`string (CtSubmissionStatus)`nullable	How the latest attempt to send this return ended. Null if it has never been sent. One of: `pending`, `acknowledged`, `accepted`, `rejected`, `unknown`
`items[].filingEnabled`required	`boolean`	Whether filing is switched on: off until HMRC’s test service passes.
`items[].returnType`required	`string (CtReturnType)`	What goes in the XML’s `ReturnType`. One of: `new`, `amended`
`items[].amendsReturnId`required	`string (uuid)`nullable	The return this amends. That one stays unchanged.
`items[].amendmentNumber`required	`integer`	1 for the first amendment. Nil on a new return.
`items[].filedElsewhereOn`required	`string (date)`nullable	A person recorded it as filed outside Tolvi on this day. example "2026-03-31"
`items[].updatedAt`required	`string (date-time)`

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

Start a return

POST/api/v1/corporation-tax/returns

Scopes: corporation_tax:write
Role: Preparer or above
Retries: Send an Idempotency-Key to make retries safe.

Preparers and above, for limited companies. A period of account over 12 months makes one return per accounting period; this answers with the first, and relatedReturns names the rest. Accounting periods starting before 1 April 2023 are refused with 422. No Working Papers file or Accounts set is needed.

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

Parameters

Parameters for POST /api/v1/corporation-tax/returns
Name	In	Type	Description
`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

Required. application/json: object (CreateCtReturnRequest).

A period of account over 12 months makes one return for each accounting period.

Request body for POST /api/v1/corporation-tax/returns
Field	Type	Description
`clientId`required	`string (uuid)`
`periodStart`required	`string (date)`	Start of the period of account. Accounting periods starting before 1 April 2023 are refused. example "2026-03-31"
`periodEnd`required	`string (date)`	End of the period of account, at most 18 months on. example "2026-03-31"

Responses

201 Created, `application/json`

Body: object (CtReturn).

A Company Tax Return for one accounting period, with its boxes, computation and what stands in the way of filing.

201 Created response for POST /api/v1/corporation-tax/returns
Field	Type	Description
`id`required	`string (uuid)`
`clientId`required	`string (uuid)`
`clientName`required	`string`
`groupId`required	`string (uuid)`	Shared by the returns of one period of account.
`periodOfAccountStart`required	`string (date)`	example "2026-03-31"
`periodOfAccountEnd`required	`string (date)`	example "2026-03-31"
`periodStart`required	`string (date)`	example "2026-03-31"
`periodEnd`required	`string (date)`	example "2026-03-31"
`periodIndex`required	`integer`	This return’s place among the accounting periods, from 0.
`periodCount`required	`integer`
`status`required	`string (CtReturnStatus)`	One of: `draft`, `in_review`, `approved`, `filing`, `filed`
`source`required	`string (CtSource)`	One of: `typed`, `working_papers`, `accounts`
`dueDate`required	`string (date)`	When the return is due (FA 1998 Sch 18 para 14). example "2026-03-31"
`openReviewPoints`required	`integer`
`taxDue`required	`integer`nullable	Tax still to pay on this return, in integer pence, negative when overpaid. Null until it has figures the tax engine can work out.
`clientConfirmationCurrent`required	`boolean`	The client confirmed these figures, not earlier ones.
`lastSubmissionStatus`required	`string (CtSubmissionStatus)`nullable	How the latest attempt to send this return ended. Null if it has never been sent. One of: `pending`, `acknowledged`, `accepted`, `rejected`, `unknown`
`filingEnabled`required	`boolean`	Whether filing is switched on: off until HMRC’s test service passes.
`returnType`required	`string (CtReturnType)`	What goes in the XML’s `ReturnType`. One of: `new`, `amended`
`amendsReturnId`required	`string (uuid)`nullable	The return this amends. That one stays unchanged.
`amendmentNumber`required	`integer`	1 for the first amendment. Nil on a new return.
`filedElsewhereOn`required	`string (date)`nullable	A person recorded it as filed outside Tolvi on this day. example "2026-03-31"
`updatedAt`required	`string (date-time)`
`recordFacts`	`object (CompanyFacts)`	What the client’s record says now, to compare with what the return states.
`recordFacts.name`required	`string`nullable	The client’s name on the record.
`recordFacts.companyNumber`required	`string`nullable	Companies House number on the record.
`recordFacts.registeredOffice`required	`string`nullable
`recordFacts.principalActivity`required	`string`nullable
`recordFacts.signatoryName`required	`string`nullable	The record’s, or the only serving director.
`recordFacts.directors`required	`array of RecordDirector`	Contacts whose role says director.
`recordFacts.directors[].name`required	`string`
`recordFacts.directors[].appointedOn`	`string (date)`	example "2026-03-31"
`recordFacts.directors[].resignedOn`	`string (date)`	example "2026-03-31"
`boxes`required	`object`nullable	{ boxes, financialYears, loans }: CT600 and CT600A boxes by number. Money is integer pence, whole pounds where the form says so. Bank details are masked. Null without figures.
`problems`required	`array of CtProblem`
`problems[].severity`required	`string (CtProblemSeverity)`	block: stops filing, not approving or downloading. warn: a person should look. One of: `block`, `warn`
`problems[].code`required	`string`
`problems[].box`	`string`
`problems[].area`required	`string (CtProblemArea)`	One of: `ct600`, `computation`, `accounts`, `source`, `xml`
`problems[].message`required	`string`
`computation`required	`object`nullable	The engine’s computation for this accounting period, with the period of account’s adjustments. Null without figures.
`input`required	`object`nullable	The engine input now held, in integer pence.
`facts`required	`object`	What a person has answered.
`masks`required	`object`	Masked bank details.
`sourceState`required	`object (CtSourceState)`
`sourceState.source`required	`string (CtSource)`	One of: `typed`, `working_papers`, `accounts`
`sourceState.engagementId`required	`string (uuid)`nullable
`sourceState.accountsSetId`required	`string (uuid)`nullable
`sourceState.sourceChanged`required	`boolean`	A linked source differs from what this return holds. The figures here haven’t moved: refresh to bring the change in.
`sourceState.sourceApproved`required	`boolean`nullable	Whether the linked file or set is approved. Null with nothing linked.
`sourceState.message`required	`string`nullable
`sourceChanged`required	`boolean`
`versions`required	`array of CtInputVersion`
`versions[].id`required	`string (uuid)`
`versions[].version`required	`integer`
`versions[].source`required	`string (CtSource)`	One of: `typed`, `working_papers`, `accounts`
`versions[].fingerprint`required	`string`
`versions[].sourceLabel`required	`string`nullable
`versions[].createdByName`required	`string`nullable
`versions[].createdAt`required	`string (date-time)`
`relatedReturns`required	`array of CtRelatedReturn`	The other returns of a long period of account.
`relatedReturns[].id`required	`string (uuid)`
`relatedReturns[].periodStart`required	`string (date)`	example "2026-03-31"
`relatedReturns[].periodEnd`required	`string (date)`	example "2026-03-31"
`relatedReturns[].status`required	`string (CtReturnStatus)`	One of: `draft`, `in_review`, `approved`, `filing`, `filed`
`returnHash`required	`string`	Send this back when approving: it fingerprints the return.
`utr`required	`string`nullable
`registrationNumber`required	`string`nullable
`approvedByName`required	`string`nullable
`approvedAt`required	`string (date-time)`nullable
`clientConfirmedOn`required	`string (date)`nullable	example "2026-03-31"
`approverRole`required	`string (ApproverRole)`	Who may approve in this firm: partners only, or managers and partners. One of: `partner`, `manager`
`reviewerNames`required	`array of string`	Who sending for review goes to, by name: the client’s partner, or every partner where the record names none, and its manager.
`canApprove`required	`boolean`
`cannotApproveReason`required	`string`nullable
`canFile`required	`boolean`	No blocker stands in the way of filing this return, whether or not filing is switched on.
`canSubmit`required	`boolean`
`cannotSubmitReason`required	`string`nullable
`filingMode`required	`string (CtFilingMode)`	One of: `test`, `test_in_live`, `live`
`declaration`required	`object`	{ version, text }: the declaration to accept before filing.
`rolledFromReturnId`required	`string (uuid)`nullable
`canAmend`required	`boolean`
`cannotAmendReason`required	`string`nullable
`lastAmendmentDay`required	`string (date)`	The last day this return can be amended: 12 months after its filing date (FA 1998 Sch 18 para 15(4)). example "2026-03-31"
`amendedByReturnId`required	`string (uuid)`nullable	The amendment of this return, once started.
`amendmentHistory`required	`array of CtAmendmentHistoryItem`	Every version of this return, oldest first. Each keeps its own review and approval.
`amendmentHistory[].id`required	`string (uuid)`
`amendmentHistory[].amendmentNumber`required	`integer`
`amendmentHistory[].status`required	`string (CtReturnStatus)`	One of: `draft`, `in_review`, `approved`, `filing`, `filed`
`amendmentHistory[].filedElsewhereOn`required	`string (date)`nullable	example "2026-03-31"
`amendmentHistory[].updatedAt`required	`string (date-time)`
`reviewPoints`required	`array of CtReviewPoint`
`reviewPoints[].id`required	`string (uuid)`
`reviewPoints[].box`required	`string`nullable
`reviewPoints[].text`required	`string`
`reviewPoints[].status`required	`string (CtReviewPointStatus)`	One of: `open`, `cleared`
`reviewPoints[].raisedByName`required	`string`nullable
`reviewPoints[].createdAt`required	`string (date-time)`
`events`required	`array of CtEvent`
`events[].id`required	`string (uuid)`
`events[].kind`required	`string`
`events[].actorName`required	`string`nullable
`events[].note`required	`string`nullable
`events[].createdAt`required	`string (date-time)`
`submissions`required	`array of CtSubmission`
`submissions[].id`required	`string (uuid)`
`submissions[].mode`required	`string (CtFilingMode)`	One of: `test`, `test_in_live`, `live`
`submissions[].status`required	`string (CtSubmissionStatus)`	How the latest attempt to send this return ended. Null if it has never been sent. One of: `pending`, `acknowledged`, `accepted`, `rejected`, `unknown`
`submissions[].correlationId`required	`string`nullable
`submissions[].irmark`required	`string`
`submissions[].errors`required	`array of object`nullable	HMRC’s errors: { number, text, location, meaning }. `meaning` says it in plain words.
`submissions[].message`required	`string`nullable	What happened, in plain words.
`submissions[].receiptAt`required	`string (date-time)`nullable
`submissions[].submittedByName`required	`string`nullable
`submissions[].createdAt`required	`string (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).

Get a return

GET/api/v1/corporation-tax/returns/{id}

Scopes: corporation_tax:read

The boxes, the computation, what would stop it being filed, where the figures came from, review points and history. canFile says whether anything blocks filing; filingEnabled whether filing is switched on. Bank details are only ever masked. Part of the corporation_tax product: the firm must have it and you must have access to it.

Parameters

Parameters for GET /api/v1/corporation-tax/returns/{id}
Name	In	Type	Description
`id`required	path	`string (uuid)`

Responses

200 OK, `application/json`

Body: object (CtReturn).

A Company Tax Return for one accounting period, with its boxes, computation and what stands in the way of filing.

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

Change a return

PATCH/api/v1/corporation-tax/returns/{id}

Scopes: corporation_tax:write
Role: Preparer or above

Preparers and above. Figures are a new immutable version, shared by every return of the period of account. Any change takes a reviewed or approved return back to draft. Figures from a linked source are refused with 409; refused once it’s with HMRC.

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

Parameters

Parameters for PATCH /api/v1/corporation-tax/returns/{id}
Name	In	Type	Description
`id`required	path	`string (uuid)`

Request body

Required. application/json: object (UpdateCtReturnRequest).

Request body for PATCH /api/v1/corporation-tax/returns/{id}
Field	Type	Description
`input`	`object`	Parts of the tax engine’s input to change, in integer pence. Applies to every return of the period of account. `researchAndDevelopment: null` removes a claim. Figures that come from a linked source can’t be changed here.
`facts`	`object`	Answers: declarationName, declarationStatus, exports, repaymentClaim, provisionalFigures, rnd (companySize, notificationSubmitted, additionalInformationSubmitted, payeReferences, connectedPayeReferences), amendment (accountsAlreadySubmitted, computationsAlreadySubmitted), outOfScope and so on.
`bank`	`object`nullable	Bank details for a repayment, or null to remove them. Encrypted, and only ever shown masked.
`note`	`string`

Responses

200 OK, `application/json`

Body: object (CtReturn).

A Company Tax Return for one accounting period, with its boxes, computation and what stands in the way of filing.

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

Group relief for a return

GET/api/v1/corporation-tax/returns/{id}/group-relief

Scopes: corporation_tax:read

Notices of consent touching this company, the companies its client record connects it with, and an associated company count from those links. The links are suggestions: nothing is applied, and the group test is what a person says. Part of the corporation_tax product: the firm must have it and you must have access to it.

Parameters

Parameters for GET /api/v1/corporation-tax/returns/{id}/group-relief
Name	In	Type	Description
`id`required	path	`string (uuid)`

Responses

200 OK, `application/json`

Body: object (CtGroupReliefState).

200 OK response for GET /api/v1/corporation-tax/returns/{id}/group-relief
Field	Type	Description
`notices`required	`array of CtGroupNotice`
`notices[].id`required	`string (uuid)`
`notices[].kind`required	`string`	One of: `current`, `carried_forward`
`notices[].surrenderingClientId`required	`string (uuid)`
`notices[].surrenderingName`required	`string`
`notices[].surrenderingUtr`required	`string`nullable
`notices[].claimantClientId`required	`string (uuid)`
`notices[].claimantName`required	`string`
`notices[].claimantUtr`required	`string`nullable
`notices[].surrenderPeriodStart`required	`string (date)`
`notices[].surrenderPeriodEnd`required	`string (date)`
`notices[].amountPence`required	`number`
`notices[].givenOn`required	`string (date)`
`notices[].status`required	`string`	One of: `given`, `withdrawn`
`notices[].gaps`required	`array of string`	What the notice lacks under FA 1998 Sch 18 para 71(1). A notice with gaps is ineffective.
`relatedCompanies`required	`array of CtGroupCompanySuggestion`	Companies the client record connects with this one. Suggestions: nothing is applied.
`relatedCompanies[].clientId`required	`string (uuid)`
`relatedCompanies[].name`required	`string`
`relatedCompanies[].utr`required	`string`nullable
`relatedCompanies[].why`required	`string`	How the client record connects the two. A pointer only.
`relatedCompanies[].looksLike75Percent`required	`boolean`	The links would meet 75% ownership if they’re complete. Never decides the group test.
`associatedCompaniesSuggested`required	`number`	A count from the links for boxes 326 to 328, for a person to accept or ignore. Never applied by itself.
`associatedCompaniesNote`required	`string`

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

Record a notice of consent

POST/api/v1/corporation-tax/returns/{id}/group-relief/notices

Scopes: corporation_tax:write
Role: Preparer or above
Retries: Send an Idempotency-Key to make retries safe.

Preparers and above. Records a notice given to HMRC, between this company and another client of the firm (FA 1998 Sch 18 para 70). A notice can’t be changed: withdraw it and record another. Recording it doesn’t change either return.

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

Parameters

Parameters for POST /api/v1/corporation-tax/returns/{id}/group-relief/notices
Name	In	Type	Description
`id`required	path	`string (uuid)`
`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

Required. application/json: object (CreateCtGroupNoticeRequest).

A notice of consent to surrender group relief, given to HMRC.

Request body for POST /api/v1/corporation-tax/returns/{id}/group-relief/notices
Field	Type	Description
`kind`required	`string`	One of: `current`, `carried_forward`
`thisCompanyIs`required	`string`	Which side this return’s company is on. One of: `surrendering`, `claimant`
`otherClientId`required	`string (uuid)`	The other company: a client of this firm.
`surrenderPeriod`	`object`	The surrendering company’s accounting period.
`surrenderPeriod.start`required	`string (date)`
`surrenderPeriod.end`required	`string (date)`
`amountPence`required	`number`	Whole pounds, in pence.
`givenOn`required	`string (date)`	When notice was given to HMRC (FA 1998 Sch 18 para 70(3)).

Responses

201 Created, `application/json`

Body: object (CtGroupNotice).

201 Created response for POST /api/v1/corporation-tax/returns/{id}/group-relief/notices
Field	Type	Description
`id`required	`string (uuid)`
`kind`required	`string`	One of: `current`, `carried_forward`
`surrenderingClientId`required	`string (uuid)`
`surrenderingName`required	`string`
`surrenderingUtr`required	`string`nullable
`claimantClientId`required	`string (uuid)`
`claimantName`required	`string`
`claimantUtr`required	`string`nullable
`surrenderPeriodStart`required	`string (date)`
`surrenderPeriodEnd`required	`string (date)`
`amountPence`required	`number`
`givenOn`required	`string (date)`
`status`required	`string`	One of: `given`, `withdrawn`
`gaps`required	`array of string`	What the notice lacks under FA 1998 Sch 18 para 71(1). A notice with gaps is ineffective.

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

Withdraw a notice of consent

POST/api/v1/corporation-tax/returns/{id}/group-relief/notices/{noticeId}/withdraw

Scopes: corporation_tax:write
Role: Preparer or above
Retries: Send an Idempotency-Key to make retries safe.

Preparers and above. A return that relies on it then can’t be filed until it’s replaced (FA 1998 Sch 18 para 71).

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

Parameters

Parameters for POST /api/v1/corporation-tax/returns/{id}/group-relief/notices/{noticeId}/withdraw
Name	In	Type	Description
`id`required	path	`string (uuid)`
`noticeId`required	path	`string (uuid)`
`Idempotency-Key`	header	`string`	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 (CtGroupNotice).

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

Link a source

POST/api/v1/corporation-tax/returns/{id}/sources/link

Scopes: corporation_tax:write
Role: Preparer or above

Preparers and above. Snapshots a Working Papers file’s tax computation, or takes profit and turnover from an approved Accounts set, or attaches only the accounts. The source of the same client and period is never written to, and later changes to it are only flagged until someone refreshes. Needs read access to the source’s product.

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

Parameters

Parameters for POST /api/v1/corporation-tax/returns/{id}/sources/link
Name	In	Type	Description
`id`required	path	`string (uuid)`

Request body

Required. application/json: object (LinkCtSourceRequest).

Request body for POST /api/v1/corporation-tax/returns/{id}/sources/link
Field	Type	Description
`source`required	`string (CtLinkSource)`	working_papers: a snapshot of the file’s tax computation. accounts: profit and turnover from an approved Accounts set, and its accounts. accounts_file: only the accounts that go with the return. typed: keep the figures and stop following a source. One of: `typed`, `working_papers`, `accounts`, `accounts_file`
`engagementId`	`string (uuid)`
`accountsSetId`	`string (uuid)`

Responses

200 OK, `application/json`

Body: object (CtReturn).

A Company Tax Return for one accounting period, with its boxes, computation and what stands in the way of filing.

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

Refresh from the source

POST/api/v1/corporation-tax/returns/{id}/sources/refresh

Scopes: corporation_tax:write
Role: Preparer or above

Preparers and above. Brings in what a linked file or set now holds, as a new version. Nothing changes if they already match. A real change loses an approval.

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

Parameters

Parameters for POST /api/v1/corporation-tax/returns/{id}/sources/refresh
Name	In	Type	Description
`id`required	path	`string (uuid)`

Responses

200 OK, `application/json`

Body: object (CtReturn).

A Company Tax Return for one accounting period, with its boxes, computation and what stands in the way of filing.

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

Start next period’s return

POST/api/v1/corporation-tax/returns/{id}/roll-forward

Scopes: corporation_tax:write
Role: Preparer or above
Retries: Send an Idempotency-Key to make retries safe.

Preparers and above. Carries trading losses, loans to participators, capital allowance pool balances and the answers from this return. This year’s figures start at nil.

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

Parameters

Parameters for POST /api/v1/corporation-tax/returns/{id}/roll-forward
Name	In	Type	Description
`id`required	path	`string (uuid)`
`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

Required. application/json: object (RollForwardCtReturnRequest).

Request body for POST /api/v1/corporation-tax/returns/{id}/roll-forward
Field	Type	Description
`periodEnd`	`string (date)`	End of the next period of account. Defaults to 12 months on. example "2026-03-31"

Responses

201 Created, `application/json`

Body: object (CtReturn).

A Company Tax Return for one accounting period, with its boxes, computation and what stands in the way of filing.

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

Send for review

POST/api/v1/corporation-tax/returns/{id}/send-for-review

Scopes: corporation_tax:write
Role: Preparer or above

Preparers and above, from draft.

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

Parameters

Parameters for POST /api/v1/corporation-tax/returns/{id}/send-for-review
Name	In	Type	Description
`id`required	path	`string (uuid)`

Request body

Required. application/json: object (CtNoteRequest).

Request body for POST /api/v1/corporation-tax/returns/{id}/send-for-review
Field	Type	Description
`note`	`string`	up to 2000 characters

Responses

200 OK, `application/json`

Body: object (CtReturn).

A Company Tax Return for one accounting period, with its boxes, computation and what stands in the way of filing.

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

Raise a review point

POST/api/v1/corporation-tax/returns/{id}/review-points

Scopes: review:write
Role: Reviewer or above

Reviewers and above. Open points stop a return being approved.

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

Parameters

Parameters for POST /api/v1/corporation-tax/returns/{id}/review-points
Name	In	Type	Description
`id`required	path	`string (uuid)`

Request body

Required. application/json: object (RaiseCtReviewPointRequest).

Request body for POST /api/v1/corporation-tax/returns/{id}/review-points
Field	Type	Description
`text`required	`string`	1 to 4000 characters
`box`	`string`	The CT600 box it’s about.

Responses

201 Created, `application/json`

Body: object (CtReturn).

A Company Tax Return for one accounting period, with its boxes, computation and what stands in the way of filing.

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/corporation-tax/returns/{id}/review-points/{pointId}/clear

Scopes: review:write
Role: Reviewer or above

Reviewers and above.

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

Parameters

Parameters for POST /api/v1/corporation-tax/returns/{id}/review-points/{pointId}/clear
Name	In	Type	Description
`id`required	path	`string (uuid)`
`pointId`required	path	`string (uuid)`

Responses

200 OK, `application/json`

Body: object (CtReturn).

A Company Tax Return for one accounting period, with its boxes, computation and what stands in the way of filing.

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

Approve a return

POST/api/v1/corporation-tax/returns/{id}/approve

Scopes: review:write
Role: Manager or above
Access: A signed-in Tolvi session only, never an API token.

A partner, signed in, or a manager where the firm allows it (403 otherwise). Refused with open review points, with a linked source changed, or if the figures moved since you reviewed them. What stops filing doesn’t stop approval. Never available to API keys or connected assistants.

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

Parameters

Parameters for POST /api/v1/corporation-tax/returns/{id}/approve
Name	In	Type	Description
`id`required	path	`string (uuid)`

Request body

Required. application/json: object (ApproveCtReturnRequest).

Request body for POST /api/v1/corporation-tax/returns/{id}/approve
Field	Type	Description
`returnHash`required	`string`	The `returnHash` you reviewed.
`note`	`string`

Responses

200 OK, `application/json`

Body: object (CtReturn).

A Company Tax Return for one accounting period, with its boxes, computation and what stands in the way of filing.

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 return

POST/api/v1/corporation-tax/returns/{id}/reopen

Scopes: review:write
Role: Reviewer or above
Access: A signed-in Tolvi session only, never an API token.

Reviewers and above, signed in. Back to draft, and an approval is lost. Never available to API keys or connected assistants.

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

Parameters

Parameters for POST /api/v1/corporation-tax/returns/{id}/reopen
Name	In	Type	Description
`id`required	path	`string (uuid)`

Request body

Required. application/json: object (CtNoteRequest).

Request body for POST /api/v1/corporation-tax/returns/{id}/reopen
Field	Type	Description
`note`	`string`	up to 2000 characters

Responses

200 OK, `application/json`

Body: object (CtReturn).

A Company Tax Return for one accounting period, with its boxes, computation and what stands in the way of filing.

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

Start an amended return

POST/api/v1/corporation-tax/returns/{id}/amend

Scopes: corporation_tax:write
Role: Preparer or above
Access: A signed-in Tolvi session only, never an API token.

Preparers and above, signed in. Only a filed return, within 12 months of its filing date (FA 1998 Sch 18 para 15(4)). A new draft with the filed figures: the original is never changed, and the amendment has its own review, approval and client's confirmation. Filing stays off. Never available to API keys or connected assistants.

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

Parameters

Parameters for POST /api/v1/corporation-tax/returns/{id}/amend
Name	In	Type	Description
`id`required	path	`string (uuid)`

Request body

Required. application/json: object (CtNoteRequest).

Request body for POST /api/v1/corporation-tax/returns/{id}/amend
Field	Type	Description
`note`	`string`	up to 2000 characters

Responses

201 Created, `application/json`

Body: object (CtReturn).

A Company Tax Return for one accounting period, with its boxes, computation and what stands in the way of filing.

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

Record a return as filed outside Tolvi

POST/api/v1/corporation-tax/returns/{id}/filed-elsewhere

Scopes: review:write
Role: Partner
Access: A signed-in Tolvi session only, never an API token.

A partner, signed in, for an approved return that went to HMRC by other means. It's the partner's record, not HMRC's word, and nothing is sent. Never available to API keys or connected assistants.

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

Parameters

Parameters for POST /api/v1/corporation-tax/returns/{id}/filed-elsewhere
Name	In	Type	Description
`id`required	path	`string (uuid)`

Request body

Required. application/json: object (RecordCtFiledElsewhereRequest).

Request body for POST /api/v1/corporation-tax/returns/{id}/filed-elsewhere
Field	Type	Description
`filedOn`required	`string (date)`	The day it went to HMRC by other means. This is a record a person makes, not HMRC’s word. example "2026-03-31"
`note`	`string`	up to 2000 characters

Responses

200 OK, `application/json`

Body: object (CtReturn).

A Company Tax Return for one accounting period, with its boxes, computation and what stands in the way of filing.

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

Record the client’s confirmation

POST/api/v1/corporation-tax/returns/{id}/client-confirmation

Scopes: corporation_tax:write
Role: Preparer or above
Access: A signed-in Tolvi session only, never an API token.

Preparers and above, signed in. The client confirmed the copy they were sent. It counts only for these figures. Never available to API keys or connected assistants.

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

Parameters

Parameters for POST /api/v1/corporation-tax/returns/{id}/client-confirmation
Name	In	Type	Description
`id`required	path	`string (uuid)`

Request body

Required. application/json: object (RecordCtClientConfirmationRequest).

Request body for POST /api/v1/corporation-tax/returns/{id}/client-confirmation
Field	Type	Description
`confirmedOn`required	`string (date)`	example "2026-03-31"
`note`	`string`
`returnHash`required	`string`	The `returnHash` of the copy the client confirmed.

Responses

200 OK, `application/json`

Body: object (CtReturn).

A Company Tax Return for one accounting period, with its boxes, computation and what stands in the way of filing.

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

File with HMRC

POST/api/v1/corporation-tax/returns/{id}/submit

Scopes: corporation_tax:write
Role: Manager or above
Access: A signed-in Tolvi session only, never an API token.
Retries: Send an Idempotency-Key to make retries safe.

A manager or partner, signed in with a second factor, once these figures are approved, the client has confirmed them and nothing blocks filing. Answers 503 until filing is switched on, once HMRC’s test service has passed. Never available to API keys or connected assistants.

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

Parameters

Parameters for POST /api/v1/corporation-tax/returns/{id}/submit
Name	In	Type	Description
`id`required	path	`string (uuid)`
`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

Required. application/json: object (SubmitCtReturnRequest).

Request body for POST /api/v1/corporation-tax/returns/{id}/submit
Field	Type	Description
`returnHash`required	`string`
`agentAccountId`required	`string (uuid)`
`declaration`required	`object`	{ accepted: true, version }: the declaration on the CT600.

Responses

200 OK, `application/json`

Body: object (CtReturn).

A Company Tax Return for one accounting period, with its boxes, computation and what stands in the way of filing.

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

Ask HMRC for its answer

POST/api/v1/corporation-tax/returns/{id}/submissions/{submissionId}/poll

Scopes: corporation_tax:read

While HMRC is checking a return. Tolvi also asks by itself. Part of the corporation_tax product: the firm must have it and you must have access to it.

Parameters

Parameters for POST /api/v1/corporation-tax/returns/{id}/submissions/{submissionId}/poll
Name	In	Type	Description
`id`required	path	`string (uuid)`
`submissionId`required	path	`string (uuid)`

Responses

200 OK, `application/json`

Body: object (CtReturn).

A Company Tax Return for one accounting period, with its boxes, computation and what stands in the way of filing.

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

Download the CT600

GET/api/v1/corporation-tax/returns/{id}/downloads/ct600.pdf

Scopes: corporation_tax:read

The return in the style of HMRC’s form, with CT600A where it applies. Every page gives its status and says it wasn’t issued by HMRC. Bank details appear masked. Part of the corporation_tax product: the firm must have it and you must have access to it.

Parameters

Parameters for GET /api/v1/corporation-tax/returns/{id}/downloads/ct600.pdf
Name	In	Type	Description
`id`required	path	`string (uuid)`

Responses

200 OK

A PDF.

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

Download the computation

GET/api/v1/corporation-tax/returns/{id}/downloads/computation.pdf

Scopes: corporation_tax:read

The tax computation for this accounting period, for people to read. Part of the corporation_tax product: the firm must have it and you must have access to it.

Parameters

Parameters for GET /api/v1/corporation-tax/returns/{id}/downloads/computation.pdf
Name	In	Type	Description
`id`required	path	`string (uuid)`

Responses

200 OK

A PDF.

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

Download the iXBRL accounts

GET/api/v1/corporation-tax/returns/{id}/downloads/accounts.xhtml

Scopes: corporation_tax:read

The tagged accounts from the linked Accounts set. 409 with no set linked. What stops the file being filed is in the return’s problems. Part of the corporation_tax product: the firm must have it and you must have access to it.

Parameters

Parameters for GET /api/v1/corporation-tax/returns/{id}/downloads/accounts.xhtml
Name	In	Type	Description
`id`required	path	`string (uuid)`

Responses

200 OK

iXBRL.

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

Download the iXBRL computation

GET/api/v1/corporation-tax/returns/{id}/downloads/computation.xhtml

Scopes: corporation_tax:read

The tagged computation for this accounting period. What stops the file being filed is in the return’s problems. Part of the corporation_tax product: the firm must have it and you must have access to it.

Parameters

Parameters for GET /api/v1/corporation-tax/returns/{id}/downloads/computation.xhtml
Name	In	Type	Description
`id`required	path	`string (uuid)`

Responses

200 OK

iXBRL.

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

Preview the CT600 XML

GET/api/v1/corporation-tax/returns/{id}/downloads/ct600.xml

Scopes: corporation_tax:read

The return in the order of HMRC’s schema, as it would be sent, without any sign-in and with bank details masked. It isn’t filed by downloading it. Part of the corporation_tax product: the firm must have it and you must have access to it.

Parameters

Parameters for GET /api/v1/corporation-tax/returns/{id}/downloads/ct600.xml
Name	In	Type	Description
`id`required	path	`string (uuid)`

Responses

200 OK

XML.

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

List HMRC accounts

GET/api/v1/corporation-tax/agent-accounts

Scopes: corporation_tax:read

Names and status only: a saved sign-in is never returned. Part of the corporation_tax product: the firm must have it and you must have access to it.

Responses

200 OK, `application/json`

Body: object (CtAgentAccountList).

200 OK response for GET /api/v1/corporation-tax/agent-accounts
Field	Type	Description
`items`required	`array of CtAgentAccount`
`items[].id`required	`string (uuid)`
`items[].name`required	`string`
`items[].credentialStatus`required	`string (CtCredentialStatus)`	One of: `not_saved`, `saved`, `needs_update`
`items[].userIdHint`required	`string`nullable
`items[].lastUsedAt`required	`string (date-time)`nullable
`canStoreCredentials`required	`boolean`	Whether sign-ins can be stored on this Tolvi.

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

Add an HMRC account

POST/api/v1/corporation-tax/agent-accounts

Scopes: settings:admin
Access: A signed-in Tolvi session only, never an API token.

Firm admins, signed in. Name it so people can tell them apart, such as Leeds office. Part of the corporation_tax product: the firm must have it and you must have access to it.

Request body

Required. application/json: object (CreateCtAgentAccountRequest).

Request body for POST /api/v1/corporation-tax/agent-accounts
Field	Type	Description
`name`required	`string`	1 to 80 characters; example "Leeds office"

Responses

201 Created, `application/json`

Body: object (CtAgentAccount).

201 Created response for POST /api/v1/corporation-tax/agent-accounts
Field	Type	Description
`id`required	`string (uuid)`
`name`required	`string`
`credentialStatus`required	`string (CtCredentialStatus)`	One of: `not_saved`, `saved`, `needs_update`
`userIdHint`required	`string`nullable
`lastUsedAt`required	`string (date-time)`nullable

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

Remove an HMRC account

DELETE/api/v1/corporation-tax/agent-accounts/{id}

Scopes: settings:admin
Access: A signed-in Tolvi session only, never an API token.

Firm admins, signed in. Its sign-in is deleted at once. Part of the corporation_tax product: the firm must have it and you must have access to it.

Parameters

Parameters for DELETE /api/v1/corporation-tax/agent-accounts/{id}
Name	In	Type	Description
`id`required	path	`string (uuid)`

Responses

204 No content

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

Save the HMRC sign-in

PUT/api/v1/corporation-tax/agent-accounts/{id}/credentials

Scopes: settings:admin
Access: A signed-in Tolvi session only, never an API token.

Firm admins, signed in. Encrypted, used only when someone allowed to file files a return, and never shown again. Part of the corporation_tax product: the firm must have it and you must have access to it.

Parameters

Parameters for PUT /api/v1/corporation-tax/agent-accounts/{id}/credentials
Name	In	Type	Description
`id`required	path	`string (uuid)`

Request body

Required. application/json: object (SaveCtCredentialsRequest).

Request body for PUT /api/v1/corporation-tax/agent-accounts/{id}/credentials
Field	Type	Description
`userId`required	`string`	1 to 100 characters
`password`required	`string`	1 to 200 characters

Responses

200 OK, `application/json`

Body: object (CtAgentAccount).

200 OK response for PUT /api/v1/corporation-tax/agent-accounts/{id}/credentials
Field	Type	Description
`id`required	`string (uuid)`
`name`required	`string`
`credentialStatus`required	`string (CtCredentialStatus)`	One of: `not_saved`, `saved`, `needs_update`
`userIdHint`required	`string`nullable
`lastUsedAt`required	`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).

Delete the saved sign-in

DELETE/api/v1/corporation-tax/agent-accounts/{id}/credentials

Scopes: settings:admin
Access: A signed-in Tolvi session only, never an API token.

Firm admins, signed in. Part of the corporation_tax product: the firm must have it and you must have access to it.

Parameters

Parameters for DELETE /api/v1/corporation-tax/agent-accounts/{id}/credentials
Name	In	Type	Description
`id`required	path	`string (uuid)`

Responses

200 OK, `application/json`

Body: object (CtAgentAccount).

200 OK response for DELETE /api/v1/corporation-tax/agent-accounts/{id}/credentials
Field	Type	Description
`id`required	`string (uuid)`
`name`required	`string`
`credentialStatus`required	`string (CtCredentialStatus)`	One of: `not_saved`, `saved`, `needs_update`
`userIdHint`required	`string`nullable
`lastUsedAt`required	`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).

Corporation Tax

List returns

Parameters

Responses

200 OK, application/json

Start a return

Parameters

Request body

Responses

201 Created, application/json

Get a return

Parameters

Responses

200 OK, application/json

Change a return

Parameters

Request body

Responses

200 OK, application/json

Group relief for a return

Parameters

Responses

200 OK, application/json

Record a notice of consent

Parameters

Request body

Responses

201 Created, application/json

Withdraw a notice of consent

Parameters

Responses

200 OK, application/json

Link a source

Parameters

Request body

Responses

200 OK, application/json

Refresh from the source

Parameters

Responses

200 OK, application/json

Start next period’s return

Parameters

Request body

Responses

201 Created, application/json

Send for review

Parameters

Request body

Responses

200 OK, application/json

Raise a review point

Parameters

Request body

Responses

201 Created, application/json

Clear a review point

Parameters

Responses

200 OK, application/json

Approve a return

Parameters

Request body

Responses

200 OK, application/json

Reopen a return

Parameters

Request body

Responses

200 OK, application/json

Start an amended return

Parameters

Request body

Responses

201 Created, application/json

Record a return as filed outside Tolvi

Parameters

Request body

Responses

200 OK, application/json

200 OK, `application/json`

201 Created, `application/json`

200 OK, `application/json`

200 OK, `application/json`

200 OK, `application/json`

201 Created, `application/json`

200 OK, `application/json`

200 OK, `application/json`

200 OK, `application/json`

201 Created, `application/json`

200 OK, `application/json`

201 Created, `application/json`

200 OK, `application/json`

200 OK, `application/json`

200 OK, `application/json`

201 Created, `application/json`

200 OK, `application/json`

200 OK, `application/json`

200 OK, `application/json`

200 OK, `application/json`

200 OK, `application/json`

201 Created, `application/json`

200 OK, `application/json`

200 OK, `application/json`