v1

latestOpenAPI 3.0.32026-07-131528298.7 KB
submission

Submit UK Tax Return

Submits a UK Tax Return for a specified accounting period.

The MTT and DTT liabilities reported in the UKTR should be stated in sterling in accordance with s123(3) F(No. 2)A 2023.

Error Codes

<p>This table contains a list of 422 error codes returned when a SubmitUKTR or AmendUKTR request is not processed successfully.</p> <table> <thead> <tr> <th>Error Message</th> <th>Next Steps</th> </tr> </thead> <tbody> <tr> <td>003 - Request could not be processed</td> <td>The message could not be processed due to locking. Please check if there is currently an open enquiry on your tax account. If you are amending an existing return, please check the request dates fall within the amendment window (12 months after the due date, minus 1 day).</td> </tr> <tr> <td>044 - Tax Obligation already fulfilled</td> <td>A UKTR for the specified period has already been submitted. If you are trying to amend a UKTR, please check you are sending the <em>amendUKTR</em> API request.</td> </tr> <tr> <td>063 - Business partner does not have an Active Subscription for this Regime</td> <td>The Pillar 2 ID in the request header is not listed as active by HMRC for this regime. Please contact the central support team.</td> </tr> <tr> <td>093 - Invalid Return</td> <td>There is an error with the tax return you’ve submitted in the request. Entities registered as UK only should check that <em>obligationMTT</em> is set to false, and <em>totalLiabilityIIR</em>, <em>amountOwedIIR</em>, <em>totalLiabilityUTPR</em> and <em>amountOwedUTPR</em> should be set to 0. The <em>accountingPeriodFrom</em> and <em>accountingPeriodTo</em> date range should match the period defined in the test organisation. If you need to check or amend the accounting period pattern, you can do this on the Pillar 2 site under “Manage group details”.</td> </tr> <tr> <td>094 - Invalid DTT Election</td> <td>If <em>electionDTTSingleMember</em> is true, the <em>numberSubGroupDTT</em> should be greater than 0, else Error 094 will be returned. If <em>electionDTTSingleMember</em> is false, no validation will be performed.</td> </tr> <tr> <td>095 - Invalid UTPR Election</td> <td>If <em>electionUTPRSingleMember</em> is true, the <em>numberSubGroupUTPR</em> should be greater than 0, else Error 095 will be returned. If <em>electionUTPRSingleMember</em> is false, no validation will be performed.</td> </tr> <tr> <td>096 - Invalid Total Liability</td> <td>The <em>totalLiability</em> value in the request does not match the combined values of <em>totalLiabilityDTT</em>, <em>totalLiabilityIIR</em> and <em>totalLiabilityUTPR</em>. Please check the sum of these fields matches the <em>totalLiability</em> value and submit the request again.</td> </tr> <tr> <td>097 - Invalid Total Liability IIR</td> <td>The <em>totalLiabilityIIR</em> value does not match the <em>amountIIR value</em> from the sum of <em>liableEntities</em> array. IIR values should only be entered by entities registered as a Multinational Enterprise. Please check the individual totals of each entity and submit the request again.</td> </tr> <tr> <td>098 - Invalid Total Liability DTT</td> <td>The <em>totalLiabilityDTT</em> value does not match the <em>amountDTT</em> value from the sum of <em>liableEntities</em> array. Please check the value of these fields matches and submit the request again.</td> </tr> <tr> <td>099 - Invalid Total Liability UTPR</td> <td>The <em>totalLiabilityUTPR</em> value does not match the <em>amountUTPR</em> value from the sum <em>liableEntities</em> array. UTPR values should only be entered by entities registered as a Multinational Enterprise. Please check the individual totals of each entity and submit the request again.</td> </tr> </tbody> </table>
post/organisations/pillar-two/uk-tax-return

Headers

Authorizationstring required

Bearer token for authentication

X-Pillar2-Idstring required

Pillar2 ID for the submission

Acceptstring
Example:application/vnd.hmrc.1.0+json

Specifies the expected response format as versioned JSON from the HMRC API (v1.0). If not provided, it will default to application/vnd.hmrc.1.0+json.

Request body

OR

Response

UK Tax Return Submission Created

processingDatestring date-time required

The date and time that an event took place.

formBundleNumberstring required

A unique identifier for the request, to be noted and retained in case amendments need to be filed against the return.

chargeReferencestring nullable

Identifier for any liabilities specified in the return. Nil returns do not return a charge reference.