v1

latestOpenAPI 3.0.32026-07-13339240.9 KB

Foreign Property Details

Update Foreign Property Details

This endpoint enables you to update the details of a foreign property for a given National Insurance number, foreign property ID and tax year. Please note that this endpoint is only available for tax years starting from 2026–27 onwards.

Customers can amend or remove the end date before the Post Finalisation Amendment (PFA) window closes. Any property with an end date added will no longer appear on the list of properties to report against for any subsequent tax year.

Test data

Scenario simulation using Gov-Test-Scenario headers is only available in the sandbox environment.

Header Value (Gov-Test-Scenario)	Scenario
N/A - DEFAULT	Simulates success response.
NOT_FOUND	Simulates the scenario where no data is found.
DUPLICATE_PROPERTY_NAME	Simulates the scenario where the foreign property name already exists for the same country.
TAX_YEAR_BEFORE_BUSINESS_START	Simulates the scenario where the requested tax year is before the first tax year in which the foreign property business was reported.
PROPERTY_BUSINESS_CEASED	Simulates the scenario where the foreign property business income source has ceased.
OUTSIDE_AMENDMENT_WINDOW	Simulates the scenario where request cannot be completed as it is outside the amendment window.
STATEFUL	Performs a stateful update.

put/individuals/business/property/foreign/{nino}/details/{propId}/{taxYear}

Path parameters

ninostring required

Example:TC663795B

National Insurance number, in the format AA999999A.

propertyIdstring uuid required

Example:8e8b8450-dc1b-4360-8109-7067337b42cb

A unique identifier for each foreign property.

taxYearstring required

Example:2026-27

The tax year to which the data applies. The start year and end year must not span two tax years. The minimum tax year is 2026-27. No gaps are allowed, for example, 2026-28 is not valid.

The foreign property must fall within the start and end dates of the associated foreign property income source, and the income source should not be ceased.

Headers

Accept'application/vnd.hmrc.6.0+json' required

Specifies the response format and the version of the API to be used.

Content-Type'application/json' required

Specifies the format of the request body, which must be JSON.

Authorizationstring required

Example:Bearer bb7fed3fe10dd235a2ccda3d50fb

An OAuth 2.0 Bearer Token with the write:self-assessment scope.

Gov-Test-Scenariostring

Example:-

Only in sandbox environment. See Test Data table for all header values.

Request body

propertyNamestring required

A customer-friendly name for the foreign property. This name must be unique for each country. Uniqueness checks ignore differences in letter case and any leading or trailing spaces. Must not be empty or contain only whitespace.

endDatestring date

The date on which income is no longer received from the property. The end date must not be later than the end of the relevant tax year. A property with an end date must always have an associated end reason.

Must conform to the format YYYY-MM-DD

endReason'no-longer-renting-property-out' | 'disposal' | 'added-in-error'

Specifies the reason for ending the property record. A property with an end reason must always have an associated end date.

Example request

{
  "propertyName": "Bob & Bobby Co",
  "endDate": "2026-08-24"
}

Response

No Content