-
Notifications
You must be signed in to change notification settings - Fork 0
Home
Note: The changelog is now being maintained at this page, where the latest updates will appear.
This wiki page is an archive of older changelog entries for reference.
The following change is now available in Sandbox:
These endpoints no longer return HATEOAS links:
Create an Historic FHL UK Property Annual SubmissionAmend an Historic FHL UK Property Annual SubmissionRetrieve an Historic FHL UK Property Annual SubmissionDelete an Historic FHL UK Property Annual SubmissionCreate an Historic Non FHL UK Property Annual SubmissionAmend an Historic Non FHL UK Property Annual SubmissionRetrieve an Historic Non FHL UK Property Annual SubmissionDelete an Historic Non FHL UK Property Annual Submission
The following changes are now available in Sandbox:
Retrieve a Self Assessment Tax Calculation now supports totalTaxableTransitionProfit and transitionProfitDetail within the new transitionProfit object.
All endpoints now support STATEFUL gov-test-scenario.
The following change is now available in Sandbox:
Version 4.0 of this API is now available with the following features.
These endpoints:
Create a UK Property Income & Expenses Period SummaryAmend a UK Property Income & Expenses Period SummaryRetrieve a UK Property Income & Expenses Period SummaryCreate a Foreign Property Income & Expenses Period SummaryAmend a Foreign Property Income & Expenses Period SummaryRetrieve a Foreign Property Income & Expenses Period Summary
now support:
- combining
rentARoomandamountClaimedvalues with aconsolidatedExpensesvalue. -
residentialFinancialCostandresidentialFinancialCostsCarriedForwardfields within theukNonFhlPropertyobject.
All expense fields for these endpoints now accept negative values and a monetary value between -99,999,999,999.99 and 99,999,999,999.99 (to two decimal places) except for residentialFinancialCost, residentialFinancialCostsCarriedForward and rentARoom.
The following changes are now available in the Sandbox:
- Added optional
transitionProfitAmountandtransitionProfitAccelerationAmountfields inannualAdjustmentsTypeobject ofRetrieve a Self-Employment Annual SubmissionandCreate and Amend Self-Employment Annual Submissionendpoints. - New error code
RULE_WRONG_TPA_AMOUNT_SUBMITTEDtoCreate and Amend Self-Employment Annual Submissionendpoint.
The following changes are now available in Production:
Retrieve a Self Assessment Tax Calculation includes the following properties:
calculation.reliefs.giftAidTaxReductionWhereBasicRateDiffers-
calculation.taxCalculation.incomeTax.giftAidTaxChargeWhereBasicRateDifferand -
taxDeductedAtSource.taxTakenOffTradingIncome.
In addition, cashOrAccruals and documentDetails.documentDueDate are now mandatory.
-
Retrieve Business Detailsincludes the objectquarterlyTypeElectionand - a new endpoint,
Create and Amend Quarterly Period Type for a Businessis now available.
New API version v3.0 is now available.
- The
Retrieve Balance and Transactionsresponse propertydocumentDueDateis now optional. - New endpoints
Opt Out of Coding Out,Retrieve Coding Out StatusandOpt in to Coding Outare now available.
All endpoints replace their respective v2 equivalents, which are now deprecated. Please use the new v3 endpoints instead.
New API version v2.0 is now available
The endpoint Retrieve CIS deductions for Subcontractor includes
- a new error,
RULE_TAX_YEAR_RANGE_INVALIDwhen the date range provided exceeds four years before the current year, and - the
fromDateandtoDateparameters have been replaced withtaxYearandsourcepath parameters.
All endpoints replace their respective v1 equivalents, which are now deprecated. Please use the new v2 endpoints instead.
New API version v2.0 is now available
- The endpoint
Retrieve Income Tax (Self Assessment) Final Declarations Obligationsreturns an array instead of a single object.
All endpoints replace their respective v1 equivalents, which are now deprecated. Please use the new v2 endpoints instead.
Update section Mapping APIs to Self Assessment tax return forms as follows:
- add CSV file and listing for SA108
- update CSV files (from v1 to v2) and change list of related APIs for SA100, SA101, SA102 and SA106 because of breakup of individuals-income-received-api
The following change is now available in Sandbox:
Version 4.0 of this API supports stateful test scenarios, enabling you to submit custom test data and then retrieve or list it from a different endpoint.
A STATEFUL Gov-Test-Scenario has been added for the below endpoints:
- Trigger a Business Source Adjustable Summary
- List a Business Source Adjustable Summary
- Retrieve a Self-Employment Business Source Adjustable Summary (BSAS)
- Submit Self-Employment Accounting Adjustments
- Retrieve a UK Property Business Source Adjustable Summary (BSAS)
- Submit UK Property Accounting Adjustments
- Retrieve a Foreign Property Business Source Adjustable Summary (BSAS)
- Submit Foreign Property Accounting Adjustments
You can test the Self-Employment and Property Business user journeys by submitting data by using the Property Business API or the Self Employment API and then adjusting these values by using the Business Source Adjustable Summary API.
The following change is available in Sandbox and Production:
Add content about Self Assessment tax return form mappings to landing page and API reference of all available versions of the API.
The following change is available in Sandbox:
Add content about Self Assessment tax return form mappings to landing page and API reference of all available versions of the API.
As part of the breakup of individuals-income-received-api, the following APIs are available in Sandbox.
This API enables you to retrieve, create, amend or delete data relating to capital gains income.
This API enables you to retrieve, create, amend or delete data relating to dividends income.
This API enables you to retrieve, create, amend or delete data relating to
- employment income
- other employment income
- non-PAYE employment income
This API enables you to retrieve, create, amend or delete data relating to foreign income.
This API enables you to retrieve, create, amend or delete data relating to insurance policies income.
This API enables you to retrieve, create, amend or delete data relating to other income.
This API enables you to retrieve, create, amend or delete data relating to pensions income.
This API enables you to retrieve, create, amend or delete data relating to savings income.
The following changes are available in Sandbox and Production.
Add content about Self Assessment tax return form mappings to landing pages and API reference of all available versions of the following APIs:
The following changes are now available in the Sandbox:
New endpoint Create and Amend Test ITSA Status.
- This endpoint enables you to create and amend a test ITSA status for a specified customer (identified by a National Insurance number) and tax year.
The following change is now available in Sandbox and Production:
Deprecated endpoints will now return the following response headers:
- Deprecation - the deprecation date/time
- Link - a link to the relevant API documentation
- Sunset (if available) - date/time after which the endpoint may not be available
For more details, see the service guide.
The following change is now available in Sandbox and Production:
Deprecated endpoints will now return the following response headers:
- Deprecation - the deprecation date/time
- Link - a link to the relevant API documentation
- Sunset (if available) - date/time after which the endpoint may not be available
For more details, see the service guide.
The following changes are now available in the Sandbox:
- New
STATEFULGov-Test-Scenarios were added to the following v3.0 endpoints:Opt In to Coding OutRetrieve Coding Out StatusOpt Out of Coding Out
The following change is now available in Sandbox and Production:
Deprecated endpoints will now return the following response headers:
- Deprecation - the deprecation date/time
- Link - a link to the relevant API documentation
- Sunset (if available) - date/time after which the endpoint may not be available
For more details, see the service guide.
The following change is now available in Sandbox and Production:
Deprecated endpoints will now return the following response headers:
- Deprecation - the deprecation date/time
- Link - a link to the relevant API documentation
- Sunset (if available) - date/time after which the endpoint may not be available
For more details, see the service guide.
The following change is now available in Sandbox:
New endpoint Opt Out of Coding Out V3.
- This endpoint enables a customer (identified by a National Insurance number) to opt out of coding out for a specified tax year.
The following change is now available in Sandbox:
New endpoint Opt In to Coding Out V3.
- This endpoint enables a customer (identified by a National Insurance number) to opt in to coding out for a specified tax year.
The following fix relating to RULE_TO_DATE_BEFORE_FROM_DATE and RULE_END_DATE_BEFORE_START_DATE validation errors has been applied to Sandbox and Production:
- With this change, date validation logic has been loosened to allow the submission end date to be same as start date in the following API's
The following change is now available in Sandbox:
For endpoint Retrieve Coding Out Status, the following MTD errors have been amended to be returned with a RULE
prefix:
-
BUSINESS_PARTNER_NOT_EXIST->RULE_BUSINESS_PARTNER_NOT_EXIST -
ITSA_CONTRACT_OBJECT_NOT_EXIST->RULE_ITSA_CONTRACT_OBJECT_NOT_EXIST
- API version
1.0has been retired in Sandbox and Production. Please update to use the newest available version of the API2.0.
- API version
3.0has been retired in Sandbox and Production. Please update to use the newest available version of the API5.0. - Updated the timezone in the deprecation headers, from
UTCtoGMT.
The following change is now available in Sandbox and Production:
Deprecated endpoints will now return the following response headers:
- Deprecation - the deprecation date/time
- Link - a link to the relevant API documentation
- Sunset (if available) - date/time after which the endpoint may not be available
The 'API lifecycle & deprecation' section of the Making Tax Digital for Income Tax end-to-end service guide will be updated with more details.
The following change is now available in Sandbox:
New endpoint Retrieve Coding Out Status.
- This endpoint enables you to retrieve opt-out of coding out status for a specified customer (identified by a National Insurance number) and tax year.
- API version
v1.0has been retired in Sandbox and Production. Please update to use the newest available version of the APIv3.0.
-
API version
v3.0has been retired in Sandbox and Production. Please update to use the newest available version of the APIv4.0. -
The below API versions have been deprecated in Sandbox and Production and will no longer accept new subscriptions. Existing subscriptions will continue to work.
individual-calculations-api v4.0individuals-business-eops-api v2.0individuals-expenses-api v1.0individuals-income-received-api v1.0property-business-api v2.0self-assessment-bsas-api v3.0self-employment-business-api v2.0
The following change is now available in Sandbox:
New endpoint Create and Amend Quarterly Period Type for a Business.
- This endpoint enables you to create and amend the type of quarterly reporting period used for a business for a specific tax year.
For the Create a Self-Employment Period Summary endpoint, the Gov Test Scenario STATEFUL will now return
RULE_MISALIGNED_PERIOD where the period start and end dates do not match the correct quarterly period dates outlined
here - https://www.gov.uk/guidance/using-making-tax-digital-for-income-tax
The following changes are now available in Sandbox:
For Create a Foreign Property Income & Expenses Period Summary
and Create a UK Property Income & Expenses Period Summary endpoints:
- New Stateful Gov Test Scenario
MISALIGNEDfor errorRULE_MISALIGNED_PERIOD
The following change is now available in Sandbox:
New API version v2.0 is now available.
For the v2.0 Retrieve ITSA Details endpoint:
- New enum value
MTD ITSA Opt-Outadded tostatusReasonfield.
The following change is now available in Sandbox:
For Retrieve Business Details endpoint:
- New optional object
quarterlyTypeChoicehas been added to the response object.
For Create a Test Business endpoint:
- New optional object
quarterlyTypeChoicehas been added to the request object. - New error
FORMAT_QUARTERLY_PERIOD_TYPEhas been added
The following changes have been made to the Developer Hub API documentation:
Wording has changed to clarify and emphasise the need to pass the taxYear query parameter for tax years 2023-24
onwards for the following endpoints (v1.0 and v2.0):
Delete CIS Deductions for Subcontractor
Wording has changed to clarify and emphasise the need to pass the taxYear query parameter for tax years 2023-24
onwards for the following endpoints (v3.0, v4.0 and v5.0):
List Self Assessment Tax Calculations
Wording has changed to clarify and emphasise the need to pass the taxYear query parameter for tax years 2023-24
onwards for the following endpoints (v3.0 and v4.0):
Submit Foreign Property Accounting AdjustmentsSubmit UK Property Accounting AdjustmentsSubmit Self-Employment Accounting AdjustmentsRetrieve a Foreign Property Business Source Adjustable SummaryRetrieve a UK Property Business Source Adjustable SummaryRetrieve a Self-Employment Business Source Adjustable SummaryList Business Source Adjustable Summaries
The following changes are now available in Production:
For Retrieve Business Details endpoint:
- New optional fields
yearOfMigration,firstAccountingPeriodStartDateandfirstAccountingPeriodEndDate - New array
latencyDetailsadded
New API version v3.0 is now available
For Submit End of Period Statement for a Business endpoint:
- New error
RULE_BUSINESS_INCOME_PERIOD_RESTRICTIONadded
New API version v5.0 is now available
For Retrieve a Self Assessment Tax Calculation endpoint:
- The field
totalAnnuityPaymentsTaxChargedis returned as decimal in both non-TYS and TYS request. - New object
statePensionadded in all the versions - In the
non-TYSrequest:- New field
cessationDateadded
- New field
- In the
TYSrequest:- New fields
cessationDate,commencementDateanditsaStatusadded - New objects
otherIncomeadded - Updated field
totalAnnuityPaymentsTaxChargedfrom integer to number
- New fields
New API version v2.0 is now available
For Create and Amend Employment Expenses (TYS) endpoint:
- New error
RULE_INVALID_SUBMISSION_PENSION_SCHEMEadded
New API version v2.0 is now available
For Create and Amend Employment Financial Details endpoint:
- New error
RULE_INVALID_SUBMISSION_PENSION_SCHEMEadded
For Create and Amend Other Income (TYS) endpoint:
- New error
RULE_UNALIGNED_CESSATION_TAX_YEARadded - The field
foreignTaxCreditReliefis now optional
For Retrieve Other Income (TYS) endpoint:
- New object
postCessationReceiptsadded - The field
foreignTaxCreditReliefis now optional
New API version v3.0 is now available
The field lossBroughtForward is removed from the following TYS endpoints:
Create and Amend a Foreign Property Annual SubmissionCreate and Amend a UK Property Business Annual SubmissionRetrieve a Foreign Property Annual SubmissionRetrieve a UK Property Business Annual Submission
New API version v4.0 is now available
For Retrieve a Self-Employment Business Source Adjustable Summary endpoint:
- The data fields in
adjustableSummaryCalculationnow accept both positive and negative values
Updated error message for MATCHING_RESOURCE_NOT_FOUND in the following endpoint:
Trigger a Business Source Adjustable Summary
- A new microservice
Self Assessment Individual Details APIhas been released. The current version (1.0) of this API enables you to obtain the ITSA status for a given National Insurance number for a specified tax year, and optionally future years after that tax year. A National Insurance number and tax year must be provided.
New API version v3.0 is now available
The fields inside the periodExpenses and periodDisallowableExpenses objects now accept negative values in the
following endpoints:
Create a Self-Employment Period Summary (TYS)Amend a Self-Employment Period Summary (TYS)Retrieve a Self-Employment Period Summary (TYS)
The following change is now available in Sandbox:
When using the STATEFUL Gov-Test-Scenario, the accountingType field will default to CASH if the accountingType field
for a business created using the the mtd-sa-test-support-api Create a Test Business endpoint has not been given a
value.
The following change has been made to the Developer Hub API documentation:
Wording has changed to clarify and emphasise the need to pass the taxYear query parameter for tax years 2023-24
onwards for the following endpoints (V1.0, v2.0 and v3.0):
Amend a Self-Employment Period SummaryRetrieve a Self-Employment Period Summary
The following change is now available in Sandbox:
New data field taxTakenOffTradingIncome has been added to the periodIncome object in the following v3.0 endpoints:
- Create a Self-Employment Period Summary
- Amend a Self-Employment Period Summary
- Retrieve a Self-Employment Period Summary
New data field taxTakenOffTradingIncome has been added to the taxDeductedAtSource response body in Retrieve a Self Assessment Tax Calculation (v4.0 and v5.0) endpoint.
The following change is now available in Sandbox:
New API version 3.0 with the following change:
-
Retrieve Balance and Transactionsresponse fielddocumentDueDateis now optional.
The following change is now available in Sandbox:
The following items have been added to the response of Retrieve a Self Assessment Tax Calculation endpoint:
-
calculation.reliefs.giftAidTaxReductionWhereBasicRateDiffersobject -
calculation.taxCalculation.incomeTax.giftAidTaxChargeWhereBasicRateDiffersfield
The following change is now available in Sandbox:
- The error message for 404
MATCHING_RESOURCE_NOT_FOUNDhas been updated inTrigger a Business Source Adjustable Summary
An issue has been fixed in Production whereby the taxYear 2017-18 was incorrectly not accepted for the following endpoints:
Retrieve a Historic FHL UK Property Business Annual SubmissionCreate and Amend a Historic FHL UK Property Business Annual SubmissionDelete a Historic FHL UK Property Business Annual SubmissionRetrieve a Historic Non-FHL UK Property Business Annual SubmissionCreate and Amend a Historic Non-FHL UK Property Business Annual SubmissionDelete a Historic Non-FHL UK Property Business Annual Submission
An issue has been fixed in Production whereby the supplied periodId was not being accepted for Q4 of tax year 2021-22, but was, incorrectly, being accepted for Q4 of tax year 2016-17. This affects the following endpoints:
Retrieve a Historic Non-FHL UK Property Income & Expenses Period SummaryRetrieve a Historic FHL UK Property Income & Expenses Period SummaryAmend a Historic Non-FHL UK Property Income & Expenses Period SummaryAmend a Historic FHL UK Property Income & Expenses Period Summary
A previous update made the final letter of a National Insurance number optional for the following API endpoints in sandbox:
List All BusinessesRetrieve Business Details
Create a Test BusinessDelete a Test Business
This change has been reverted and a full 9 digit National Insurance number format is now required.
The following changes are now available in Sandbox and Production:
- Date fields only accept within the range of 1900-01-01 and 2100-01-01.
The following changes are now available in the Sandbox:
- The final letter of a National Insurance number is now optional for the following API endpoints:
Create a Test BusinessDelete a Test Business
- The final letter of a National Insurance number is now optional for the following API endpoints:
List All BusinessesRetrieve Business Details
The following changes are now available in the Sandbox:
- Support for the
STATEFUL_DELETEGov-Test-Scenario forDelete a Self-Employment Annual Submissionendpoint has been removed in v3.0. This has been replaced with theSTATEFULGov-Test-Scenario.
- Support for the
STATEFUL_DELETEGov-Test-Scenarios for endpointsDelete a Historic FHL UK Property Business Annual SubmissionandDelete a Historic Non-FHL UK Property Business Annual Submissionhas been removed in v3.0. This has been replaced with theSTATEFULGov-Test-Scenario.
- Support for the
STATEFUL_DELETEGov-Test-Scenario forDelete Charitable Giving Tax Reliefendpoint has been removed in v1.0. This has been replaced with theSTATEFULGov-Test-Scenario.
The following changes are now available in the Sandbox:
- New
STATEFULGov-Test-Scenarios were added to the following v2.0 endpoints:-
Create and Amend,RetrieveandDelete Other Income -
Create and Amend,RetrieveandDelete Savings Income -
Create and Amend,RetrieveandDelete Other Capital Gains and Disposals
-
- New
STATEFULGov-Test-Scenarios were added to the following v1.0 endpoints:-
Create,Amend,ListandDelete State Benefit -
AmendandDelete State Benefit Amounts
-
- New
STATEFULGov-Test-Scenarios were added to the following v2.0 endpoints:-
Create or Amend,RetrieveandDelete Coding Out Underpayments and Debt Amounts
-
- New
STATEFULGov-Test-Scenarios were added to the following v2.0 endpoints:-
CreateAmend,RetrieveandDelete CIS Deductions for Subcontractor
-
- New dynamic Gov-Test-Scenarios were added to the following v4.0 endpoints:
Retrieve a Foreign Property Business Source Adjustable Summary (BSAS)Retrieve a UK Property Business Source Adjustable Summary (BSAS)Retrieve a Self-Employment Business Source Adjustable Summary (BSAS)List Business Source Adjustable Summaries (BSAS)
- New
DYNAMICGov-Test-Scenario was added to the following endpoints in v4.0 and later:Retrieve a Self Assessment Tax Calculation
- Additional validation error codes added to
Create a Test Businessendpoint:MISSING_FIRST_ACCOUNTING_PERIOD_START_DATEMISSING_FIRST_ACCOUNTING_PERIOD_END_DATERULE_FIRST_ACCOUNTING_DATE_RANGE_INVALIDRULE_UNEXPECTED_BUSINESS_ADDRESSRULE_MISSING_BUSINESS_ADDRESSRULE_UNEXPECTED_TRADING_NAMERULE_MISSING_TRADING_NAME
- A new error
INVALID_IDTYPEhas been added to the following API endpoints:List All BusinessesRetrieve Business Details
The following changes are now available in the Sandbox:
- Data field taxTakenOffTradingIncome has been removed from the taxDeductedAtSource response body in Retrieve a Self Assessment Tax Calculation (v4.0 and v5.0) endpoint. (This field will be reinstated in a future release).
- Data field taxTakenOffTradingIncome has been removed from the periodIncome object in the following v3.0 endpoints (
This field will be reinstated in a future release):
- Create a Self-Employment Period Summary
- Amend a Self-Employment Period Summary
- Retrieve a Self-Employment Period Summary
Version 5.0 is now available in the sandbox with the following changes:
- The format of the
calculation.taxCalculation.totalAnnuityPaymentsTaxChargedfield has been changed from Integer to Decimal (decimal places <= 2).
The following changes are now available in the Sandbox:
-
A number of corrections have been made to the Developer Hub documentation for this API. In particular, some
List Checkpointsendpoint fields were incorrectly named:-
Checkpointsshould have beencheckpoints, and -
checkpointcreationTimestampshould have beencheckpointCreationTimestamp.
-
-
All endpoints on this test-support API now use application-restricted authorisation. They will still also allow valid user-restricted OAuth 2.0 access tokens.
The following changes are now available in the Sandbox:
-
New
STATEFULGov-Test-Scenarios were added to the following v2 endpoints:-
Create and Amend,RetrieveandDelete Employment Financial Details -
Create and Amend,RetrieveandDelete Insurance Policies Income -
Create and Amend,RetrieveandDelete Pensions Income -
Add,List,Create and AmendandRetrieve UK Savings Account -
Create and Amend,RetrieveandDelete CGT Residential Property Disposals (non-PPD) -
Create and Amend,RetrieveandDelete CGT Residential Property Disposals (PPD)
-
-
Code improvement for breaking change, The code changes are for v2:
- A new
RULE_INVALID_SUBMISSION_PENSION_SCHEMEerror has been added.
- A new
- New
DYNAMICGov-Test-Scenarios added to v3.0 endpoint:Retrieve a Self-Employment Period Summary
- Code improvement for breaking change, The code changes are for v2:
- A new
RULE_INVALID_SUBMISSION_PENSION_SCHEMEerror has been added.
- A new
-
New feature
Create,Restore,ListandDelete Checkpoint. These endpoints enable you to create, restore, list and delete a checkpoint for the stateful data for a particular NINO. -
New feature
Create,Delete Test Business. These endpoints enable you to create and delete test businesses as required. -
Upgrade
HTTP Clientto Version 2 -
New
Auto delete checkpointfeature. This feature will auto delete checkpoints after 7 days.
The following changes are now available in the Sandbox:
- For
Retrieve Business Detailsendpoint:- Updated
taxYear1andtaxYear2fields inLatency Detailsresponse object to the format YYYY-YY (e.g 2018-19)
- Updated
- Version 2.0 is has been retired in Production and the sandbox.
- Version 1.0 is has been retired in Production and the sandbox.
Version 4.0 is now available in the sandbox with the following changes:
-
Retrieve Self-Employment BSASendpoint: Data fields within theadjustableSummaryCalculationresponse object can now return negative values.
- In Production, the following properties are now mandatory in the retrieve a business income source summary endpoint
response:
total.incometotal.expensesprofit.incomeprofit.expensesloss.netloss.taxable
The following change is now available in the Sandbox:
- The properties
yearOfMigration,firstAccountingPeriodStartDate,firstAccountingPeriodEndDateand the objectlatencyDetailswere added to theRetrieve Business Detailsendpoint.
The following changes are now available in the Sandbox:
- For
Retrieve a Self Assessment Tax v4.0endpoint:- New data fields
cessationDateandcommencementDatehave been added to thebusinessIncomeSourcesresponse object. - New object
otherIncomehas been added to thecalculationresponse object. - New data field
taxTakenOffTradingIncomehas been added to thetaxDeductedAtSourceresponse object. - New data field
itsaStatushas been added to thepersonalInformationresponse object.
- New data fields
The following changes are now available in the Sandbox:
- For version 1.0 and later, Gov-Test-Scenario values that are not supported by the sandbox will now result in a status code 400 response with an error code of RULE_INCORRECT_GOV_TEST_SCENARIO.
- For version 1.0, Gov-Test-Scenario values that are not supported by the sandbox will now result in a status code 400 response with an error code of RULE_INCORRECT_GOV_TEST_SCENARIO.
- Version 2.0 is has been retired in Production and the sandbox.
- Version 1.0 is has been retired in Production and the sandbox.
- Version 1.0 is has been retired in the sandbox.
- Version 2.0 is has been retired in Production and the sandbox.
The following changes are now available in the Sandbox:
New API Version v3.0 is now available
- For
v2.0andv3.0: - Updated data fields within the
periodExpenses&periodDisallowableExpensesobjects to accept negative values in the following endpoints:-
Create,RetrieveandAmend a Self-Employment Period Summary
-
- A new data field
taxTakenOffTradingIncomehas been added to theincomesTypeobject in the following endpoints:-
Create,RetrieveandAmend a Self-Employment Period Summary
-
- Version 1.0 is has been deprecated in Production and the sandbox and will no longer accept new subscriptions to this version. Existing subscriptions will continue to work.
The following changes are now available in the Sandbox:
- New
STATEFULGov-Test-Scenarios were added to the following v4.0 endpoints:-
Create,Retrieve,ListandDelete Loss Claims Amend a Loss Claims TypeAmend Loss Claims Order
-
-
New
STATEFULGov-Test-Scenarios were added to the following endpoints:-
Add,AmendandDelete Custom Employment -
RetrieveandList Employments -
Create and Amend,RetrieveandDelete Non-PAYE Employment Income -
Create and Amend,RetrieveandDelete Other Employment Income -
Create and Amend,RetrieveandDelete Dividends Income -
Create and Amend,RetrieveandDelete UK Dividends Income -
Create and Amend,RetrieveandDelete Foreign Income
-
-
New
DYNAMICGov-Test-Scenario added toRetrieve Other Incomeendpoint
- New
DYNAMICGov-Test-Scenarios added to v2.0 endpoints:Retrieve Income Tax (Self Assessment) Income and Expenditure ObligationsRetrieve Income Tax (Self Assessment) Final Declaration ObligationsRetrieve Income Tax (Self Assessment) End of Period Statement Obligations
- New
DYNAMICGov-Test-Scenario added to v3.0List Self Assessment Tax Calculationsendpoint
- New
DYNAMICGov-Test-Scenario added toRetrieve Employment Expensesendpoint
- New
DYNAMICGov-Test-Scenario added to v2.0List Self-Employment Period Summariesendpoint
- New
DYNAMICGov-Test-Scenario added toRetrieve CIS Deductions for Subcontractorendpoint
- New feature in the
Delete Stateful Test Dataendpoint. This endpoint allows a developer to delete stateful test data using a nino supplied by them in the sandbox environment.
The following changes are now available in the Sandbox:
-
Delete a Self-Employment Annual SubmissionSTATEFUL_DELETE gov test scenario is deprecated and will be removed on 05 September 2023. It will be replaced by the STATEFUL Gov-Test-Scenario.
-
Delete a Historic FHL UK Property Business Annual Submission&Delete a Historic Non-FHL UK Property Business Annual SubmissionSTATEFUL_DELETE gov test scenario is deprecated and will be removed on 05 September 2023. It will be replaced by the STATEFUL Gov-Test-Scenario.
The following changes are now available in the Sandbox:
New API Version v3.0 is now available for:
-
self-employment-business-api -
property-business-api -
individuals-business-eops-api -
A new error
RULE_BUSINESS_INCOME_PERIOD_RESTRICTIONand gov-test-scenarioBUSINESS_INCOME_PERIOD_RESTRICTIONhas been added to the following API endpoints:-
Create a Self-Employment Period Summaryforself-employment-business-api v3 -
Create a UK Property Income & Expenses Period Summaryforproperty-business-api v3 -
Submit End of Period Statement for a Businessforindividuals-business-eops-api v3
-
- Version 3.0 is has been deprecated in Production and the sandbox and will no longer accept new subscriptions to this version. Existing subscriptions will continue to work.
The following changes are now available in the Sandbox:
- A new error
RULE_INVALID_SUBMISSION_PENSION_SCHEMEhas been added toCreate and Amend Employment Expenses.
- A new error
RULE_INVALID_SUBMISSION_PENSION_SCHEMEhas been added toCreate and Amend Financial Details.
- Updated the
totalIncomeTaxAndNicsDueto optional in the V4.0 API documentation for endpointList Self Assessment Tax Calculations.
The following changes are now available in the Sandbox:
- For version 1.0 and later, Gov-Test-Scenario values that are not supported by the sandbox will now result in a status code 400 response with an error code of RULE_INCORRECT_GOV_TEST_SCENARIO.
-
Delete Charitable Giving Tax ReliefSTATEFUL_DELETE gov test scenario is deprecated and will be removed on 05 September 2023. It will be replaced by the STATEFUL Gov-Test-Scenario.
The following changes are now available in the Sandbox:
- For version 1.0, Gov-Test-Scenario values that are not supported by the sandbox will now result in a status code 400 response with an error code of RULE_INCORRECT_GOV_TEST_SCENARIO.
The following changes are now available in Production:
New API Version v2.0 is now available
-
Retrieve Pensions ChargesandCreate and Amend Pensions Chargeshave been updated withisAnnualAllowanceReduced,moneyPurchasedAllowanceandtaperedAnnualAllowanceremoved frompensionSavingsTaxChargesand added topensionContributions
All endpoints replace their respective v1 equivalents, which are now deprecated. Please use the new v2 endpoints instead.
New API version v4.0 is now available in Production
-
List Self Assessment Tax Calculationshas been updated:bissandPOAremoved from thecalculationType,totalIncomeTaxAndNicsDueis now optional andcalculationTimeStampnow has three digits for milliseconds instead of two -
Retrieve a Self Assessment Tax Calculationhas new propertiescalculation.endOfYearEstimate.totalAllowancesAndDeductions,calculation.reliefs.basicRateExtension.totalBasicRateExtension,calculation.reliefs.basicRateExtension.giftAidRelief,calculation.reliefs.basicRateExtension.pensionsContributionReliefandcalculation.employmentAndPensionsIncome.employmentAndPensionsIncomeDetail.offPayrollWorker
All endpoints replace their respective v3 equivalents, which are now deprecated. Please use the new v4 endpoints instead.
- The property
offPayrollWorkerhas been added toCreate and Amend Employment Financial DetailsandRetrieve an Employment and its Financial Details
The following changes are now available in the Sandbox:
New API Version v2.0
Updated Endpoint: Retrieve CIS Deductions for Subcontractor
- Updated endpoint URL
- Added
taxYearas path parameter - Added
sourceas path parameter - Removed
fromDateandtoDatefrom query parameters as they are replaced bytaxYearpath parameter
- Added
- Removed
DATE_RANGE_OUT_OF_DATEgov-test-scenario - Added
TAX_YEAR_RANGE_INVALIDgov-test-scenario
The following changes are now available in the Sandbox:
- The error
RULE_DISPOSAL_DATEwas removed, and a new error,RULE_DISPOSAL_DATE_NOT_FUTUREadded toCreate and Amend Other Capital Gains and Disposals - The description for the error
RULE_DISPOSAL_DATEinCreate and Amend CGT Residential Property Disposals (non-PPD)was updated - The property
foreignTaxCreditReliefis now optional forRetrieve Dividends Income,Retrieve Pensions Income,Retrieve Other IncomeandCreate and Amend Other Income
- Updated the
statusquery parameter description in the v1.0 API documentation for endpoints:Retrieve Income Tax (Self Assessment) Income and Expenditure ObligationsRetrieve Income Tax (Self Assessment) End of Period Statement Obligations
The following changes are now available in the Sandbox:
- New
STATEFULGov-Test-Scenarios were added to the following endpoints:-
Create and Amend,RetrieveandDelete Self Employment Annual Submission -
Create,Amend,RetrieveandList Self Employment Period Summaries
-
- New
STATEFULGov-Test-Scenario was added to the following endpoint:-
Create and Amend,RetrieveandDelete Pensions Charges
-
-
New
STATEFULGov-Test-Scenario was added to the following endpoint:-
Create and Amend,RetrieveandDelete Disclosures
-
-
New
DYNAMICGov-Test-Scenario was added to the following endpoint:Retrieve Disclosures
- New
STATEFULGov-Test-Scenarios were added to the following endpoints:-
Create and Amend,RetrieveandDelete Other Expenses -
Create and Amend,RetrieveandDelete Employment Expenses
-
-
New
STATEFULGov-Test-Scenario was added to the following endpoint:-
Create,Amend,Retrieve,ListandDelete Brought Forward Losses
-
-
New
DYNAMICGov-Test-Scenarios were added to the following endpoints:Amend a Brought Forward Loss AmountAmend a Loss Claim TypeList Loss Claims
- New
STATEFULGov-Test-Scenario was added to the following endpoint:-
Create and Amend,RetrieveandDelete Deductions
-
- New
DYNAMICGov-Test-Scenario was added to the following v1.0 endpoint:Retrieve Income Tax (Self Assessment) Final Declaration Obligations
- New
STATEFULGov-Test-Scenarios were added to the following endpoints:-
Create and Amend,RetrieveandDelete Relief Investments -
Create and Amend,RetrieveandDelete Other Reliefs -
Create and Amend,RetrieveandDelete Foreign Reliefs -
Create and Amend,RetrieveandDelete Pensions Reliefs -
Create and Amend,RetrieveandDelete Charitable Giving Tax Reliefs
-
- New
DYNAMICGov-Test-Scenario was added to the following endpoint:Retrieve Business Details
- New
DYNAMICGov-Test-Scenario was added to the following endpoint:List Business Source Adjustable Summaries
- New
DYNAMICGov-Test-Scenario was added to the following endpoint:List State Benefits
The following changes are now available in the Sandbox:
-
Retrieve Income Tax (Self Assessment) Final Declaration Obligations:- New, optional
statusquery parameter. This may specify either Open or Fulfilled. Ifstatusisn't provided, both Open and Fulfilled obligations will be returned. - A new error code has been added: FORMAT_STATUS.
- govTestScenarios removed: OPEN and FULFILLED.
- The
taxYearquery parameter's default behaviour has changed. IftaxYearisn't provided, data will be returned for the last 5 years, i.e. current tax year and up to 4 years previously.
- New, optional
The following changes are now available in the Sandbox and Production:
- Updated the
periodDatafield description in the API documentation for:Create CIS Deductions for SubcontractorAmend CIS Deductions for SubcontractorRetrieve CIS Deductions for Subcontractor
The following changes are now available in the Sandbox:
- Updated endpoint
Create and Amend other income:- Creation of new field
postCessationReceiptsin request object - Added a new
RULE_UNALIGNED_CESSATION_TAX_YEAR
- Creation of new field
- Updated endpoint
Retrieve other income:- Creation of new field
postCessationReceiptsin response object
- Creation of new field
The following changes are now available in the Sandbox:
- For version 1.0, Gov-Test-Scenario values that are not supported by the sandbox will now result in a status code 400 response with an error code of RULE_INCORRECT_GOV_TEST_SCENARIO.
The following changes are now available in the Sandbox:
New API Version v2.0
Updated Endpoint: Create and Amend Dividends Income
- The field
foreignTaxCreditReliefin request objects:dividendIncomeReceivedWhilstAbroadandforeignDividendis now optional.
Updated Endpoint: Create and Amend Pensions Income
- The field
foreignTaxCreditReliefin request object:foreignPensionis now optional.
Updated Endpoint: Retrieve Savings Income
- The field
foreignTaxCreditReliefin request object:foreignInterestis now optional.
New API Version v4.0
Updated Endpoint: List Self Assessment Tax Calculations
- The field
totalIncomeTaxAndNicsDuein request object:taxCalculationsis now optional.
The following changes are now available in the Sandbox:
- For version 1.0 and later, Gov-Test-Scenario values that are not supported by the sandbox will now result in a status code 400 response with an error code of RULE_INCORRECT_GOV_TEST_SCENARIO.
The following change is now available in the Sandbox:
- Renamed from transactional-risking to self-assessment-assist and taxyear included as part of URL
- Error codes and description updated and additional error codes added please refer to endpoint documentation for details.
The following changes are now available in the Sandbox:
- New
STATEFULGov-Test-Scenarios were added to the following endpoints:-
Create and AmendandRetrieve UK Property Business Annual Submission -
Create and AmendandRetrieve a Foreign Property Annual Submission Delete a Property Annual Submission-
Create and Amend,RetrieveandDelete a Historic non-FHL UK Property Business Annual Submission -
Create and Amend,RetrieveandDelete a Historic FHL UK Property Business Annual Submission -
Create,Amend,ListandRetrieve a Historic non-FHL UK Property Income & Expenses Period Summary -
Create,Amend,ListandRetrieve a Historic FHL UK Property Income & Expenses Period Summary -
Create,AmendandRetrieve a Foreign Property Income & Expenses Period Summary -
Create,AmendandRetrieve UK Property Income & Expenses Period Summary List Property Income & Expenses Period Summaries
-
- For version 1.0, new
DYNAMICGov-Test-Scenarios were added to the following endpoints:Retrieve Income Tax (Self Assessment) End of Period Statement ObligationsRetrieve Income Tax (Self Assessment) Income and Expenditure Obligations
- New
DYNAMICGov-Test-Scenario was added to theList Brought Forward Lossesendpoint.
- New
CASHandACCRUALSGov-Test-Scenarios were added to theRetrieve Business Detailsendpoint.
- A new microservice
Self-Assessment Test Support APIhas been released and is available to developers in the sandbox environment. The current version (1.0) of this API provides a means for developers to delete all vendor-supplied stateful test data in the sandbox environment.
The following changes are now available in the Sandbox.
- Added new
BOTH_EXPENSES_SUPPLIEDGov-Test-Scenario to the following endpoints:- Create a Self-Employment Period Summary
- Amend a Self-Employment Period Summary
- Gov-Test-Scenario values that are not supported by the sandbox will now result in a status code 400 response with an
error code of
RULE_INCORRECT_GOV_TEST_SCENARIO.
- Added new
TAX_YEAR_NOT_ENDEDGov-Test-Scenario to the following endpoints:- Create and Amend Employment Expenses
- Ignore Employment Expenses
- Gov-Test-Scenario values that are not supported by the sandbox will now result in a status code 400 response with an
error code of
RULE_INCORRECT_GOV_TEST_SCENARIO.
The following change is now available in the Sandbox.
- For version 2.0 and later, Gov-Test-Scenario values that are not supported by the sandbox will now result in a status code 400 response with an error code of RULE_INCORRECT_GOV_TEST_SCENARIO.
The following changes are now available in the Sandbox.
- For version 2.0 and later, Gov-Test-Scenario values that are not supported by the sandbox will now result in a status code 400 response with an error code of RULE_INCORRECT_GOV_TEST_SCENARIO.
✂️ Deprecation of API versions
The following API versions have been deprecated in Production and Sandbox:
- Individual Losses API V3.0
- Self Employment Business API V1.0
These deprecated versions cannot be subscribed to any longer. However, they can be called if the subscription was made before this status change.
The following changes are now available in the Sandbox and Production.
-
RULE_LOSSES_GREATER_THAN_GAINerror was removed for following endpoints:Create and Amend 'Report and Pay Capital Gains Tax on Residential Property' Overrides (PPD)Create and Amend CGT Residential Property Disposals (non-PPD)
-
RULE_COMPLETION_DATE_BEFORE_DISPOSAL_DATEerror was removed for the following endpoint:Create and Amend CGT Residential Property Disposals (non-PPD)
The following changes are now available in the Sandbox.
-
New gov-test-scenarios were added for
Create and Amend Other Capital Gains and Disposalsendpoint:INVALID_DISPOSAL_DATEINVALID_ACQUISITION_DATE
-
New gov-test-scenarios were added for
Create and Amend 'Report and Pay Capital Gains Tax on Residential Property' Overrides (PPD)endpoint:RULE_DUPLICATED_PPD_SUBMISSION_IDRULE_TAX_YEAR_NOT_ENDED
-
New gov-test-scenarios were added for
Create and Amend CGT Residential Property Disposals (non-PPD)endpoint:RULE_ACQUISITION_DATE_AFTER_DISPOSAL_DATERULE_COMPLETION_DATERULE_DISPOSAL_DATE
The following changes are now available in the Sandbox and Production.
- Added new
TAX_YEAR_NOT_ENDEDGov-Test-Scenario to the following endpoints:Ignore EmploymentUnignore EmploymentCreate and Amend Employment Financial Details
- Added new
PROPERTY_INCOME_ALLOWANCEGov-Test-Scenario to the following endpoints:Create and Amend a Foreign Property Annual SubmissionCreate and Amend a UK Property Annual Submission
- Added new
DUPLICATE_COUNTRY_CODEGov-Test-Scenario to the following endpoints:Create and Amend a Foreign Property Annual Submission
The following changes are now available in the Sandbox.
- For version 1.0 and later, Gov-Test-Scenario values that are not supported by the sandbox will now result in a status
code 400 response with an error code of
RULE_INCORRECT_GOV_TEST_SCENARIO.
The following changes are now available in the Sandbox.
- For version 3.0 and later, Gov-Test-Scenario values that are not supported by the sandbox will now result in a status
code 400 response with an error code of
RULE_INCORRECT_GOV_TEST_SCENARIO.
The following changes are now available in the Sandbox.
New API Version v2.0
Updated Endpoint: Retrieve Income Tax (Self Assessment) Final Declaration Obligations (V2)
- Response body updated to be an array of obligations
- Error
RULE_TAX_YEAR_NOT_SUPPORTEDdescription and message updated - Error
RULE_TAX_YEAR_TOO_LONGreplaced withRULE_TAX_YEAR_RANGE_INVALID - Gov-Test-Scenario
MULTIPLEadded
The following changes are now available in the Sandbox.
- For version 1.0, Gov-Test-Scenario values that are not supported by the sandbox will now result in a status code 400
response with an error code of
RULE_INCORRECT_GOV_TEST_SCENARIO.
- For version 1.0, Gov-Test-Scenario values that are not supported by the sandbox will now result in a status code 400
response with an error code of
RULE_INCORRECT_GOV_TEST_SCENARIO.
The following changes are now available in the Sandbox.
- For versions 1.0 and later, Gov-Test-Scenario values that are not supported by the sandbox will now result in a status
code 400 response with an error code of
RULE_INCORRECT_GOV_TEST_SCENARIO.
We have switched to a new tool for publishing API documentation. The details of API endpoints are now presented in an improved format in Production and the sandbox.
We have also updated the descriptions of a number of properties across the APIs to make them easier to understand.
The following changes have been made to the documentation:
- Added missing
messageattribute to all example error codes - Documented that
correlationIdis mandatory
The following changes are now available in Production:
- Some error response status codes are corrected from 403 to 400 for the following endpoints:
Amend CIS Deductions For SubcontractorCreate CIS Deductions For SubcontractorRetrieve CIS Deductions For Subcontractor
- Updated endpoint
Amend CIS Deductions for Subcontractor- New error
RULE_TAX_YEAR_NOT_SUPPORTEDadded - Providing empty
periodDataarray now returns aRULE_INCORRECT_OR_EMPTY_BODY_SUBMITTEDerror
- New error
- Updated endpoint
Create CIS Deductions for Subcontractor- Providing empty
periodDataarray now returns aRULE_INCORRECT_OR_EMPTY_BODY_SUBMITTEDerror
- Providing empty
The following changes are now available in Production:
-
Some error response status codes are corrected from 403 to 400 for the following
v3.0endpoints:Submit a Self Assessment Final DeclarationTrigger a Self Assessment Tax Calculation
-
A new field is added to
Retrieve a Self Assessment Tax Calculationendpoint:-
underLowerProfitThresholdto sectioncalculation.taxCalculation.nics.class2Nics
-
-
New error codes are added for
Submit a Self Assessment Final Declarationendpoint:RULE_FINAL_DECLARATION_TAX_YEARRULE_FINAL_DECLARATION_IN_PROGRESS
-
New Gov-Test-Scenario header values added to support new errors
-
The
bissoption of thecalculationTypefield is removed fromList Self Assessment Tax Calculations -
Documentation has been updated for
List Self Assessment Tax Calculations- Description of the endpoint
- Description of the
calculationTimestampfield
The following changes are now available in Production:
-
Some error response status codes are corrected from 403 to 400 for the following
v4.0endpoints:Amend a Brought Forward Loss AmountCreate a Brought Forward LossCreate a Loss ClaimDelete a Brought Forward Loss
-
New API Version
v4.0is available with the following endpoints:List Loss ClaimsList Brought Forward Losses
Both endpoints replace their respective v3 equivalents, which are now deprecated, and not available in v4. Please use the new v4 endpoints instead.
The new endpoints require a tax year path parameter; previously this was an optional query parameter.
In v3, if either endpoint is called without the tax year query parameter, the array returned will include losses for all available tax years up to the latest completed tax year.
- Documentation updated to clarify description of
Create Loss Claimsendpoint.
The following changes are now available in Production:
- An error response status code is corrected from 403 to 400 for
Submit End of Period Statement for a Businessv2.0
The following changes are now available in Production:
- Updated endpoint
Delete Pension Charges- New error
RULE_TAX_YEAR_NOT_SUPPORTEDadded
- New error
- Documentation for
Delete Pension Chargesis updated with the missingmessageattribute added to all example error codes
The following changes are now available in Production:
- Some error response status codes are corrected from 403 to 400 for these endpoints:
Create and Amend DisclosuresCreate Marriage Allowance ClaimDelete Disclosures
The following changes are now available in Production:
-
RULE_TAX_YEAR_NOT_SUPPORTEDdescription and message are updated to indicate that there could be a maximum as well as a minimum supported tax year -
Updated documentation: The descriptions of these endpoints are updated:
Create And Amend Employment ExpensesIgnore Employment ExpensesCreate And Amend Other ExpensesDelete Other ExpensesRetrieve Other Expenses
-
Amend Employment Expensesrenamed toCreate And Amend Employment Expenses -
Amend Other Expensesrenamed toCreate And Amend Other Expenses
The following changes are now available in Production:
- Some error response status codes are corrected from 403 to 400 for the following endpoints:
Add a UK Savings AccountCreate and Amend ‘Report and Pay Capital Gains Tax on Property’ Overrides (PPD)Ignore EmploymentUnignore EmploymentAmend Custom EmploymentDelete Custom Employment
- Updated endpoint
Create and Amend Savings Income-
foreignTaxCreditReliefis changed from mandatory to optional
-
- Updated endpoint
Create and Amend Employment Financial Details- New error
NOT_ALLOWED_OFF_PAYROLL_WORKERis added
- New error
- Documentation is updated:
-
Capital Gains on Residential Property Disposalsresources are updated -
Create and Amend Employment Financial Detailsdescription is updated -
Delete Employment Financial Detailsdescription is updated -
Ignore Employmentdescription is updated -
Unignore Employmentdescription is updated -
Create and Amend a UK Savings Account Annual SummaryandRetrieve UK Savings Account Annual Summary-taxedUkInterestfield is updated -
Create and Amend Pensions IncomeandRetrieve Pensions Income-taxableAmountfield is updated -
Create And Amend Savings Incomerequest andRetrieve Savings Incomeresponse -grossAmountfield is updated -
Create And Amend Savings Incomerequest andRetrieve Savings Incomeresponse -specialWithholdingTaxfield is updated -
Create And Amend Dividends Incomerequest andRetrieve Dividends Incomeresponse -specialWithholdingTaxfield is updated
The following changes are now available in Production:
-
Error response status codes are corrected from 403 to 400 for
Create and Amend Other Reliefs. -
Description and message are updated for
RULE_TAX_YEAR_NOT_SUPPORTEDto indicate that there could be a maximum as well as a minimum supported tax year. -
Updated endpoint
Create And Amend Relief Investments-knowledgeIntensivefield is now optional
The following changes are now available in Production:
- Some error response status codes are corrected from 403 to 400 for the following endpoints:
Create State BenefitIgnore State BenefitUnignore State Benefit
- Updated documentation:
- Updated name and description for the endpoint
Amend State Benefit Amounts - Updated description for
Ignore State Benefit - Updated description for
Unignore State Benefit
- Updated name and description for the endpoint
- Added new Gov-Test-Scenario header values for
Ignore State Benefit,Unignore State Benefit,Amend State BenefitandCreate State Benefit, see sandbox changelog
The following changes are now available in Production:
- Some error response status codes are corrected from 403 to 400 for the following endpoints:
Retrieve Income Tax (Self Assessment) Crystallisation ObligationsRetrieve Income Tax (Self Assessment) End of Period Statement ObligationsRetrieve Income Tax (Self Assessment) Income and Expenditure Obligations
- Updated documentation:
- Updated the description for
ruleFromDateNotSupportederror - Renamed endpoint from
Retrieve Income Tax (Self Assessment) Crystallisation ObligationstoRetrieve Income Tax (Self Assessment) Final Declaration Obligations - Updated the downstream URL for all three endpoints
- Updated the description for
The following changes are now available in Production:
- Updated the description and message for
RULE_TAX_YEAR_NOT_SUPPORTEDto indicate that there could be a maximum as well as a minimum supported tax year - Updated documentation
- Endpoint
Amend Other Deductionsrenamed toCreate And Amend Other Deductions
The following changes are now available in Production:
- Updated the descriptions of:
Amend a Historic FHL UK Property Income & Expenses Period SummaryCreate a Historic FHL UK Property Income & Expenses Period SummaryCreate a Historic Non-FHL UK Property Income & Expenses Period Summary
The following changes are now available in Production:
-
Updated
List Self Assessment Payments & Allocation Details- addedMISSING_PAYMENT_LOT_ITEMandRULE_INCONSISTENT_QUERY_PARAMSerrors -
Updated documentation:
- Updated the description of
List Self Assessment Payments & Allocation Details - Updated the description and message for
RULE_TAX_YEAR_NOT_SUPPORTEDto indicate that there could be a maximum as well as a minimum supported tax year
- Updated the description of
The following changes are now available in Production:
- Error response status code corrected from 403 to 400 for
Retrieve a Business Income Source Summary
The following changes are now available in Production:
- Some error response status codes are corrected from 403 to 400 for the
v3.0following endpoints:Submit Foreign Property Accounting AdjustmentsSubmit Self-Employment Accounting AdjustmentsSubmit UK Property Accounting AdjustmentsTrigger a Business Source Adjustable Summary
The following changes are now available in Production:
-
New API Version
v2.0. The following endpoints have been updated to replace their respective v1 equivalents. Please use the new v2 endpoints instead. -
Create a Self-Employment Period Summary- Added
RULE_INVALID_SUBMISSION_PERIODandRULE_INVALID_SUBMISSION_END_DATEerrors
- Added
-
Create a Self-Employment Period Summary,Retrieve a Self-Employment Period Summary,Amend a Self-Employment Period Summary -
In all 3 endpoints, renamed
periodAllowableExpensesand all its properties to remove the word "allowable"; e.g.periodAllowableExpensesbecomesperiodExpenses. -
Updated documentation - updated the description of
periodExpensesfield
The following change is now available in the Sandbox:
For versions 1.0 and later, Gov-Test-Scenario values that are not supported by the sandbox will now result in a status
code 400 response with an error code of RULE_INCORRECT_GOV_TEST_SCENARIO.
The following changes are now available in the Sandbox.
Minor clarifications made to the developer hub documentation for the Create and Amend Pension Charges endpoint:
- Fixed the
isAnnualAllowanceReduceddescription to clarify that it's a mandatory field - Updated the
formatProviderNameandformatProviderAddresserror descriptions
The following changes are now available in the Sandbox:
- New Gov-Test-Scenario header values added to
Amend State BenefitandCreate State Benefit:START_DATE_AFTER_TAX_YEAR_ENDEND_DATE_BEFORE_TAX_YEAR_START
- New Gov-Test-Scenario header value added to
Ignore State Benefit,Unignore State BenefitandCreate State Benefit:TAX_YEAR_NOT_ENDED
The following changes are now available in the Sandbox:
- For version 1.0, Gov-Test-Scenario values that are not supported by the sandbox will now result in a status code 400
response with an error code of
RULE_INCORRECT_GOV_TEST_SCENARIO.
The following changes are now available in the Sandbox.
Minor clarifications made to developer hub documentation. The following descriptions were updated:
-
grossAmountfield inCreate And Amend Savings Incomerequest andRetrieve Savings Incomeresponse. -
specialWithholdingTaxfield inCreate And Amend Savings Incomerequest andRetrieve Savings Incomeresponse. -
specialWithholdingTaxfield inCreate And Amend Dividends Incomerequest andRetrieve Dividends Incomeresponse.
Minor clarifications made to developer hub documentation:
- Updated description of Create Loss Claims endpoint.
Updated Endpoint: Amend Loss Claims Order
- Fix HATEOAS links in response
Updated Endpoint: List Loss Claims
- Fix HATEOAS links in response
Minor clarifications made to developer hub documentation:
- Updated description of
periodExpensesfield in multiple endpoints.
The following changes are now available in the Sandbox.
New API Version v2.0
Updated Endpoint: Create and Amend Pension Charges (V2)
- Fields added to the
pensionContributionsrequest object:isAnnualAllowanceReduced,moneyPurchasedAllowance,taperedAnnualAllowance - Fields removed from the
pensionSavingsTaxChargesrequest object:isAnnualAllowanceReduced,moneyPurchasedAllowance,taperedAnnualAllowance
Updated Endpoint: Retrieve Pension Charges (V2)
- Fields added to the
pensionContributionsresponse object:isAnnualAllowanceReduced,moneyPurchasedAllowance,taperedAnnualAllowance - Fields removed from the
pensionSavingsTaxChargesresponse object:isAnnualAllowanceReduced,moneyPurchasedAllowance,taperedAnnualAllowance
The following changes are now available in the Sandbox.
- For versions 2.0 and later, Gov-Test-Scenario values that are not supported by the sandbox will now result in a status
code 400 response with an error code of
RULE_INCORRECT_GOV_TEST_SCENARIO.
The following changes are now available in the Sandbox.
New API Version v4.0
New endpoints in v4:
List Loss ClaimsList Brought Forward Losses
Both endpoints replace their respective v3 equivalents, which are now deprecated, and not available in v4. Please use the new v4 endpoints instead.
The new endpoints require a tax year path parameter; previously this was an optional query parameter.
In v3, if either endpoint is called without the tax year query param, the array returned will include losses for all available tax years up to the latest completed tax year.
Endpoint: Retrieve an Employment and its Financial Details
- Updated response data field
offPayrollWorkerto be optional
Endpoint: Submit a Self Assessment Final Declaration
-
New error codes added:
RULE_FINAL_DECLARATION_TAX_YEARRULE_FINAL_DECLARATION_IN_PROGRESS
-
New Gov-Test-Scenario header values added to support new errors.
The following changes are now available in the Sandbox.
New API Version v2.0
Endpoint: Retrieve a Self-Employment Period Summary
- Renamed
periodAllowableExpensesand all its properties, removing ‘allowable’- e.g
periodAllowableExpenses→periodExpenses
- e.g
Endpoint: Amend a Self-Employment Period Summary
- Renamed
periodAllowableExpensesand all its properties, removing ‘allowable’- e.g
periodAllowableExpenses→periodExpenses
- e.g
Endpoint: Create a Self-Employment Period Summary
- Renamed
periodAllowableExpensesand all its properties, removing ‘allowable’- e.g
periodAllowableExpenses→periodExpenses
- e.g
self-assessments-api v2.0 has now been deprecated
The following changes are now available in the Sandbox.
Endpoint: Create and Amend Pension Charges
- Fields added to the
pensionSavingsTaxChargesobject:isAnnualAllowanceReduced,moneyPurchasedAllowance,taperedAnnualAllowance - Fields removed from the
pensionContributionsobject:isAnnualAllowanceReduced,moneyPurchasedAllowance,taperedAnnualAllowance
Endpoint: Retrieve Pensions Charges
- Fields added to the
pensionSavingsTaxChargesobject:isAnnualAllowanceReduced,moneyPurchasedAllowance,taperedAnnualAllowance - Fields removed from the
pensionContributionsobject:isAnnualAllowanceReduced,moneyPurchasedAllowance,taperedAnnualAllowance
The following changes are now available in the Sandbox.
Endpoint: Retrieve a UK Property Income & Expenses Period Summary
- Added
periodCreationDatefield
Endpoint: Create a UK Property Income & Expenses Period Summary
- Added TYS downstream error codes for endpoint
Endpoint: Retrieve an Employment and its Financial Details
- New field
offPayrollWorkeradded to theemploymentobject
Endpoint: Create and Amend Employment Financial Details
- New field
offPayrollWorkeradded to theemploymentobject
The following changes were made to sandbox.
For the following endpoints, some error response status codes have been corrected from 403 Forbidden to 400 Bad Request:
- cis-deductions-api v1.0
- Amend CIS Deductions For Subcontractor
- Create CIS Deductions For Subcontractor
- Retrieve CIS Deductions For Subcontractor
- individual-calculations-api v3.0
- Submit a Self Assessment Final Declaration
- Trigger a Self Assessment Tax Calculation
- individual-losses-api v1.0
- Amend a Brought Forward Loss Amount
- Create a Brought Forward Loss
- Create a Loss Claim
- Delete a Brought Forward Loss
- individuals-business-eops-api v2.0
- Submit End of Period Statement for a Business
- individuals-disclosures-api v1.0
- Create and Amend Disclosures
- Create Marriage Allowance Claim
- Delete Disclosures
- individuals-income-received-api v1.0
- Add a UK Savings Account
- Create and Amend ‘Report and Pay Capital Gains Tax on Property’ Overrides (PPD)
- Ignore Employment
- Unignore Employment
- individuals-reliefs-api v1.0
- Create and Amend Other Reliefs
- individuals-state-benefits-api v1.0
- Create State Benefit
- Ignore State Benefit
- Unignore State Benefit
- obligations-api v1.0
- Retrieve Income Tax (Self Assessment) Crystallisation Obligations
- Retrieve Income Tax (Self Assessment) End of Period Statement Obligations
- Retrieve Income Tax (Self Assessment) Income and Expenditure Obligations
- self-assessment-biss-api v2.0
- Retrieve a Business Income Source Summary
- self-assessment-bsas-api v3.0
- Submit Foreign Property Accounting Adjustments
- Submit Self-Employment Accounting Adjustments
- Submit UK Property Accounting Adjustments
- Trigger a Business Source Adjustable Summary
The following changes were made to sandbox.
For the following APIs, the RULE_TAX_YEAR_NOT_SUPPORTED description and message have been updated to indicate that there could be a maximum as well as a minimum supported tax year:
- individuals-charges-api v1.0
- individuals-expenses-api v1.0
- individuals-income-received-api v1.0
- individuals-reliefs-api v1.0
- individuals-state-benefits-api v1.0
- other-deductions-api v1.0
- self-assessment-accounts-api v2.0
For endpoint Create And Amend Other Expenses:
- Update endpoint name to include ‘create’.
✂️ Deprecation of API versions API version Deprecation Deployed to Production
-
The following API versions have been deprecated:
- Individual Calculations API V2.0
- Individual Business End of Period API V1.0
These deprecated versions cannot be subscribed to any longer. However, they can be called if the subscription was made before this status change.
✂️ Deprecation of API versions API version Deprecation Deployed to Sandbox
-
The following API versions have been deprecated:
- Self Assessment Accounts API V1.0
These deprecated versions cannot be subscribed to any longer. However, they can be called if the subscription was made before this status change.
For endpoint:
Retrieve a Self Assessment Tax Calculation
- Added new field underLowerProfitThreshold to section calculation.taxCalculation.nics.class2Nics.
- Added totalAllowancesAndDeductions field Path: calculation.endOfYearEstimate.totalAllowancesAndDeductions.
- Added totalBasicRateExtension, giftAidRelief, pensionContributionReliefs new field Path: calculation.reliefs.basicRateExtension.
- Added offPayrollWorker (OPW) flag for API#1885. Path: calculation.employmentAndPensionsIncome.employmentAndPensionsIncomeDetail.
- Minor re-wording of the Coding Out endpoint descriptions in the API documentation.
- Update the API documentation to clarify usage of "historic" endpoints.
The following changes were made to production.
The following Payments & Liabilities and Coding our Underpayments and Debts endpoints are now available:
Retrieve History of a Self Assessment ChargeRetrieve Self Assessment Balance and TransactionsList Self Assessment Payments & Allocation DetailsRetrieve Coding Out underpayments and debt amountsCreate or Amend Coding out underpayment and debt amountsDelete Coding Out underpayments and debt amounts
The following Historic FHL and non-FHL UK Property Business endpoints are now available:
Retrieve a Historic FHL UK Property Business Annual SubmissionCreate and Amend a Historic FHL UK Property Business Annual SubmissionDelete a Historic FHL UK Property Business Annual SubmissionRetrieve a Historic Non-FHL UK Property Business Annual SubmissionCreate and Amend a Historic Non-FHL UK Property Business Annual SubmissionDelete a Historic Non-FHL UK Property Business Annual SubmissionList Historic FHL UK Property Income & Expenses Period SummaryCreate a Historic FHL UK Property Income & Expenses Period SummaryRetrieve a Historic FHL UK Property Income & Expenses Period SummaryAmend a Historic FHL UK Property Income & Expenses Period SummaryList Historic Non-FHL UK Property Income & Expenses Period SummaryCreate a Historic Non-FHL UK Property Income & Expenses Period SummaryRetrieve a Historic Non-FHL UK Property Income & Expenses Period SummaryAmend a Historic Non-FHL UK Property Income & Expenses Period Summary
The following Dividends and Savings Income endpoints are now available:
Retrieve Dividends IncomeCreate and Amend Dividends IncomeDelete Dividends IncomeCreate and Amend Savings IncomeRetrieve Savings IncomeDelete Savings IncomeList All UK Savings AccountsAdd a UK Savings Account
The following Charitable Givings endpoints are now available:
Retrieve Charitable Giving Tax ReliefCreate and Amend Charitable Giving Tax ReliefDelete Charitable Giving Tax Relief
The following endpoints are now available:
Retrieve a Self-Employment Annual SubmissionCreate and Amend a Self-Employment Annual SubmissionDelete a Self-Employment Annual SummaryList Self-Employment Period SummariesCreate a Self-Employment Period SummaryRetrieve a Self-Employment Period SummaryAmend a Self-Employment Period Summary
The following changes were made to sandbox.
For endpoint:
-
List Self Assessment Tax Calculations- RULE_TAX_YEAR_NOT_SUPPORTED description and message updated to indicate that there could be a maximum as well as a minimum supported tax year.
- taxYear query parameter description updated to clarify that calculations from a single tax year are returned with the default as the current tax year.
For endpoint:
-
Retrieve a Self Assessment Tax Calculation- RULE_TAX_YEAR_NOT_SUPPORTED description and message updated to indicate that the endpoint returns calculations from a single tax year, which by default is the current tax year.
For endpoint:
-
Trigger a Self Assessment Tax Calculation- RULE_TAX_YEAR_NOT_SUPPORTED description and message updated to indicate that there could be a maximum as well as a minimum supported tax year.
- New error codes added applicable to tax years from 2023-24: RULE_INCOME_SOURCES_CHANGED, RULE_RESIDENCY_CHANGED, RULE_TAX_YEAR_NOT_ENDED, RULE_RECENT_SUBMISSIONS_EXIST, RULE_CALCULATION_IN_PROGRESS, and RULE_BUSINESS_VALIDATION_FAILURE.
- New Gov-Test-Scenario header values added to support new errors.
For endpoints:
Delete Self-Employment Annual SubmissionCreate and Amend Self-Employment Annual Submission- and
Retrieve a Self-Employment Annual Submission- RULE_TAX_YEAR_NOT_SUPPORTED description and message updated to indicate that there could be a maximum as well as a minimum supported tax year.
For endpoint:
-
Create Self-Employment Period Summary- New error codes added applicable to tax years from 2023-24: RULE_TAX_YEAR_NOT_SUPPORTED, RULE_DUPLICATE_SUBMISSION.
- New Gov-Test-Scenario header values added to support new errors.
For endpoint:
-
Amend Self-Employment Period Summary- New taxYear query parameter added that must be supplied only for tax years from 2023-24.
- New error codes added applicable to tax years from 2023-24: RULE_TAX_YEAR_NOT_SUPPORTED, FORMAT_TAX_YEAR, RULE_TAX_YEAR_RANGE_INVALID.
- New error codes added applicable to tax years earlier than 2023-24: INVALID_TAX_YEAR_PARAMETER.
- New Gov-Test-Scenario header values added to support new errors.
For endpoints:
Create and Amend a Foreign Property Annual SubmissionCreate and Amend a UK Property Business Annual SubmissionRetrieve a Foreign Property Annual SubmissionRetrieve a UK Property Business Annual SubmissionCreate a Foreign Property Income & Expenses Period SummaryCreate a UK Property Income & Expenses Period SummaryAmend a Foreign Property Income & Expenses Period SummaryAmend a UK Property Income & Expenses Period SummaryList Property Income & Expenses Period SummariesRetrieve a Foreign Property Income & Expenses Period SummaryRetrieve a UK Property Income & Expenses Period Summary- and
Delete a Property Annual Submission- RULE_TAX_YEAR_NOT_SUPPORTED description and message updated to indicate that there could be a maximum as well as a minimum supported tax year.
For endpoint:
-
Retrieve a Business Income Source Summary- RULE_TAX_YEAR_NOT_SUPPORTED description and message updated to indicate that there could be a maximum as well as a minimum supported tax year.
For endpoint:
-
Submit End of Period Statement for a Business- For tax years from 2023-24 a generic RULE_BUSINESS_VALIDATION_FAILURE can occur without an errorId.
- New error codes added applicable to tax years from 2023-24: RULE_TAX_YEAR_NOT_SUPPORTED.
- New Gov-Test-Scenario header values added to support new errors.
For endpoint:
-
List Loss Claims- RULE_TAX_YEAR_NOT_SUPPORTED description and message updated to indicate that there could be a maximum as well as a minimum supported tax year.
- taxYearClaimedFor is mandatory for returning data related to tax years from 2023-24.
For endpoint:
-
List Brought Forward Losses- RULE_TAX_YEAR_NOT_SUPPORTED description and message updated to indicate that there could be a maximum as well as a minimum supported tax year.
- taxYearBroughtForwardFrom is mandatory for returning data related to tax years from 2023-24.
For endpoints:
Submit Foreign Property Accounting AdjustmentsSubmit UK Property Accounting Adjustments- and
Submit Self-Employment Accounting Adjustments- New taxYear query parameter added that must be supplied only for tax years from 2023-24.
- New error codes added applicable to tax years from 2023-24: RULE_TAX_YEAR_NOT_SUPPORTED, FORMAT_TAX_YEAR, RULE_TAX_YEAR_RANGE_INVALID.
- New error codes added applicable to tax years earlier than 2023-24: INVALID_TAX_YEAR_PARAMETER.
- New Gov-Test-Scenario header values added to support new errors.
For endpoint:
-
Trigger a Business Source Adjustable Summary- New error codes added applicable to tax years from 2023-24: RULE_TAX_YEAR_NOT_SUPPORTED.
- New Gov-Test-Scenario header values added to support new errors.
For endpoint:
-
List Business Source Adjustable Summaries- RULE_TAX_YEAR_NOT_SUPPORTED description and message updated to indicate that there could be a maximum as well as a minimum supported tax year.
For endpoints:
Retrieve a Foreign Property Business Source Adjustable SummaryRetrieve a Self-Employment Business Source Adjustable Summary- and
Retrieve a UK Property Business Source Adjustable Summary- New taxYear query parameter added that must be supplied only for tax years from 2023-24.
- New error codes added applicable to tax years from 2023-24: RULE_TAX_YEAR_NOT_SUPPORTED, FORMAT_TAX_YEAR, RULE_TAX_YEAR_RANGE_INVALID.
- New error codes added applicable to tax years earlier than 2023-24: INVALID_TAX_YEAR_PARAMETER.
- New Gov-Test-Scenario header values added to support new errors.
14 November 2022
- self-assessment-biss-api
🎊 New endpoints available for testing in Sandbox v2.0 Documentation + Testable in Sandbox
Endpoints for self-assessment-biss-api:
- Retrieve a Business Income Source Summary
The updates can be found in the documentation on the developer hub
31 October 2022
- New
taxYear query parameter for a small number of APIs
taxYear query parameter for a small number of APIsNew taxYear query parameter for a small number of APIs, now available for testing in Sandbox. This parameter will be required from tax years 2023-24 onwards, but should not be included for tax years prior to that.
The following API endpoints are affected and available for testing:
- List self-employment period summaries
- Retrieve a self-employment period summary
- Delete CIS deductions for a subcontractor
Click the above links for the API developer documentation.
28 October 2022
- self-assessment-accounts-api
🎊 New endpoints available for testing in Sandbox v2.0 Documentation + Testable in Sandbox
Endpoints for self-assessment-accounts-api:
- Retrieve History of a Self Assessment Charge
- Retrieve Self Assessment Balance & Transactions
- List Self Assessment Payments & Allocation Details
The updates can be found in the documentation on the developer hub
21 October 2022
- individuals-reliefs-api
🎊 New endpoints available for testing in Sandbox v1.0 Documentation + Testable in Sandbox
Endpoints for Charitable Giving:
- Create & Amend Charitable Giving Tax Relief for a Tax Year
- Retrieve Charitable Giving Tax Relief for a Tax Year
- Delete Charitable Giving Tax Relief for a Tax Year
The updates can be found in the documentation on the developer hub
17 October 2022
- property-business-api
🎊 New endpoints available for testing in Sandbox v2.0 Documentation + Testable in Sandbox
Endpoints for Historic Furnished Holiday Lettings (FHL) UK Property Business Annual Submission:
- Retrieve a Historic Furnished Holiday Lettings (FHL) UK Property Business Annual Submission
- Create & Amend a Historic FHL UK Property Business Annual Submission
- Delete a Historic FHL Uk Property Business Annual Submission
Endpoints for Historic Non-Furnished Holiday Lettings (Non-FHL) UK Property Business Annual Submission:
- Retrieve a Historic Non-FHL UK Property Business Annual Submission
- Create & Amend a Historic Non-FHL UK Property Business Annual Submission
- Delete a Historic Non-FHL UK Property Business Annual Submission
Endpoints for Historic Furnished Holiday Lettings (FHL) UK Property Income & Expenses Period Summary:
- Retrieve a Historic FHL UK Property Income & Expenses Period Summary
- Amend a Historic FHL UK Property Income & Expenses Period Summary
- Create a Historic FHL Property Income & Expenses Period Summary
- List Historic FHL Property Income & Expenses Period Summary
Endpoints for Historic Non-Furnished Holiday Lettings (Non-FHL) UK Property Income & Expenses Period Summary:
- Retrieve a Historic non-FHL Property Income & Expenses Period Summary
- Amend a Historic non-FHL Property Income & Expenses Period Summary
- Create a Historic non-FHL Property Income & Expenses Period Summary
- List Historic FHL Property Income & Expenses Period Summary
The updates can be found in the documentation on the developer hub
14 October 2022
These changes are available for testing in Sandbox
- individuals-income-received-api
These changes are available for testing in SandboxCreate and amend UK dividends income annual summary & Create and Amend a UK savings account annual summary -
Downstream Request URL changed specific for 23/24 tax year & newer only
Downstream Tax Year format has changed (eg. 23-24)
Updated tax year format in downstream request mapping
Changes to downstream errors:
- Renamed INVALID_TYPE(400) to INVALID_INCOMESOURCE_TYPE(400)
- Renamed INVALID_TAXYEAR(400) to INVALID_TAX_YEAR(400)
- Added INVALID_CORRELATIONID (400)
- Removed INVALID_PAYLOAD from 422
- NOT_FOUND_INCOME_SOURCE was previously a 403 code, this is now renamed to INCOME_SOURCE_NOT_FOUND and is now a 404 code
- Added INCOMPATIBLE_INCOME_SOURCE (422)
- Added TAX_YEAR_NOT_SUPPORTED (422)
- MISSING_CHARITIES_NAME_GIFT_AID was previously a 403 code, this is now a 422 code
- MISSING_GIFT_AID_AMOUNT was previously a 403 code, this is now a 422 code
- MISSING_CHARITIES_NAME_INVESTMENT was previously a 403 code, this is now a 422 code
- MISSING_INVESTMENT_AMOUNT was previously a 403 code, this is now a 422 code
- INVALID_ACCOUNTING_PERIOD was previously a 403 code, this is now a 422 code
- Removed NOT_FOUND (404)
- Updated vendor error message and description for TAX_YEAR_NOT_SUPPORTED
Retrieve UK dividends income annual summary & Retrieve UK savings account annual summary -
Downstream Request URL changed specific for 23/24 tax year & newer only
Downstream Tax Year format has changed (eg. 23-24)
Changes to downstream errors:
- INVALID_TAXYEAR (400) changed to INVALID_TAX_YEAR
- Added INVALID_CORRELATION_ID (400)
- INVALID_INCOME_SOURCE (400) changed to INVALID_INCOMESOURCE_ID (400)
- Added INVALID_INCOMESOURCE_TYPE (400)
- NOT_FOUND_PERIOD (404) renamed to SUBMISSION_PERIOD_NOT_FOUND
- NOT_FOUND_INCOME_SOURCE (404) there are currently 2 codes with different descriptions, there is now only 1 code renamed to INCOME_DATA_SOURCE_NOT_FOUND
- Added new code TAX_YEAR_NOT_SUPPORTED (422)
- Updated vendor error message and description for TAX_YEAR_NOT_SUPPORTED
Retrieve other employment income -
Downstream Request URL changed specific for 23/24 tax year & newer only
Downstream Tax Year format has changed (eg. 23-24)
Use the already existing taxYear parameter for TYS backend APIs as well.
SchemePlanType was incorrect, EMI is now Enterprise Management Incentive instead of Equated Monthly Instalment
Changes to downstream errors:
- NO_DATA_FOUND (404) re-named to NOT_FOUND (404)
- Added TAX_YEAR_NOT_SUPPORTED (422)
- Updated vendor error message and description for RULE_TAX_YEAR_NOT_SUPPORTED
Delete other employment income
Downstream Request URL changed specific for 23/24 tax year & newer only
Downstream Tax Year format has changed (eg. 23-24)
Changes to downstream errors:
- Added downstream error code TAX_YEAR_NOT_SUPPORTED (422)
- Updated vendor error message and description for RULE_TAX_YEAR_NOT_SUPPORTED
25 August 2022
This change is available for testing in the Sandbox
- self-assessment-accounts-api
This change is available for testing in the Sandbox🔧 DUPLICATE_ID_NOT_ALLOWED Error code added
The "Create or Amend Coding Out underpayment and debt amounts" endpoint doesn't allow duplicate ID values in the request. Requests with duplicate IDs will now result in the DUPLICATE_ID_NOT_ALLOWED response error code.
The documentation for this change can be found on the developer hub
26 July 2022
Now Available in Production
New API versions:
- individual-calculations-api
v3.0
Now Available in Productionv3.0
individual-calculations-api v3.0 documentation
🔧 Updates to the following endpoint v3.0 Available in Production
- List Self Assessment Tax Calculations
- Trigger a Self Assessment Tax Calculation
- Submit a Self Assessment Final Declaration
- Retrieve a Self Assessment Tax Calculation
13 June 2022
- self-employment-business-api
🎉 New API Version - v1.0 Now Available in Sandbox
🎊 Endpoints available for testing in Sandbox v1.0 Documentation + Testable in Sandbox
- Retrieve a Self-Employment Annual Submission
- Create and Amend Self-Employment Annual Submission
- Delete a Self-Employment Annual Submission
- List Self-Employment Period Summaries
- Create a Self-Employment Period Summary
- Retrieve a Self-Employment Period Summary
- Amend a Self-Employment Period Summary
The updates can be found in the documentation on the developer hub
25 May 2022
- individual-business-eops-api
🎉 New API Version - v2.0 Now Available in Sandbox
🎊 Endpoint available for testing in Sandbox v2.0 Documentation + Testable in Sandbox
- Submit End of Period Statement for a Business
The updates can be found in the documentation on the developer hub
25 May 2022
- individual-calculations-api
🔧 Updates to the following endpoint v3.0
-
Retrieve a Self Assessment Tax Calculation
-
typein inputs.allowancesReliefsAndDeductions array changed to optional -
dtaRatein calculation.reliefs.foreignTaxCreditRelief.foreignTaxCreditReliefDetail array now allows decimal values up to 2 decimal places
-
The updates can be found in the documentation on the developer hub
23 May 2022
- individuals-income-received-api
The field occupationalPension will now be returned for customer added employments
The updates can be found in the documentation on the developer hub
17 May 2022
- individual-calculations-api
🎉 New API Version - v3.0 Now Available in Sandbox
🎊 Endpoints available for testing in Sandbox v3.0 Documentation + Testable in Sandbox
- List Self Assessment Tax Calculations
- Trigger a Self Assessment Tax Calculation
- Retrieve a Self Assessment Tax Calculation
- Submit a Self Assessment Final Declaration
The updates can be found in the documentation on the developer hub
27 April 2022
- individual-losses-api
- self-assessment-biss-api
⛔️ Retirement of API versions API version retirement No Longer Available in Sandbox and Production
-
The following API versions have been retired and are no longer available in Sandbox and Production:
- Individual Losses API V2.0
- Business Income Source Summary V1.0
14 April 2022
- property-business-api
- self-assessment-biss-api
- individual-losses-api
- self-assessment-bsas-api
property-business-api, self-assessment-biss-api, individual-losses-api, and self-assessment-bsas-api
✂️ Deprecation of API versions API version Deprecation Deployed to Production
-
The following API versions have been deprecated:
- Property Business API V1.0
- Business Income Source Summary API V1.0
- Individual Losses API V2.0
- Business Source Adjustable Summary API V2.0
These deprecated versions cannot be subscribed to any longer. However, they can be called if the subscription was made before this status change.
30 March 2022
- individuals-income-received-api
individuals-income-received-api documentation
🔧 Updates to the following endpoint v1.0 Available in Production
- Delete a Custom Employment
- New error (RULE_DELETE_FORBIDDEN) when attempting to delete an HMRC held employment
- Corresponding new Gov-Test-Scenario (DELETE_FORBIDDEN)
22 March 2022
Now Available in Production
New API versions:
- individual-losses-api
v3.0
- self-assessment-biss-api
v2.0
- self-assessment-bsas-api
v3.0
- property-business-api
v2.0
Updates:
- self-assessment-api
v2.0
- individuals-income-received-api
v1.0
- individuals-business-eops-api
v1.0
Now Available in Productionv3.0
v2.0
v3.0
v2.0
v2.0
v1.0
v1.0
individual-losses-api v3.0 documentation
🔧 Business ID is now mandatory for UK Property.
self-assessment-biss-api v2.0 documentation
🔧 Business ID is now mandatory for UK Property. Redesigned endpoint.
self-assessment-bsas-api v3.0 documentation
🔧 Additional fields and redesigned 'summary' response.
property-business-api v2.0 documentation
🔧 Additional fields for Foreign Property. Additional endpoints for UK Property for tax years 2022-23 onwards. For UK property previous years, continue to use self-assessment-api.
self-assessment-api v2.0 documentation
🔧 Additional tax year rules for UK Property periods and annuals, which support up to tax year 2021-22. Additional rules for self-employment annuals regarding the field 'tradingIncomeAllowance'.
individuals-income-received-api v1.0 documentation
🔧 Retrieve All CGT Residential Property Disposals and Overrides (Includes PPD and Non-PPD) updated with new field 'ppdYearToDate'.
individuals-business-eops-api v1.0 documentation
🔧 Additional errors added.
21 March 2022
- self-assessment-bsas-api
🔧 Updates to the following endpoint v3 Deployed to Sandbox
- Retrieve a Self-Employment Business Source Adjustable Summary (BSAS)
-
taxableProfitandadjustedIncomeTaxLossinadjustableSummaryCalculationchanged to integers -
adjustedSummaryCalculationobject changed to optional -
costOfGoodsBoughtDisallowableinadjustedSummaryCalculation.additionsrenamed tocostOfGoodsDisallowable - Responses section updated to include three examples; Full expenses, Consolidated Expenses and Trading Allowance.
-
The updates can be found in the documentation on the developer hub
17 March 2022
- self-assessment-bsas-api
🔧 Updates to the following endpoint v3 Deployed to Sandbox
- Retrieve a Self-Employment Business Source Adjustable Summary (BSAS)
- the
goodAndServicesOwnUsefield has been renamedgoodsAndServicesOwnUse(inadjustableSummaryCalculation.additionsand inadjustedSummaryCalculation.additions)
- the
The updates can be found in the documentation on the developer hub
9 March 2022
- self-assessment-api
- property-business-api
🔧 Updates to the following endpoint r3 Deployed to Sandbox
- Update and Retrieve Properties (both FHL and Other) Annual Summary
- Update and Retrieve Self-Employment Annual Summary
-
lossBroughtForwardelement has been removed fromadjustments
-
The updates can be found in the documentation on the developer hub
🔧 Updates to the following endpoint all versions Deployed to Sandbox
- Amend and Retrieve Annual Summary
-
lossBroughtForwardelement has been removed fromadjustments
-
The updates can be found in the documentation on the developer hub
2 March 2022
- individuals-income-received-api
🔧 Updates to the following endpoint v1.0 Deployed to Sandbox
- Retrieve an Employment
- The addition of the optional boolean field
occupationalPension
- The addition of the optional boolean field
The updates can be found in the documentation on the developer hub
28 February 2022
- individuals-expenses-api
- self-assessment-biss-api
🔧 Amend Employment Expenses v1.0 Sandbox
- new gov-test-scenario added (NOT_FOUND)
- new error - MATCHING_RESOURCE_NOT_FOUND
🔧 Ignore Employment Expenses v1.0 Sandbox
- new gov-test-scenario added (NOT_FOUND)
- new error - MATCHING_RESOURCE_NOT_FOUND
The updates can be found in the documentation on the developer hub
📖 Retrieve Business Income Source Summary v2.0 Sandbox
- Added RULE_NO_INCOME_SUBMISSIONS_EXIST error and gov-test-scenario to Documentation
The updates can be found in the documentation on the developer hub
24 February 2022
- self-assessment-bsas-api
- individual-losses-api
🎉 New API Version - v3.0 Now Available in Sandbox
🎊 Endpoints available for testing in Sandbox v3.0 Documentation + Testable in Sandbox
- List Business Source Adjustable Summaries
- Trigger a Business Source Adjustable Summary
- Retrieve a Self Employment Business Source Adjustable Summary (BSAS)
- Submit Self-Employment Accounting Adjustments
- Retrieve a UK Property Business Source Adjustable Summary (BSAS)
- Submit UK Property Accounting Adjustments
- Retrieve a Foreign Property Business Source Adjustable Summary (BSAS)
- Submit Foreign Property Accounting Adjustments
The updates can be found in the documentation on the developer hub
🎉 New API Version - v3.0 Now Available in Sandbox
🎊 Endpoints available for testing in Sandbox v3.0 Documentation + Testable in Sandbox
- List Brought Forward Losses
- Create a Brought Forward Loss
- Retrieve a Brought Forward Loss
- Delete a Brought Forward Loss
- Amend a Brought Forward Loss Amount
- List Loss Claims
- Create a Loss Claim
- Retrieve a Loss Claim
- Delete a Loss Claim
- Amend a Loss Claim Type
- Amend Loss Claims Order
The updates can be found in the documentation on the developer hub
22 February 2022
- self-assessment-bsas-api
- individuals-business-eops-api
📖 Endpoint with only documentation available in Sandbox v3.0 Documentation only
- Submit Self-Employment Accounting Adjustments
🔧 Updates to the following endpoint v3.0 Documentation only
-
Retrieve a Foreign Property Business Source Adjustable Summary
- The following fields have been updated from integers to decimals for Foreign Non-FHL
- adjustableSummaryCalculation.countryLevelDetail.taxableProfit
- adjustableSummaryCalculation.countryLevelDetail.adjustedIncomeTaxLoss
- adjustedSummaryCalculation.countryLevelDetail.taxableProfit
- adjustedSummaryCalculation.countryLevelDetail.adjustedIncomeTaxLoss
- The following fields have been updated from integers to decimals for Foreign Non-FHL
The updates can be found in the documentation on the developer hub
🔧 Updates to the following endpoint v1.0 Testable in Sandbox
-
Submit End of Period Statement for a Business
- New error RULE_BUSINESS_VALIDATION_FAILURE, with Gov-Test-Scenario.
21 February 2022
- self-assessment-bsas-api
📖 Documentation updated for the following endpoints v3.0 Documentation only
- Retrieve a Foreign Property Business Source Adjustable Summary
The updates can be found in the documentation on the developer hub
17 February 2022
- self-assessment-bsas-api
📖 Documentation updated for the following endpoints v3.0 Documentation only
-
Retrieve a UK Property Business Source Adjustable Summary
- Field
inputs.submissionPeriodsmarked as mandatory (as per Foreign Property and Self-Employment endpoints)
- Field
-
Retrieve a UK Property Business Source Adjustable Summary, Retrieve a Foreign Property Business Source Adjustable Summary and Retrieve a Self-Employment Property Business Source Adjustable Summary
- Field
inputs.typeOfBusinessmarked as mandatory
- Field
The updates can be found in the documentation on the developer hub
17 February 2022
- individuals-income-received-api
- self-assessment-bsas-api
🔧 Updates to the following endpoint v1.0 Deployed to Sandbox
Retrieve All CGT Residential Property Disposals and Overrides
- The removal of the 'ppdReturnCharge' field in 'MultiplePropertyDisposals' and 'SinglePropertyDisposals' objects
- The addition of the 'ppdYearToDate' in the 'PpdService' object
The updates can be found in the documentation on the developer hub
📖 Endpoint with only documentation available in Sandbox v3.0 Documentation only
- Submit UK Property Accounting Adjustments
🔧 Update to the following endpoints v3.0 Documentation only
- Retrieve a UK Property Business Source Adjustable Summary
- Submit UK Property Accounting Adjustments
Url changed to state 'uk-property' instead of 'property'
The updates can be found in the documentation on the developer hub
16 February 2022
- self-assessment-bsas-api
- individuals-business-eops-api
📖 Endpoint with only documentation available in Sandbox v3.0 Documentation only
- Submit Foreign Property Accounting Adjustments
The updates can be found in the documentation on the developer hub
🔧 Gov-Test-Scenario Updates v1.0 Deployed to Sandbox
- The updates to the Gov-Test-Scenarios for
Submit End of Period Statement for a Businessinclude the following:- The removal of
RULE_prefix from Gov-Test-Scenarios - MATCHING_RESOURCE_NOT_FOUND updated to NOT_FOUND
- The addition of the new Gov-Test-Scenarios CONSOLIDATED_EXPENSES and MISMATCHED_END_DATE.
- The removal of
The updates can be found in the documentation on the developer hub
15 February 2022
- self-assessment-bsas-api
📖 Endpoint with only documentation available in Sandbox v3.0 Documentation only
- Trigger a Business Source Adjustable Summary
The updates can be found in the documentation on the developer hub
14 February 2022
- self-assessment-api
- self-assessment-bsas-api
🔧 Updates to the following endpoints v2.0 Deployed to Sandbox
- Get a self-employment annual summary
-
Amend a self-employment annual summary
- Updated max value of
1000.00for allowances.tradingAllowance - Removal of field nonFinancials.payVoluntaryClass2Nic
- Updated max value of
ℹ️
Self Assessment API UK Property periodics and annuals endpoints are available for tax years up to 2021-22.
Future years are supported by the Property Business API.
- Create a non-FHL UK property update period
- Get a non-FHL UK property business annual summary
- Amend a non-FHL UK property business annual summary
- Create a FHL UK property update period
- Get a FHL UK property business annual summary
-
Amend a FHL UK property business annual summary
- New error
RULE_TAX_YEAR_NOT_SUPPORTEDwhen using tax year 2022-23 onwards. - New Gov-Test-Scenario header
RULE_TAX_YEAR_NOT_SUPPORTED.
- New error
The updates can be found in the documentation on the developer hub
🔧 Add RULE_TYPE_OF_BUSINESS_INCORRECT error for retrievals endpoints (to match corresponding submission endpoints) v3.0 Deployed to Sandbox
-
Retrieve a Self Employment Business Source Adjustable Summary (BSAS)
- Error replaces RULE_NOT_SELF_EMPLOYMENT
-
Retrieve a UK Property Business Source Adjustable Summary (BSAS)
- Error replaces RULE_NOT_UK_PROPERTY
-
Retrieve a Foreign Property Business Source Adjustable Summary (BSAS)
- Error replaces RULE_NOT_FOREIGN_PROPERTY
The updates can be found in the documentation on the developer hub
11 February 2022
- self-assessment-api
- self-assessment-bsas-api
🔧 Updated description and example capitalAllowanceSingleAssetPool field v2.0 Deployed to Sandbox
- Get a self-employment annual summary
- Amend a self-employment annual summary
The updates can be found in the documentation on the developer hub
🔧 Updated description and example capitalAllowanceSingleAssetPool field v3.0 Deployed to Sandbox
- Retrieve a Self Employment Business Source Adjustable Summary (BSAS)
The updates can be found in the documentation on the developer hub
10 February 2022
- self-assessment-bsas-api
📖 Endpoint with only documentation available in Sandbox v3.0 Documentation only
- List Business Source Adjustable Summaries
The updates can be found in the documentation on the developer hub
8 February 2022
- self-assessment-bsas-api
- individual-calculations-api
🔧 Removed rentReceived field v3.0 Deployed to Sandbox
- Retrieve a UK Property Business Source Adjustable Summary
The updates can be found in the documentation on the developer hub
🔧 Response Updates Retrieve Self Assessment Tax Calculation Allowances, Deductions and Reliefs v2.0 Deployed to Sandbox and Production
- The following updates were made to Retrieve Self Assessment Tax Calculation Allowances, Deductions and Reliefs response:
- The 404 NO_ALLOWANCES_DEDUCTIONS_RELIEFS_EXIST error will no longer be returned
- A 200 success response with empty details will now be returned in the event that no data exists for allowances, deductions and reliefs
- Gov-Test-Scenario NO_ALLOWANCES_DEDUCTIONS_RELIEFS_EXIST updated to return a success with a note added in the scenario section of the documentation.
The updates can be found in the documentation on the developer hub
4 February 2022
- self-assessment-bsas-api
🔧 Updated HATEOAS links v3.0 Deployed to Sandbox
- Retrieve a Self-Employment Business Source Adjustable Summary
- Retrieve a UK Property Business Source Adjustable Summary
The updates can be found in the documentation on the developer hub
2 February 2022
- property-business-api
🔧 New error RULE_TYPE_OF_BUSINESS_INCORRECT and corresponding Gov-Test-Scenario v2.0 Deployed to Sandbox
- Create a Foreign Property Income & Expenses Period Summary [test only]
- Create a UK Property Income & Expenses Period Summary [test only]
The documentation for these new resources can be found on the developer hub
28 January 2022
- self-assessment-bsas-api
📖 Endpoints with only documentation available in Sandbox v3.0 Documentation only
- Retrieve a Self-Employment Business Source Adjustable Summary
- Retrieve a UK Property Business Source Adjustable Summary
The updates can be found in the documentation on the developer hub
21 January 2022
- self-assessment-biss-api
📖 Endpoints with only documentation available in Sandbox v2.0 Documentation only
- Retrieve a Business Income Source Summary
The updates can be found in the documentation on the developer hub
18 January 2022
- individual-losses-api
📖 Endpoints with only documentation available in Sandbox v3.0 Documentation only
- Amend Loss Claims Order
- Delete a Loss Claim
The updates can be found in the documentation on the developer hub
13 January 2022
- individual-losses-api
🔧 New Fields and Gov-Test-Scenarios Added
-
The following mandatory fields have been added to List Brought Forward Losses response:
- businessId
- typeOfLoss
- lossAmount
- taxYearBroughtForwardFrom
- lastModified
-
The following Gov-Test-Scenarios have been added to List Brought Forward Losses:
- SELF_EMPLOYMENT
- UK_PROPERTY
- FOREIGN_PROPERTY
📖 Endpoint with only documentation available in Sandbox v3.0 Documentation only
- Delete a Brought Forward Loss
The updates can be found in the documentation on the developer hub
10 January 2022
- individual-losses-api
📖 Endpoints with only documentation available in Sandbox v3.0 Documentation only
- List Loss Claims
- Create Loss Claims
The updates can be found in the documentation on the developer hub
7 January 2022
- individual-losses-api
📖 Endpoints with only documentation available in Sandbox v3.0 Documentation only
- Amend a Loss Claim Type
- Retrieve a Loss Claim
The updates can be found in the documentation on the developer hub
4 January 2022
- individual-losses-api
📖 Endpoints with only documentation available in Sandbox v3.0 Documentation only
- Create a Brought Forward Loss
- Amend a Brought Forward Loss Amount
- Retrieve a Brought Forward Loss
- List Brought Forward Losses
The updates can be found in the documentation on the developer hub
17 December 2021
- income-tax-mtd-end-to-end-service-guide
🔧 Service Guide Content Updates Content Updates Deployed to Production
The updates in the service guide include:
-
Set upheading replaced bySign upwith the menu tree updated to only have three sections;Agent,IndividualandLink software to HMRC. - Updated content in the
Minimum functionality standardssection with two other sections added;Bridging softwareandNon-MTD products - Updated content in
The DeclarationandDeclaration for Agentssections ofFinal Declaration (Crystallisation)
The updates can be found in the documentation on the developer hub
16 December 2021
- property-business-api
🔧 Added consistency in the naming of the field zeroEmissionsGoodsVehicleAllowance to four Property Annual Submission endpoints v2.0 Deployed to Sandbox Documentation and Code Updates:
- Create and Amend a Foreign Property Annual Submission [test only]
- Retrieve a Foreign Property Annual Submission [test only]
- Create and Amend a UK Property Business Annual Submission [test only]
- Retrieve a UK Property Business Annual Submission [test only]
The updates can be found in the documentation on the developer hub
15 December 2021
- property-business-api
🎊 Endpoint available for testing in Sandbox v2.0 Documentation + Testable in Sandbox
- Retrieve a Foreign Property Annual Submission [test only]
The updates can be found in the documentation on the developer hub
14 December 2021
- property-business-api
🎊 Endpoint available for testing in Sandbox v2.0 Documentation + Testable in Sandbox
- Create or Amend a Foreign Property Annual Submission [test only]
The updates can be found in the documentation on the developer hub
13 December 2021
- property-business-api
🔧 Documentation and validation updates for Create and Amend a UK Property Business Annual Submission v2.0 Deployed to Sandbox:
- New error
RULE_PROPERTY_INCOME_ALLOWANCEadded to prevent submissions where bothpropertyIncomeAllowanceandprivateUseAdjustmentare supplied. - Maximum value for
propertyIncomeAllowanceupdated to 1000.00 in code and documentation
The updates can be found in the documentation on the developer hub
9 December 2021
- property-business-api
🎊 Endpoint available for testing in Sandbox v2.0 Documentation + Testable in Sandbox
- Retrieve a Foreign Property Income & Expenditure Period Summary [test only]
The documentation for these new resources can be found on the developer hub
8 December 2021
- individuals-state-benefits-api
- property-business-api
- Added new description for List State Benefits
🎊 Endpoint available for testing in Sandbox v2.0 Documentation + Testable in Sandbox
- List Property Income & Expenses Period Summaries [test only]
The documentation for these new resources can be found on the developer hub
6 December 2021
- property-business-api
📖 Endpoint with only documentation available in Sandbox v2.0 Documentation only
- Create and Amend a Foreign Property Annual Submission [test only]
🎊 Endpoint available for testing in Sandbox v2.0 Documentation + Testable in Sandbox
- Create a Foreign Property Income & Expenses Period Summary [test only]
The documentation for these new resources can be found on the developer hub
3 December 2021
- property-business-api
🎊 Endpoint available for testing in Sandbox v2.0 Documentation + Testable in Sandbox
- Amend a Foreign Property Income & Expenses Period Summary [test only]
The documentation for these new resources can be found on the developer hub
30 November 2021
- property-business-api
- self-assessment-api
- individual-losses-api
- individual-calculations-api
- self-assessment-bsas-api
- Changed ‘foreignTaxPaidOrDeducted’, ‘specialWithholdingTaxOrUkTaxPaid’ and ’residentialFinancialCost' field descriptions for Create, Amend & Retrieve a Foreign Property Income & Expenses Period Summary
- Changed ‘residentialFinancialCost’ field description for Create & Retrieve a UK Property Income & Expenses Period Summary
📖 Endpoint with only documentation available in Sandbox v2.0 Documentation only
- Create a Foreign Property Income & Expenditure Period Summary [test only]
⛔️ Deprecation of six endpoints Endpoint Deprecation v2.0 No Longer Available in Sandbox and Production
- The following endpoints have been deprecated and are no longer available in Sandbox and Production:
- Submit Self-Employment End-of-Period Statement - replaced by the Submit End of Period Statement for a Business endpoint in the individuals-business-eops-api
- Submit UK Property End-of-Period Statement - replaced by the Submit End of Period Statement for a Business endpoint in the individuals-business-eops-api
- Retrieve all UK property business obligations - replaced by the Retrieve Income Tax (Self Assessment) Income and Expenditure Obligations endpoint in the obligations-api
- Retrieve End of Period Statement Obligations for a UK Property Business - replaced by the Retrieve Income Tax (Self Assessment) End of Period Statement Obligations endpoint in the obligations-api
- Intent to Crystallise - replaced by the Intent to Crystallise endpoint in the individual-calculations-api
- Crystallisation - replaced by the Crystallisation endpoint in the individual-calculations-api
- The above endpoints now return 410 Gone.
⛔️ Retirement of API versions API version retirement v1.0 No Longer Available in Sandbox and Production
-
The following API versions have been retired and are no longer available in Sandbox and Production:
- Individual Losses API V1.0
- Individual Calculations API V1.0
- Business Source Adjustable Summary V1.0
25 November 2021
- property-business-api
🎊 Endpoints available for testing in Sandbox v2.0 Documentation + Testable in Sandbox
- Create a UK Property Income & Expenses Period Summary [test only]
- Amend a UK Property Income & Expenses Period Summary [test only]
📖 Endpoint with only documentation available in Sandbox v2.0 Documentation only
- Amend a Foreign Property Income & Expenses Period Summary [test only]
The documentation for these new resources can be found on the developer hub
24 November 2021
- property-business-api
🎊 Endpoints available for testing in Sandbox v2.0 Documentation + Testable in Sandbox
- Create and Amend a UK Property Business Annual Submission [test only]
🎊 Endpoints available for testing in Sandbox v2.0 Documentation + Testable in Sandbox
- Retrieve a UK Property Income & Expenses Period Summary [test only]
📖 Updated endpoint and field descriptions for Create a UK Property Income & Expenses Period Summary
The documentation for these new resources can be found on the developer hub
15 November 2021
- individuals-income-received-api
- individuals-disclosures-api
- individual-calculations-api
- individuals-state-benefits-api
- individuals-charges-api
🎉 Release 6 Now Live
- New Endpoints for
Capital Gains Tax - New Endpoints for
Foreign Income - New Endpoints for
Non-PAYE Income - 🔧 Non-user impact technical alignments implemented
- New Endpoints for
Marriage Allowance
- New Fields
totalTaxDeductedBeforeCodingOut&saUnderpaymentsCodedOutadded to Retrieve self assessment tax calculation end of year estimate - New Field
tipsIncomeadded to Retrieve Self Assessment Tax Calculation Taxable Income - New Field
topSlicingReliefs.amountadded to Retrieve self assessment tax calculation allowances, deductions and reliefs - 🔧 Non-user impact technical alignments implemented
- 🔧 Non-user impact technical alignments implemented
- 🔧 Non-user impact technical alignments implemented
10 November 2021
- individuals-income-received-api
- property-business-api
🔧 Enhanced validation for Create and Amend 'Report and Pay Capital Gains Tax on Property' Overrides (PPD) v1.0 Deployed to Sandbox:
-
RULE_DUPLICATED_PPD_SUBMISSION_IDnow includes details of duplicatedppdSubmissionIds along with their paths.
🎉 New API Version - v2.0 Now Available in Sandbox
🎊 Endpoints available for testing in Sandbox v2.0 Documentation + Testable in Sandbox
- Retrieve a UK property Business Annual Submission [test only]
- Delete a Property Annual Submission [test only]
📖 Endpoint with only documentation available in Sandbox v2.0 Documentation only
- Create a UK Property Income & Expenses Period Summary [test only]
The documentation for these new resources can be found on the developer hub
2 November 2021
- property-business-api
🔧 Retrieve a UK property business annual submission code added, not yet available to hit in Sandbox
📖 Retrieve a UK property business annual submission documentation added to Developer Hub
28 October 2021
- individuals-income-received-api
🔧 404 error removed from Create and Amend Foreign Income Documentation
27 October 2021
- property-business-api
📦 New field structureAndBuildingAllowance added to Retrieve Foreign Property Annual Submission response body and Create or Amend a Foreign Property Annual Summary request body
21 October 2021
- individuals-income-received-api
🔧 Added 2 additional validation errors to the request body.
12 October 2021
- mtd-itsa-vendors-roadmap
🔧 Updated ITSA Future Deliverables - Date due: End of April 2022 section of roadmap.
07 October 2021
- business-details-api
- individual-losses-api
- obligations-api
- self-assessment-bsas-api
- individuals-reliefs-api
📦 businessId within response body canned data updated to include more consistent data and match against the typeOfBusiness in the following endpoints:
- List All Businesses
- Retrieve business details
📦 businessId within response body canned data updated to include more consistent data and match against the typeOfBusiness in the following endpoints:
- Retrieve a Brought Forward Loss
- Retrieve a Loss Claim
📦 businessId within response body canned data updated to include more consistent data and match against the typeOfBusiness in the following endpoints:
- Retrieve Income Tax Income and Expenditure Obligations
- Retrieve Income Tax End of Period Statement Obligations
📦 businessId within response body canned data updated to include more consistent data and match against the typeOfBusiness in the following endpoints:
- List Business Source Adjustable Summaries
- Retrieve a Self-Employment Business Source Adjustable Summary
- Retrieve a Self-Employment Business' Summary Adjustments
- Retrieve a UK Property Business Source Adjustable Summary
- Retrieve a UK Property Business' Summary Adjustments
- Retrieve a Foreign Property Business Source Adjustable Summary
- Retrieve a Foreign Property Business' Summary Adjustments
📦 Remapped RULE_SUBMISSION_FAILED error and added INVALID_CORRELATIONID error in the following endpoints:
- Amend Other Reliefs
05 October 2021
- individual-calculations-api
📦 Retrieve Self Assessment Tax Calculation Metadata now returns a taxYear of 2018-19 within the response body.
04 October 2021
- individuals-income-received-api
- individuals-state-benefits-api
- individuals-charges-api
- self-assessment-api
📦 Update to integration tests
📦 Update to integration tests
📦 Update to integration tests
🔧 Fix to Sandbox
-
Amend a self-employment periodic updateendpoint now returns 404 (and not 500) when called for an unknownselfEmploymentId -
Get a self-employment periodic updateendpoint now returns 404 (and not 500) when called for an unknownselfEmploymentId
The documentation for this service can be found on the developer hub
29 September 2021
- individuals-income-received-api
🔧 Internal auditing change for v1.0 Deployed to Sandbox
14 September 2021
- individuals-income-received-api
🔧 The rules for field disposals.completionDate have been relaxed for previous tax years. See endpoint description and field description for details. v1.0 Deployed to Sandbox
- Create and Amend CGT Residential Property Disposals (Non-PPD)
7 September 2021
- individuals-income-received-api
- individuals-state-benefits-api
🔧 The field singlePropertyDisposals.acquisitionDate is now optional for the endpoints: v1.0 Deployed to Sandbox
- Create and Amend 'Report and Pay Capital Gains Tax on residential property' Overrides (PPD)
- Retrieve All CGT Residential Property Disposals and Overrides (PPD and Non-PPD)
🔧 A couple of changes have been made to the following endpoint v1.0 Deployed to Sandbox
Create State Benefit
- New error RULE_BENEFIT_TYPE_EXISTS added
- New Gov-Test-Scenario value BENEFIT_TYPE_EXISTS added
The documentation for these changes can be found on the developer hub
6 September 2021
- individual-calculations-api
🔧 A number of changes have been made to the following endpoints v2.0 Deployed to Sandbox & Production
Declare Crystallisation
- INVALID_INCOME_SOURCES, INCOME_SUBMISSIONS_NOT_EXIST, and BUSINESS_VALIDATION error codes added
The documentation for these changes can be found on the developer hub
2 September 2021
- individuals-charges-api
- individual-calculations-api
🔧 Release 6 Pensions alignments to IF specifications
Create and Amend pension charges
- Changed the MATCHING_RESOURCE_NOT_FOUND to FORMAT_NINO error
The documentation for these changes can be found on the developer hub
🔧 A number of changes have been made to the following endpoints v2.0 Deployed to Sandbox & Production
Retrieve Self Assessment Tax Calculation Taxable Income
- The returned detail.savingsAndGains.totalOfAllGains is now optional
The documentation for these changes can be found on the developer hub
28 August 2021
- individuals-income-received-api
🔧 A number of changes have been made to the following endpoints v1.0 Deployed to Sandbox
Retrieve an Employment and its Financial Details
- The returned employment.pay.taxablePayToDate is now optional
- The returned employment.pay.totalTaxToDate is now optional
Amend a Custom Employment
- New error RULE_UPDATE_FORBIDDEN added
- New Gov-Test-Scenario value HMRC_HELD added
Create and amend Employment Financial Details
-
RULE_INCORRECT_OR_EMPTY_BODY_SUBMITTED error returned if
- employment.deductions.studentLoans is included but empty
- employment.deductions is included but empty
- employment.benefitsInKind is included but empty
Retrieve an Employment
- The returned startDate is now optional
All endpoints where used
- Regex for employmentId loosened
- Regex for payrollId loosened
The documentation for these changes can be found on the developer hub
24 August 2021
- self-assessment-accounts-api
🔧 submittedOn Field Format Updated
*The following fields have had a format update in the Retrieve Coding Out endpoint:
- taxCodeComponents.selfAssessmentUnderpayment[].submittedOn
- taxCodeComponents.payeUnderpayment[].submittedOn
- taxCodeComponents.debt[].submittedOn
- taxCodeComponents.inYearAdjustment.submittedOn
- unmatchedCustomerSubmissions.selfAssessmentUnderpayment[].submittedOn
- unmatchedCustomerSubmissions.payeUnderpayment[].submittedOn
- unmatchedCustomerSubmissions.debt[].submittedOn
- unmatchedCustomerSubmissions.inYearAdjustment.submittedOn
The documentation for these changes can be found on the developer hub
19 August 2021
- self-assessment-api
🔧 Cleaning up redundant code and routes
-
The following changes has made to clean up SA-API-LEGACY:
- Removed FOA (File-Only-Agents) authentication logic
- Removed unused endpoints/routes
- Removed redundant feature switch logic
🔧 Fix to Sandbox
-
List all self-employment update periodsendpoint now returns only those periods for the specifiedselfEmploymentId
The documentation for this service can be found on the developer hub
17 August 2021
- self-assessment-accounts-api
🔧 Id Field Updated Added v2.0 Deployed to Sandbox
-
The following mandatory fields have been updated to optional in the Retrieve Coding Out Underpayments And debt Amounts Response:
-
taxCodeComponents.selfAssessmentUnderpayment[].id
-
taxCodeComponents.payeUnderpayment[].id
-
taxCodeComponents.debt[].id
-
taxCodeComponents.inYearAdjustment.id
-
unmatchedCustomerSubmissions.selfAssessmentUnderpayment[].id
-
unmatchedCustomerSubmissions.payeUnderpayment[].id
-
unmatchedCustomerSubmissions.debt[].id
-
unmatchedCustomerSubmissions.inYearAdjustment.id
-
The documentation for these changes can be found on the developer hub
16 August 2021
- individual-calculations-api
🔧 New Object and Fields Added v2.0 Deployed to Sandbox
- The following optional object has been added to Retrieve Self Assessment tax calculation income tax NICs calculated response:
- calculation.marriageAllowanceTransferredIn
- The following optional fields have been added to Retrieve Self Assessment tax calculation income tax NICs calculated response:
- detail.marriageAllowanceTransferredIn.amount
- detail.marriageAllowanceTransferredIn.rate
The documentation for these changes can be found on the developer hub
12 August 2021
- individuals-disclosures-api
- individual-calculations-api
🎉 New Endpoint Added Create Marriage Allowance v1.0 Now Available in Sandbox
- The following endpoint has been added and is now available to use in Sandbox:
-
Create Marriage Allowance
The documentation for these new resources can be found on the developer hub
-
Create Marriage Allowance
🔧 New Object and Fields Added v2.0 Deployed to Sandbox
-
The following optional object has been added to Retrieve Self Assessment Tax Calculation Allowances, Deductions and Reliefs response:
- details.allowancesAndDeductions.marriageAllowanceTransferOut
-
The following mandatory fields have been added to Retrieve Self Assessment Tax Calculation Allowances, Deductions and Reliefs response:
- details.allowancesAndDeductions.marriageAllowanceTransferOut.personalAllowanceBeforeTransferOut
- details.allowancesAndDeductions.marriageAllowanceTransferOut.transferredOutAmount
The documentation for these changes can be found on the developer hub
11 August 2021
- individual-calculations-api
🔧 New Fields Added v2.0 Deployed to Sandbox
- The following optional fields have been added to Retrieve Self Assessment Tax Calculation Income Tax and Nics response:
-
summary.capitalGainsTax.totalCapitalGainsIncome
-
summary.capitalGainsTax.annualExemptionAmount
-
summary.capitalGainsTax.totalTaxableGains
-
summary.capitalGainsTax.capitalGainsTaxAmount
-
summary.capitalGainsTax.adjustments
-
summary.capitalGainsTax.adjustedCapitalGainsTax
-
summary.capitalGainsTax.foreignTaxCreditRelief
-
summary.capitalGainsTax.capitalGainsTaxAfterFTCR
-
summary.capitalGainsTax.taxOnGainsAlreadyPaid
-
summary.capitalGainsTax.capitalGainsTaxDue
-
summary.capitalGainsTax.capitalGainsOverpaid
-
details.capitalGainsTax.businessAssetsDisposalsAndInvestorsRel.gainsIncome
-
details.capitalGainsTax.businessAssetsDisposalsAndInvestorsRel.lossesBroughtForward
-
details.capitalGainsTax.businessAssetsDisposalsAndInvestorsRel.lossesArisingThisYear
-
details.capitalGainsTax.businessAssetsDisposalsAndInvestorsRel.gainsAfterLosses
-
details.capitalGainsTax.businessAssetsDisposalsAndInvestorsRel.annualExemptionAmount
-
details.capitalGainsTax.businessAssetsDisposalsAndInvestorsRel.taxableGains
-
details.capitalGainsTax.businessAssetsDisposalsAndInvestorsRel.rate
-
details.capitalGainsTax.businessAssetsDisposalsAndInvestorsRel.taxAmount
-
details.capitalGainsTax.residentialPropertyAndCarriedInterest.gainsIncome
-
details.capitalGainsTax.residentialPropertyAndCarriedInterest.lossesBroughtForward
-
details.capitalGainsTax.residentialPropertyAndCarriedInterest.lossesArisingThisYear
-
details.capitalGainsTax.residentialPropertyAndCarriedInterest.gainsAfterLosses
-
details.capitalGainsTax.residentialPropertyAndCarriedInterest.annualExemptionAmount
-
details.capitalGainsTax.residentialPropertyAndCarriedInterest.taxableGains
-
details.capitalGainsTax.residentialPropertyAndCarriedInterest.cgtTaxBands.name
-
details.capitalGainsTax.residentialPropertyAndCarriedInterest.cgtTaxBands.rate
-
details.capitalGainsTax.residentialPropertyAndCarriedInterest.cgtTaxBands.income
-
details.capitalGainsTax.residentialPropertyAndCarriedInterest.cgtTaxBands.taxAmount
-
details.capitalGainsTax.residentialPropertyAndCarriedInterest.cgtTaxBands.name
-
details.capitalGainsTax.residentialPropertyAndCarriedInterest.totalTaxBands
-
details.capitalGainsTax.otherGains.gainsIncome
-
details.capitalGainsTax.otherGains.lossesBroughtForward
-
details.capitalGainsTax.otherGains.lossesArisingThisYear
-
details.capitalGainsTax.otherGains.gainsAfterLosses
-
details.capitalGainsTax.otherGains.attributedGains
-
details.capitalGainsTax.otherGains.netGains
-
details.capitalGainsTax.otherGains.annualExemptionAmount
-
details.capitalGainsTax.otherGains.taxableGains
-
details.capitalGainsTax.otherGains.cgtTaxBands.name
-
details.capitalGainsTax.otherGains.cgtTaxBands.rate
-
details.capitalGainsTax.otherGains.cgtTaxBands.income
-
details.capitalGainsTax.otherGains.cgtTaxBands.taxAmount
-
details.capitalGainsTax.otherGains.totalTaxAmount
-
The documentation for these changes can be found on the developer hub
10 August 2021
- self-assessment-accounts-api
🔧 New Fields Added v1.0 Deployed to Sandbox
- The following optional fields have been added to List self assessment transactions response:
- transactions.accruingInterestAmount
- transactions.interestRate
- transactions.interestFromDate
- transactions.interestEndDate
- transactions.latePaymentInterestAmount
- transactions.interestOutstandingAmount
The documentation for these changes can be found on the developer hub
5 August 2021
- individual-calculations-api
🔧 New Field Added v2.0 Deployed to Sandbox
- The following optional field has been added to Retrieve Self Assessment Tax Calculation Allowances, Deductions and Reliefs response:
- detail.reliefs.topSlicingRelief
The documentation for this change can be found on the developer hub
4 August 2021
- individual-calculations-api
🔧 New Fields Added v2.0 Deployed to Sandbox
- The following optional fields have been added to Retrieve Self Assessment Tax Calculation End Of Year Estimate response:
- summary.cgtAmount
- summary.incomeTaxNicAndCgtAmount
- The following optional field has been added to Retrieve Self Assessment Tax Calculation Allowances, Deductions and Reliefs response:
- detail.cgtLossSetAgainstInYearGeneralIncome
The documentation for these changes can be found on the developer hub
2 August 2021
- self-assessment-api
- individuals-income-received-api
📖 Documentation updated for id response field, for following endpoints. There is no change in behaviour. v2.0 Documentation
- List all self-employment update periods
- List all non-FHL UK property update periods
- List all FHL UK property update periods
🎉 New Endpoints Added Non-PAYE v1.0 Now Available in Sandbox
- The following endpoints have been added and are now available to use in Sandbox:
- Delete non-PAYE employment income [test-only]
-
Create and Amend non-PAYE employment income [test-only]
The documentation for these new resources can be found on the developer hub
30 July 2021
- individuals-income-received-api
🎉 New Endpoint Added Non-PAYE v1.0 Now Available in Sandbox
- The following endpoint has been added and is now available to use in Sandbox:
- Retrieve Non-PAYE employment income [test only] The documentation for these new resources can be found on the developer hub
29 July 2021
- self-assessment-bsas-api
📦 Upgraded API to Play! Framework version 2.8
28 July 2021
- individuals-income-received-api
🎉 New Endpoint Added CGT v1.0 Now Available in Sandbox
- The following endpoint has been added and is now available to use in Sandbox:
- Create and Amend CGT Residential Property Disposals (non-PPD) [test only] The documentation for these new resources can be found on the developer hub
23 July 2021
- individuals-income-received-api
🎉 New Endpoint Added CGT v1.0 Now Available in Sandbox
- The following endpoint has been added and is now available to use in Sandbox:
- Delete CGT Residential Property Disposals (non-PPD) [test only] The documentation for these new resources can be found on the developer hub
22 July 2021
- vat-service-guide
- income-tax-mtd-end-to-end-service-guide
- individuals-income-received-api
📦 Upgraded API to Play! Framework version 2.8
📦 Upgraded API to Play! Framework version 2.8
🎉 New Endpoint Added CGT v1.0 Now Available in Sandbox
- The following endpoint has been added and is now available to use in Sandbox:
- Retrieve all CGT Residential Property Disposal Submissions (non-PPD and PPD) [test only]
The documentation for these new resources can be found on the developer hub
21 July 2021
- individual-calculations-api
🔧 New Fields Added v2.0 Deployed to Sandbox
-
The following fields have been added to Retrieve Self Assessment Tax Calculation End Of Year Estimate:
- summary.totalTaxDeductedBeforeCodingOut
- summary.saUnderpaymentsCodedOut
-
The following fields have been added to Retrieve Self Assessment Tax Calculation Income Tax and NICs Calculated:
- summary.incomeTax.payeUnderpaymentsCodedOut
- summary.totalTaxDeductedBeforeCodingOut
- summary.saUnderpaymentsCodedOut
-
The following field has been added to Retrieve Self Assessment Tax Calculation Taxable Income:
- detail.payPensionsProfit.tipsIncome
The documentation for these new fields can be found on the developer hub
20 July 2021
- individuals-income-received-api
🎉 New Endpoints Added CGT v1.0 Now Available in Sandbox
- The following endpoints have been added and are now available to use in Sandbox:
- Create and Amend 'Report and Pay Capital Gains Tax on Property' Overrides [test only]
- Delete 'Report and Pay Capital Gains Tax on residential property' Overrides [test only]
- Retrieve Other Capital Gains and Disposals [test only]
- Create and Amend Other Capital Gains and Disposals [test only]
- Delete Other Capital Gains and Disposals [test only]
The documentation for these new resources can be found on the developer hub
8 July 2021
- self-assessment-api
⛔️ Deprecation of endpoint Endpoint Deprecation v2.0 No Longer Available in Sandbox and Production
- The following endpoints have been deprecated and are no longer available in Sandbox and Production:
- Retrieve crystallisation obligations - replaced by the obligations-api
6 July 2021
- self-assessment-api
⛔️ Deprecation of four endpoints Endpoint Deprecation v2.0 No Longer Available in Sandbox and Production
- The following endpoints have been deprecated and are no longer available in Sandbox and Production:
- List all self-employment businesses - replaced by the business-details-api
- Get a self-employment business - replaced by the business-details-api
- Retrieve self-employment business obligations - replaced by the obligations-api
- Retrieve End of Period Statement Obligations for a Self-Employment Business - replaced by the obligations-api
- The above endpoints now return 410 Gone.
2 July 2021
- self-assessment-biss-api
📦 Upgraded API to Play! Framework version 2.8
29 June 2021
- mtd-savings-accounts
- mtd-crystallisation
📦 Upgraded API to Play! Framework version 2.8
📦 Upgraded API to Play! Framework version 2.8
28 June 2021
- mtd-charitable-giving
- mtd-property
- obligations-api
- mtd-dividends-income
📦 Upgraded API to Play! Framework version 2.8
📦 Upgraded API to Play! Framework version 2.8
📦 Upgraded API to Play! Framework version 2.8
📦 Upgraded API to Play! Framework version 2.8
23 June 2021
- self-assessment-api
- self-assessment-api-legacy
📦 Upgraded API to Play! Framework version 2.8
📦 Upgraded API to Play! Framework version 2.8
21 June 2021
- self-assessment-api
- individual-calculations-api
- individual-losses-api
- self-assessment-bsas-api
- business-details-api
- obligations-api
- self-employment-business-api
- individuals-business-eops-api
📖 Added new text to the selfEmploymentId field description to account for the change from selfEmploymentId to businessId
📖 Added new text to the selfEmploymentId field description to account for the change from selfEmploymentId to businessId
📖 Removed duplication of Regex in businessId field description
📖 Adjusted formatting for Regex in businessId field descriptions
📖 Added new text to the businessId field description to account for the change from selfEmploymentId to businessId
📖 Adjusted formatting for Regex in businessId query parameter description. Added Regex to businessId response field description
📖 Adjusted formatting for the businessId field description
📖 Adjusted formatting for Regex in the businessId request field