This version is in beta - expect some breaking changes.

Interest Restriction Return API

Version and status
Available in Sandbox	Yes
Sandbox base URL	https://test-api.service.hmrc.gov.uk
Available in Production	Yes
Production base URL	https://api.service.hmrc.gov.uk

Overview

The API in its current state supports the following functions:

• Revoke an existing Reporting Company from submitting Interest Restriction Returns
• Appoint a new Reporting Company for submitting Interest Restriction Returns
• Submit an Interest Restriction Return (full)
• Submit an Interest Restriction Return (abbreviated)

This API uses User Restricted Endpoints. Please find further details on the Authorisation page.

For more information about how to develop your own client applications, including example clients for this API, see Tutorials.

Support

• Raise non-technical or platform-related issues with the Software Development Support Team (SDST).

• Raise technical issues on the interest-restriction-return issues page

Changelog

You can find the change log on the interest-restriction-return wiki page.

Versioning

When an API changes in a way that is backwards-incompatible, we increase the version number of the API. See our reference guide for more on versioning.

Errors

We use standard HTTP status codes to show whether an API request succeeded or not. They are usually in the range:

• 200 to 299 if it succeeded, including code 202 if it was accepted by an API that needs to wait for further action
• 400 to 499 if it failed because of a client error by your application
• 500 to 599 if it failed because of an error on our server

Errors specific to each API are shown in the Endpoints section, under Response. See our reference guide for more on errors.

Skip to main content

Endpoints

Reporting Company

These resources allow software packages to develop functionality that will:

• Appoint a Reporting Company to act on behalf of the group and file the Interest Restriction Return
• Revoke an existing Reporting Company to remove them from acting on behalf of the group

Reporting Company resources

/organisations/interest-restriction/reporting-company/appoint

Appoint a Reporting Company

POST

Request to appoint a Reporting Company that can submit Interest Restriction Returns

Authorisation

This endpoint is user-restricted and requires an Authorization header containing an OAuth 2.0 Bearer Token with the write:interest-restriction-return scope.

Request headers

Name	Description
Accept required	Specifies the response format and the version of the API to use. For example: application/vnd.hmrc.1.0+json
Content-Type required	Specifies the format of the request body, which must be JSON. For example: application/json
Authorization required	An OAuth 2.0 Bearer Token with the write:interest-restriction-return scope. For example: Bearer bb7fed3fe10dd235a2ccda3d50fb

See also fraud prevention.

Request

Scenario: Appoint Reporting Company

{
  "agentDetails": {
    "agentActingOnBehalfOfCompany": true,
    "agentName": "AAgent"
  },
  "reportingCompany": {
    "companyName": "ACompany",
    "ctutr": "1123456789",
    "sameAsUltimateParent": true
  },
  "isReportingCompanyAppointingItself":false,
  "identityOfAppointingCompany": {
    "companyName": "BCompany",
    "ctutr": "9999999999"
  },
  "authorisingCompanies": [{
    "companyName": "CCompany",
    "utr": "5555555555"
  }],
  "accountingPeriod": {
    "startDate": "2018-11-01",
    "endDate": "2019-12-01"
  },
  "declaration": true
}

Name	Description
agentDetails object required	Details of the agent where an agent is submitting on behalf of the reporting company
agentActingOnBehalfOfCompany boolean required	Is an agent acting on behalf of the reporting company
agentName string optional	Name of the agent where an agent is acting on behalf of the reporting company Must conform to the regular expression ^[ -~¡-ÿĀ-ʯḀ-ỿ‐-―‘-‟₠-₿ÅK]{1,160}$
reportingCompany object required	Details of the reporting company
companyName string required	Name of the reporting company Must conform to the regular expression ^[ -~¡-ÿĀ-ʯḀ-ỿ‐-―‘-‟₠-₿ÅK]{1,160}$
ctutr string required	Reporting company's Corporation Tax Unique Taxpayer Reference Must conform to the regular expression ^[0-9]{10}$
sameAsUltimateParent boolean required	Indicate whether the reporting company is also the ultimate parent company
authorisingCompanies array required	Details of companies authorising the appointment
companyName string required	Name of authorising company Must conform to the regular expression ^[ -~¡-ÿĀ-ʯḀ-ỿ‐-―‘-‟₠-₿ÅK]{1,160}$
utr string required	Authorising company's Unique Tax Reference. Must conform to the regular expression ^[0-9]{10}$
consenting boolean optional	Indicate whether the authorising company agrees to take on the group's restriction in its Corporation Tax return
isReportingCompanyAppointingItself boolean required	Indicate whether the reporting company is appointing itself
identityOfAppointingCompany object optional	Details of the company appointing the reporting company
companyName string required	Name of the appointing company. Must conform to the regular expression ^[ -~¡-ÿĀ-ʯḀ-ỿ‐-―‘-‟₠-₿ÅK]{1,160}$
countryOfIncorporation string optional	Country of incorporation where the appointing company is not a UK company. A valid ISO 3166-1 2 Alpha Country Code. For example: US
ctutr string optional	Where the appointing company is a UK company, the Corporation Tax Unique Taxpayer Reference Must conform to the regular expression ^[0-9]{10}$
legalEntityIdentifier string optional	A Legal Entity Identifier (LEI); format is as per the ISO 17442 standard - 18 uppercase alphabetic or numeric characters followed by 2 numeric characters Must conform to the regular expression ^[0-9A-Z]{18}[0-9]{2}$
ultimateParentCompany object optional	Details of the ultimate parent company
isUk boolean required	Indicate whether the ultimate parent company is a UK company
companyName string required	Name of the ultimate parent company Must conform to the regular expression ^[ -~¡-ÿĀ-ʯḀ-ỿ‐-―‘-‟₠-₿ÅK]{1,160}$
ctutr string optional	Ultimate parent's Corporation Tax Unique Taxpayer Reference. Must conform to the regular expression ^[0-9]{10}$
sautr string optional	Ultimate parent company's self assessment Unique Taxpayer Reference Must conform to the regular expression ^[0-9]{10}$
countryOfIncorporation string optional	Country of incorporation where the ultimate parent company is not a UK company. A valid ISO 3166-1 2 Alpha Country Code For example: US
legalEntityIdentifier string optional	A Legal Entity Identifier (LEI); format is as per the ISO 17442 standard - 18 uppercase alphabetic or numeric characters followed by 2 numeric characters Must conform to the regular expression ^[0-9A-Z]{18}[0-9]{2}$
accountingPeriod object required	The worldwide group's period of account
startDate string required	Start date of the group's period of account, which cannot be before 2016-10-01 Must conform to the regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$
endDate string required	End date of the group's period of account, which must be within 18 months of the start date Must conform to the regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$
declaration boolean required	Statement to confirm the truth of the information given and that the authorising companies listed make up at least 50% of eligible companies in the group

Response

HTTP status: 200 (OK)

Typical response received

{
  "acknowledgementReference": "XAIRR00000012345678"
}

Name	Description
acknowledgementReference string required

Error scenarios

Scenario	HTTP status	Code
Matching resource not found.	404 (Not Found)	MATCHING_RESOURCE_NOT_FOUND
The requested resource could not be found.	404 (Not Found)	NOT_FOUND
An internal server error occurred.	500 (Internal Server Error)	INTERNAL_SERVER_ERROR
Invalid request.	400 (Bad Request)	INVALID_REQUEST
Expecting text/json or application/json body.	400 (Bad Request)	INVALID_BODY_TYPE
The client and/or agent is not authorised.	401 (Unauthorized)	CLIENT_OR_AGENT_NOT_AUTHORISED
The accept header is missing or invalid.	406 (Not Acceptable)	ACCEPT_HEADER_INVALID

For error scenarios that are common across all APIs, and for error formats, see our reference guide.

Close Section

/organisations/interest-restriction/reporting-company/appoint/validate

Validate Appointing a Reporting Company

POST

Validates the payload for Appointing a Reporting Company without submitting the Appoint request

Authorisation

This endpoint is user-restricted and requires an Authorization header containing an OAuth 2.0 Bearer Token with the write:interest-restriction-return scope.

Request headers

Name	Description
Accept required	Specifies the response format and the version of the API to use. For example: application/vnd.hmrc.1.0+json
Content-Type required	Specifies the format of the request body, which must be JSON. For example: application/json
Authorization required	An OAuth 2.0 Bearer Token with the write:interest-restriction-return scope. For example: Bearer bb7fed3fe10dd235a2ccda3d50fb

See also fraud prevention.

Request

Scenario: Appoint Reporting Company

{
  "agentDetails": {
    "agentActingOnBehalfOfCompany": true,
    "agentName": "AAgent"
  },
  "reportingCompany": {
    "companyName": "ACompany",
    "ctutr": "1123456789",
    "sameAsUltimateParent": true
  },
  "isReportingCompanyAppointingItself":false,
  "identityOfAppointingCompany": {
    "companyName": "BCompany",
    "ctutr": "9999999999"
  },
  "authorisingCompanies": [{
    "companyName": "CCompany",
    "utr": "5555555555"
  }],
  "accountingPeriod": {
    "startDate": "2018-11-01",
    "endDate": "2019-12-01"
  },
  "declaration": true
}

Name	Description
agentDetails object required	Details of the agent where an agent is submitting on behalf of the reporting company
agentActingOnBehalfOfCompany boolean required	Is an agent acting on behalf of the reporting company
agentName string optional	Name of the agent where an agent is acting on behalf of the reporting company Must conform to the regular expression ^[ -~¡-ÿĀ-ʯḀ-ỿ‐-―‘-‟₠-₿ÅK]{1,160}$
reportingCompany object required	Details of the reporting company
companyName string required	Name of the reporting company Must conform to the regular expression ^[ -~¡-ÿĀ-ʯḀ-ỿ‐-―‘-‟₠-₿ÅK]{1,160}$
ctutr string required	Reporting company's Corporation Tax Unique Taxpayer Reference Must conform to the regular expression ^[0-9]{10}$
sameAsUltimateParent boolean required	Indicate whether the reporting company is also the ultimate parent company
authorisingCompanies array required	Details of companies authorising the appointment
companyName string required	Name of authorising company Must conform to the regular expression ^[ -~¡-ÿĀ-ʯḀ-ỿ‐-―‘-‟₠-₿ÅK]{1,160}$
utr string required	Authorising company's Unique Tax Reference. Must conform to the regular expression ^[0-9]{10}$
consenting boolean optional	Indicate whether the authorising company agrees to take on the group's restriction in its Corporation Tax return
isReportingCompanyAppointingItself boolean required	Indicate whether the reporting company is appointing itself
identityOfAppointingCompany object optional	Details of the company appointing the reporting company
companyName string required	Name of the appointing company. Must conform to the regular expression ^[ -~¡-ÿĀ-ʯḀ-ỿ‐-―‘-‟₠-₿ÅK]{1,160}$
countryOfIncorporation string optional	Country of incorporation where the appointing company is not a UK company. A valid ISO 3166-1 2 Alpha Country Code. For example: US
ctutr string optional	Where the appointing company is a UK company, the Corporation Tax Unique Taxpayer Reference Must conform to the regular expression ^[0-9]{10}$
legalEntityIdentifier string optional	A Legal Entity Identifier (LEI); format is as per the ISO 17442 standard - 18 uppercase alphabetic or numeric characters followed by 2 numeric characters Must conform to the regular expression ^[0-9A-Z]{18}[0-9]{2}$
ultimateParentCompany object optional	Details of the ultimate parent company
isUk boolean required	Indicate whether the ultimate parent company is a UK company
companyName string required	Name of the ultimate parent company Must conform to the regular expression ^[ -~¡-ÿĀ-ʯḀ-ỿ‐-―‘-‟₠-₿ÅK]{1,160}$
ctutr string optional	Ultimate parent's Corporation Tax Unique Taxpayer Reference. Must conform to the regular expression ^[0-9]{10}$
sautr string optional	Ultimate parent company's self assessment Unique Taxpayer Reference Must conform to the regular expression ^[0-9]{10}$
countryOfIncorporation string optional	Country of incorporation where the ultimate parent company is not a UK company. A valid ISO 3166-1 2 Alpha Country Code For example: US
legalEntityIdentifier string optional	A Legal Entity Identifier (LEI); format is as per the ISO 17442 standard - 18 uppercase alphabetic or numeric characters followed by 2 numeric characters Must conform to the regular expression ^[0-9A-Z]{18}[0-9]{2}$
accountingPeriod object required	The worldwide group's period of account
startDate string required	Start date of the group's period of account, which cannot be before 2016-10-01 Must conform to the regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$
endDate string required	End date of the group's period of account, which must be within 18 months of the start date Must conform to the regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$
declaration boolean required	Statement to confirm the truth of the information given and that the authorising companies listed make up at least 50% of eligible companies in the group

Response

HTTP status: 204 (No Content)

Error scenarios

Scenario	HTTP status	Code
Matching resource not found.	404 (Not Found)	MATCHING_RESOURCE_NOT_FOUND
The requested resource could not be found.	404 (Not Found)	NOT_FOUND
An internal server error occurred.	500 (Internal Server Error)	INTERNAL_SERVER_ERROR
Invalid request.	400 (Bad Request)	INVALID_REQUEST
Expecting text/json or application/json body.	400 (Bad Request)	INVALID_BODY_TYPE
The client and/or agent is not authorised.	401 (Unauthorized)	CLIENT_OR_AGENT_NOT_AUTHORISED
The accept header is missing or invalid.	406 (Not Acceptable)	ACCEPT_HEADER_INVALID

For error scenarios that are common across all APIs, and for error formats, see our reference guide.

Close Section

/organisations/interest-restriction/reporting-company/revoke

Revoke a Reporting Company

POST

Request to revoke a Reporting Company that can submit Interest Restriction Returns

Authorisation

This endpoint is user-restricted and requires an Authorization header containing an OAuth 2.0 Bearer Token with the write:interest-restriction-return scope.

Request headers

Name	Description
Accept required	Specifies the response format and the version of the API to use. For example: application/vnd.hmrc.1.0+json
Content-Type required	Specifies the format of the request body, which must be JSON. For example: application/json
Authorization required	An OAuth 2.0 Bearer Token with the write:interest-restriction-return scope. For example: Bearer bb7fed3fe10dd235a2ccda3d50fb

See also fraud prevention.

Request

Scenario: Revoke Reporting Company

{
  "agentDetails": {
    "agentActingOnBehalfOfCompany": true,
    "agentName": "AAgent"
  },
  "reportingCompany": {
    "companyName": "ACompany",
    "ctutr": "1123456789",

    "sameAsUltimateParent": false
  },
  "isReportingCompanyRevokingItself":false,
  "companyMakingRevocation": {
    "companyName": "BCompany",
    "ctutr": "9999999999"
  },
  "ultimateParentCompany": {
    "companyName": "CCompany",
    "isUk": true,
    "ctutr": "1123456789"
  },
  "authorisingCompanies": [{
    "companyName": "DCompany",
    "utr": "5555555555",
    "consenting": true

  }],
  "accountingPeriod": {
    "startDate": "2018-11-01",
    "endDate": "2019-12-01"
  },
  "declaration": true
}

Name	Description
agentDetails object required	Details of the agent where an agent is submitting the revoke form on behalf of the group
agentActingOnBehalfOfCompany boolean required	Is an agent acting on behalf of the reporting company
agentName string optional	Name of the agent where an agent is acting on behalf of the reporting company Must conform to the regular expression ^[ -~¡-ÿĀ-ʯḀ-ỿ‐-―‘-‟₠-₿ÅK]{1,160}$
reportingCompany object required	Details of the reporting company
companyName string required	Name of the reporting company Must conform to the regular expression ^[ -~¡-ÿĀ-ʯḀ-ỿ‐-―‘-‟₠-₿ÅK]{1,160}$
ctutr string required	Reporting company's Corporation Tax Unique Taxpayer Reference Must conform to the regular expression ^[0-9]{10}$
sameAsUltimateParent boolean required	Indicate whether the reporting company is also the ultimate parent company
isReportingCompanyRevokingItself boolean required	Indicate whether the reporting company is revoking itself
companyMakingRevocation object optional	Details of the revoking company
companyName string required	Name of the revoking company. Must conform to the regular expression ^[ -~¡-ÿĀ-ʯḀ-ỿ‐-―‘-‟₠-₿ÅK]{1,160}$
countryOfIncorporation string optional	Country of incorporation where the revoking company is not a UK company. A valid ISO 3166-1 2 Alpha Country Code. For example: US
ctutr string optional	Revoking company's Corporation Tax Unique Taxpayer Reference. Must conform to the regular expression ^[0-9]{10}$
legalEntityIdentifier string optional	A Legal Entity Identifier (LEI); format is as per the ISO 17442 standard - 18 uppercase alphabetic or numeric characters followed by 2 numeric characters Must conform to the regular expression ^[0-9A-Z]{18}[0-9]{2}$
ultimateParentCompany object optional	Details of the ultimate parent company
isUk boolean required	Indicate whether the ultimate parent company is a UK company
companyName string required	Name of the ultimate parent company Must conform to the regular expression ^[ -~¡-ÿĀ-ʯḀ-ỿ‐-―‘-‟₠-₿ÅK]{1,160}$
ctutr string optional	Ultimate parent's Corporation Tax Unique Taxpayer Reference. Must conform to the regular expression ^[0-9]{10}$
sautr string optional	Ultimate parent company's self assessment Unique Taxpayer Reference Must conform to the regular expression ^[0-9]{10}$
countryOfIncorporation string optional	Country of incorporation where the ultimate parent company is not a UK company. A valid ISO 3166-1 2 Alpha Country Code For example: US
legalEntityIdentifier string optional	A Legal Entity Identifier (LEI); format is as per the ISO 17442 standard - 18 uppercase alphabetic or numeric characters followed by 2 numeric characters Must conform to the regular expression ^[0-9A-Z]{18}[0-9]{2}$
accountingPeriod object required	The worldwide group's period of account
startDate string required	Start date of the group's period of account, which cannot be before 2016-10-01 Must conform to the regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$
endDate string required	End date of the group's period of account, which must be within 18 months of the start date Must conform to the regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$
authorisingCompanies array required	Details of the companies authorising the revocation of the appointment
companyName string required	Name of authorising company Must conform to the regular expression ^[ -~¡-ÿĀ-ʯḀ-ỿ‐-―‘-‟₠-₿ÅK]{1,160}$
utr string required	Authorising company's Unique Tax Reference. Must conform to the regular expression ^[0-9]{10}$
consenting boolean optional	Indicate whether the authorising company agrees to take on the group's restriction in its Corporation Tax return
declaration boolean required	Statement to confirm the truth of the information given and that the authorising companies listed make up at least 50% of eligible companies in the group

Response

HTTP status: 200 (OK)

Typical response received

{
  "acknowledgementReference": "XAIRR00000012345678"
}

Name	Description
acknowledgementReference string required

Error scenarios

Scenario	HTTP status	Code
Matching resource not found.	404 (Not Found)	MATCHING_RESOURCE_NOT_FOUND
The requested resource could not be found.	404 (Not Found)	NOT_FOUND
An internal server error occurred.	500 (Internal Server Error)	INTERNAL_SERVER_ERROR
Invalid request.	400 (Bad Request)	INVALID_REQUEST
Expecting text/json or application/json body.	400 (Bad Request)	INVALID_BODY_TYPE
The client and/or agent is not authorised.	401 (Unauthorized)	CLIENT_OR_AGENT_NOT_AUTHORISED
The accept header is missing or invalid.	406 (Not Acceptable)	ACCEPT_HEADER_INVALID

For error scenarios that are common across all APIs, and for error formats, see our reference guide.

Close Section

/organisations/interest-restriction/reporting-company/revoke/validate

Validate Revoking a Reporting Company

POST

Validates the payload for Revoking a Reporting Company without submitting the Revoke request

Authorisation

This endpoint is user-restricted and requires an Authorization header containing an OAuth 2.0 Bearer Token with the write:interest-restriction-return scope.

Request headers

Name	Description
Accept required	Specifies the response format and the version of the API to use. For example: application/vnd.hmrc.1.0+json
Content-Type required	Specifies the format of the request body, which must be JSON. For example: application/json
Authorization required	An OAuth 2.0 Bearer Token with the write:interest-restriction-return scope. For example: Bearer bb7fed3fe10dd235a2ccda3d50fb

See also fraud prevention.

Request

Scenario: Revoke Reporting Company

{
  "agentDetails": {
    "agentActingOnBehalfOfCompany": true,
    "agentName": "AAgent"
  },
  "reportingCompany": {
    "companyName": "ACompany",
    "ctutr": "1123456789",

    "sameAsUltimateParent": false
  },
  "isReportingCompanyRevokingItself":false,
  "companyMakingRevocation": {
    "companyName": "BCompany",
    "ctutr": "9999999999"
  },
  "ultimateParentCompany": {
    "companyName": "CCompany",
    "isUk": true,
    "ctutr": "1123456789"
  },
  "authorisingCompanies": [{
    "companyName": "DCompany",
    "utr": "5555555555",
    "consenting": true

  }],
  "accountingPeriod": {
    "startDate": "2018-11-01",
    "endDate": "2019-12-01"
  },
  "declaration": true
}

Name	Description
agentDetails object required	Details of the agent where an agent is submitting the revoke form on behalf of the group
agentActingOnBehalfOfCompany boolean required	Is an agent acting on behalf of the reporting company
agentName string optional	Name of the agent where an agent is acting on behalf of the reporting company Must conform to the regular expression ^[ -~¡-ÿĀ-ʯḀ-ỿ‐-―‘-‟₠-₿ÅK]{1,160}$
reportingCompany object required	Details of the reporting company
companyName string required	Name of the reporting company Must conform to the regular expression ^[ -~¡-ÿĀ-ʯḀ-ỿ‐-―‘-‟₠-₿ÅK]{1,160}$
ctutr string required	Reporting company's Corporation Tax Unique Taxpayer Reference Must conform to the regular expression ^[0-9]{10}$
sameAsUltimateParent boolean required	Indicate whether the reporting company is also the ultimate parent company
isReportingCompanyRevokingItself boolean required	Indicate whether the reporting company is revoking itself
companyMakingRevocation object optional	Details of the revoking company
companyName string required	Name of the revoking company. Must conform to the regular expression ^[ -~¡-ÿĀ-ʯḀ-ỿ‐-―‘-‟₠-₿ÅK]{1,160}$
countryOfIncorporation string optional	Country of incorporation where the revoking company is not a UK company. A valid ISO 3166-1 2 Alpha Country Code. For example: US
ctutr string optional	Revoking company's Corporation Tax Unique Taxpayer Reference. Must conform to the regular expression ^[0-9]{10}$
legalEntityIdentifier string optional	A Legal Entity Identifier (LEI); format is as per the ISO 17442 standard - 18 uppercase alphabetic or numeric characters followed by 2 numeric characters Must conform to the regular expression ^[0-9A-Z]{18}[0-9]{2}$
ultimateParentCompany object optional	Details of the ultimate parent company
isUk boolean required	Indicate whether the ultimate parent company is a UK company
companyName string required	Name of the ultimate parent company Must conform to the regular expression ^[ -~¡-ÿĀ-ʯḀ-ỿ‐-―‘-‟₠-₿ÅK]{1,160}$
ctutr string optional	Ultimate parent's Corporation Tax Unique Taxpayer Reference. Must conform to the regular expression ^[0-9]{10}$
sautr string optional	Ultimate parent company's self assessment Unique Taxpayer Reference Must conform to the regular expression ^[0-9]{10}$
countryOfIncorporation string optional	Country of incorporation where the ultimate parent company is not a UK company. A valid ISO 3166-1 2 Alpha Country Code For example: US
legalEntityIdentifier string optional	A Legal Entity Identifier (LEI); format is as per the ISO 17442 standard - 18 uppercase alphabetic or numeric characters followed by 2 numeric characters Must conform to the regular expression ^[0-9A-Z]{18}[0-9]{2}$
accountingPeriod object required	The worldwide group's period of account
startDate string required	Start date of the group's period of account, which cannot be before 2016-10-01 Must conform to the regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$
endDate string required	End date of the group's period of account, which must be within 18 months of the start date Must conform to the regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$
authorisingCompanies array required	Details of the companies authorising the revocation of the appointment
companyName string required	Name of authorising company Must conform to the regular expression ^[ -~¡-ÿĀ-ʯḀ-ỿ‐-―‘-‟₠-₿ÅK]{1,160}$
utr string required	Authorising company's Unique Tax Reference. Must conform to the regular expression ^[0-9]{10}$
consenting boolean optional	Indicate whether the authorising company agrees to take on the group's restriction in its Corporation Tax return
declaration boolean required	Statement to confirm the truth of the information given and that the authorising companies listed make up at least 50% of eligible companies in the group

Response

HTTP status: 204 (No Content)

Error scenarios

Scenario	HTTP status	Code
Matching resource not found.	404 (Not Found)	MATCHING_RESOURCE_NOT_FOUND
The requested resource could not be found.	404 (Not Found)	NOT_FOUND
Invalid request.	400 (Bad Request)	INVALID_REQUEST
Expecting text/json or application/json body.	400 (Bad Request)	INVALID_BODY_TYPE
The client and/or agent is not authorised.	401 (Unauthorized)	CLIENT_OR_AGENT_NOT_AUTHORISED
The accept header is missing or invalid.	406 (Not Acceptable)	ACCEPT_HEADER_INVALID

For error scenarios that are common across all APIs, and for error formats, see our reference guide.

Close Section

Return Submission

These resources allow software packages to develop functionality that will:

• Allow an appointed Reporting Company to submit a Full Interest Restriction Return
• Allow an appointed Reporting Company to submit an Abbreviated Interest Restriction Return

Return Submission resources

/organisations/interest-restriction/return/full

Post a Full Interest Restriction Return

POST

Request to submit a Full return for an Interest Restriction Return

Authorisation

This endpoint is user-restricted and requires an Authorization header containing an OAuth 2.0 Bearer Token with the write:interest-restriction-return scope.

Request headers

Name	Description
Accept required	Specifies the response format and the version of the API to use. For example: application/vnd.hmrc.1.0+json
Content-Type required	Specifies the format of the request body, which must be JSON. For example: application/json
Authorization required	An OAuth 2.0 Bearer Token with the write:interest-restriction-return scope. For example: Bearer bb7fed3fe10dd235a2ccda3d50fb

See also fraud prevention.

Request

Scenario: Submit a full IRR

{
  "appointedReportingCompany": true,
  "agentDetails": {
    "agentActingOnBehalfOfCompany": true,
    "agentName": "some agent"
  },
  "reportingCompany": {
    "companyName": "Company Name ltd",
    "ctutr": "1123456789",
    "sameAsUltimateParent": false
  },
  "parentCompany": {
    "ultimateParent": {
      "companyName": "Company Name ltd",
      "isUk": true,
      "ctutr": "1123456789"
    }
  },
  "groupCompanyDetails": {
    "accountingPeriod": {
      "startDate": "2019-02-18",
      "endDate": "2020-08-17"
    }
  },
  "submissionType": "revised",
  "revisedReturnDetails": "some details",
  "groupLevelElections": {
    "groupRatio": {
      "isElected": true,
      "groupEBITDAChargeableGains": true,
      "activeGroupEBITDAChargeableGains": false,
      "groupRatioBlended": {
        "isElected": true,
        "investorGroups": [
          {
            "groupName": "some investor group",
            "elections": [
              "groupRatioBlended",
              "groupEBITDA",
              "interestAllowanceAlternativeCalculation",
              "interestAllowanceNonConsolidatedInvestment",
              "interestAllowanceConsolidatedPartnership"
            ]
          },
          {
            "groupName": "some investor group",
            "elections": [
              "interestAllowanceAlternativeCalculation",
              "interestAllowanceNonConsolidatedInvestment",
              "interestAllowanceConsolidatedPartnership"
            ]
          }
        ]
      }
    },
    "interestAllowanceAlternativeCalculation": true,
    "activeInterestAllowanceAlternativeCalculation": false,
    "interestAllowanceNonConsolidatedInvestment": {
      "isElected": true,
      "nonConsolidatedInvestments": [
        {
          "investmentName": "some Investment"
        }
      ]
    },
    "interestAllowanceConsolidatedPartnership": {
      "isElected": true,
      "isActive": false,
      "consolidatedPartnerships": [
        {
          "partnershipName": "some partner",
          "sautr": "1123456789"
        }
      ]
    }
  },
  "ukCompanies": [
    {
      "companyName": "Company Name ltd",
      "utr": "1123456789",
      "consenting": true,
      "qicElection": true,
      "netTaxInterestExpense": 0,
      "netTaxInterestIncome": 50,
      "taxEBITDA": 5,
      "allocatedReactivations": {
        "currentPeriodReactivation": 2
      }
    },
    {
      "companyName": "Company Name ltd",
      "utr": "1123456789",
      "consenting": true,
      "qicElection": true,
      "netTaxInterestExpense": 0,
      "netTaxInterestIncome": 50,
      "taxEBITDA": 5,
      "allocatedReactivations": {
        "currentPeriodReactivation": 2
      }
    }
  ],
  "angie": 1.11,
  "returnContainsEstimates": false,
  "groupSubjectToInterestRestrictions": false,
  "groupSubjectToInterestReactivation": true,
  "totalReactivation": 4,
  "totalRestrictions": 0,
  "groupLevelAmount": {
    "interestReactivationCap": 300,
    "interestAllowanceBroughtForward": 3,
    "interestAllowanceForPeriod": 4,
    "interestCapacityForPeriod": 5
  },
  "adjustedGroupInterest": {
    "qngie": 100,
    "groupEBITDA": 200,
    "groupRatio": 50
  },
  "declaration": true
}

Name	Description
appointedReportingCompany boolean required	Indicate if reporting company appointed
agentDetails object required	Details of the agent where an agent is submitting on behalf of the reporting company
agentActingOnBehalfOfCompany boolean required	Is an agent acting on behalf of the reporting company
agentName string optional	Name of the agent where an agent is acting on behalf of the reporting company Must conform to the regular expression ^[ -~¡-ÿĀ-ʯḀ-ỿ‐-―‘-‟₠-₿ÅK]{1,160}$
reportingCompany object required	Details of the reporting company
companyName string required	Name of the reporting company Must conform to the regular expression ^[ -~¡-ÿĀ-ʯḀ-ỿ‐-―‘-‟₠-₿ÅK]{1,160}$
ctutr string required	Reporting company's Corporation Tax Unique Taxpayer Reference Must conform to the regular expression ^[0-9]{10}$
sameAsUltimateParent boolean required	Indicate whether the reporting company is also the ultimate parent company
parentCompany object optional	Details of the parent company, which can be ultimate parent or deemed parent
ultimateParent object optional	Details of the ultimate parent company
isUk boolean required	Indicate whether the ultimate parent company is a UK company
companyName string required	Name of the ultimate parent company Must conform to the regular expression ^[ -~¡-ÿĀ-ʯḀ-ỿ‐-―‘-‟₠-₿ÅK]{1,160}$
ctutr string optional	Ultimate parent's Corporation Tax Unique Taxpayer Reference. Must conform to the regular expression ^[0-9]{10}$
sautr string optional	Ultimate parent company's self assessment Unique Taxpayer Reference Must conform to the regular expression ^[0-9]{10}$
countryOfIncorporation string optional	Country of incorporation where the ultimate parent company is not a UK company. A valid ISO 3166-1 2 Alpha Country Code For example: US
legalEntityIdentifier string optional	A Legal Entity Identifier (LEI); format is as per the ISO 17442 standard - 18 uppercase alphabetic or numeric characters followed by 2 numeric characters Must conform to the regular expression ^[0-9A-Z]{18}[0-9]{2}$
deemedParent array optional	Details of the entities that make up the deemed parent company
isUk boolean required	Indicate if the entity is a UK company
companyName string required	Name of the entity Must conform to the regular expression ^[ -~¡-ÿĀ-ʯḀ-ỿ‐-―‘-‟₠-₿ÅK]{1,160}$
ctutr string optional	Entity's Corporation Tax Unique Taxpayer Reference Must conform to the regular expression ^[0-9]{10}$
sautr string optional	Entity's Self Assessment Unique Taxpayer Reference Must conform to the regular expression ^[0-9]{10}$
countryOfIncorporation string optional	Country of incorporation where the entity is not a UK company. A valid ISO 3166-1 2 alpha country code For example: US
legalEntityIdentifier string optional	A Legal Entity Identifier (LEI); format is as per the ISO 17442 standard - 18 uppercase alphabetic or numeric characters followed by 2 numeric characters Must conform to the regular expression ^[0-9A-Z]{18}[0-9]{2}$
groupCompanyDetails object required	Details of the worldwide group
accountingPeriod object required	Worldwide group's period of account
startDate string required	Start date of the group's period of account, which cannot be before 2016-10-01 Must conform to the regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$
endDate string required	End date of the group's period of account, which must be within 18 months of the start date Must conform to the regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$
submissionType string required	Indicate whether this is the first (original) return or an amended (revised) return Limited to the following possible values: original revised
revisedReturnDetails string optional	What information has been revised since the original return Must conform to the regular expression ^[ -~¢-¥©®±×÷‐₠-₿−-∝≈≠≣-≥]{1,5000}$
angie number required	Adjusted net group-interest expense (ANGIE) amount
returnContainsEstimates boolean required	Indicate if the return contains estimated figures
groupEstimateReason string optional	Reasons for group level figures being estimated
groupSubjectToInterestRestrictions boolean required	Indicate if the group has an interest restriction
groupSubjectToInterestReactivation boolean required	Indicate if the group has a reactivation
groupLevelElections object required	Details of the calculation methods elected by the group
groupRatio object required	Details of the group ratio method of calculation
isElected boolean required	Indicate if the group wants to use the group ratio calculation
groupRatioBlended object optional	Details of the blended group ratio method of calculation
isElected boolean required	Indicate if the group also elects to use a blended group ratio calculation
investorGroups array optional	List investor groups the blended group ratio election relates to
groupName string required	Name of the investor group Must conform to the regular expression ^[ -~¡-ÿĀ-ʯḀ-ỿ‐-―‘-‟₠-₿ÅK]{1,160}$
elections array optional	Elections made by the investor group. Limited to the following possible values: groupRatioBlended groupEBITDA interestAllowanceAlternativeCalculation interestAllowanceNonConsolidatedInvestment interestAllowanceConsolidatedPartnership
groupEBITDAChargeableGains boolean required	Indicate if the group elects to use group-EBITDA chargeable gains election
activeGroupEBITDAChargeableGains boolean required	Indicate if the group has an active group-EBITDA chargeable gains election
interestAllowanceAlternativeCalculation boolean required	Indicate if the group elects interest allowance alternative calculation
activeInterestAllowanceAlternativeCalculation boolean required	Indicate if the group has an active interest allowance alternative calculation election
interestAllowanceNonConsolidatedInvestment object required	Details of interest allowance non-consolidated investment
isElected boolean required	Indicate whether the group elects to include interest allowance non-consolidated investments
nonConsolidatedInvestments array optional	List the non-consolidated investments
investmentName string required	Name of investment Must conform to the regular expression ^[ -~¢-¥©®±×÷‐₠-₿−-∝≈≠≣-≥]{1,5000}$
interestAllowanceConsolidatedPartnership object required	Details of interest allowance consolidated partnership
isElected boolean required	Indicate if the group elects interest allowance consolidated partnership
isActive boolean required	Indicate if the group has an active interest allowance consolidated partnership election
consolidatedPartnerships array optional	List partnerships
partnershipName string required	Name of partnership Must conform to the regular expression ^[ -~¡-ÿĀ-ʯḀ-ỿ‐-―‘-‟₠-₿ÅK]{1,160}$
sautr string optional	Partnership's Self Assessment Unique Taxpayer Reference. Must conform to the regular expression ^[0-9]{10}$
ukCompanies array required	Details of all the UK companies in the group
companyName string required	Name of the UK company Must conform to the regular expression ^[ -~¡-ÿĀ-ʯḀ-ỿ‐-―‘-‟₠-₿ÅK]{1,160}$
utr string required	UK company's Unique Taxpayer Reference. Must conform to the regular expression ^[0-9]{10}$
consenting boolean required	Indicate if the UK company agrees to take on the group's restriction in its Corporation Tax return
qicElection boolean required	Indicate whether any of the UK companies in the group has made a qualifying infrastructure company (QIC) election
netTaxInterestExpense number required	Amount of net tax-interest expense
netTaxInterestIncome number required	Amount of net tax-interest income
allocatedRestrictions object optional	Details of the disallowances for the company's accounting periods
ap1EndDate string required	End date of the first accounting period that a company can apportion a disallowance to. For example: 2020-04-06 Must conform to the regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$
ap2EndDate string optional	End date of the second accounting period that a company can apportion a disallowance to. For example: 2020-07-06 Must conform to the regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$
ap3EndDate string optional	End date of the third accounting period that a company can apportion a disallowance to. For example: 2020-10-06 Must conform to the regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$
disallowanceAp1 number required	Amount of disallowance for the first accounting period
disallowanceAp2 number optional	Amount of disallowance for the second accounting period
disallowanceAp3 number optional	Amount of disallowance for the third accounting period
totalDisallowances number required	Total disallowances for all accounting periods
allocatedReactivations object optional	Details of reactivations for the group's period of account
currentPeriodReactivation number required	Amount reactivated for group's period of account
taxEBITDA number required	Amount of earnings before interest, tax, depreciation and amortisation (EBITDA)
companyEstimateReason string optional	Reasons for company level figures being estimated
groupLevelAmount object required	Group level amounts
interestReactivationCap number required	Interest reactivation cap
interestAllowanceBroughtForward number required	Interest allowance brought forward
interestAllowanceForPeriod number required	Amount of interest allowance used for the period of account
interestCapacityForPeriod number required	Amount of interest capacity for the period of account to carry forward
adjustedGroupInterest object optional	Amount of adjusted group interest
qngie number required	Amount of qualifying net interest expense (QNGIE) for the group
groupEBITDA number required	Amount of earnings before interest, tax, depreciation and amortisation (EBITDA) for the group
groupRatio number required	QNGIE divided by the group-EBITDA
totalRestrictions number required	Total of all allocated restrictions for each UK company
declaration boolean required	Statement to confirm the truth of the information given

Response

HTTP status: 200 (OK)

Typical response received

{
  "acknowledgementReference": "XAIRR00000012345678"
}

Name	Description
acknowledgementReference string required	Confirmation of submission with reference number

Error scenarios

Scenario	HTTP status	Code
Matching resource not found.	404 (Not Found)	MATCHING_RESOURCE_NOT_FOUND
The requested resource could not be found.	404 (Not Found)	NOT_FOUND
An internal server error occurred.	500 (Internal Server Error)	INTERNAL_SERVER_ERROR
Invalid request.	400 (Bad Request)	INVALID_REQUEST
Expecting text/json or application/json body.	400 (Bad Request)	INVALID_BODY_TYPE
The client and/or agent is not authorised.	401 (Unauthorized)	CLIENT_OR_AGENT_NOT_AUTHORISED
The accept header is missing or invalid.	406 (Not Acceptable)	ACCEPT_HEADER_INVALID

For error scenarios that are common across all APIs, and for error formats, see our reference guide.

Close Section

/organisations/interest-restriction/return/full/validate

Validate a Full Interest Restriction Return

POST

Validates the payload for a Full Interest Restriction Return without submitting the return

Authorisation

This endpoint is user-restricted and requires an Authorization header containing an OAuth 2.0 Bearer Token with the write:interest-restriction-return scope.

Request headers

Name	Description
Accept required	Specifies the response format and the version of the API to use. For example: application/vnd.hmrc.1.0+json
Content-Type required	Specifies the format of the request body, which must be JSON. For example: application/json
Authorization required	An OAuth 2.0 Bearer Token with the write:interest-restriction-return scope. For example: Bearer bb7fed3fe10dd235a2ccda3d50fb

See also fraud prevention.

Request

Scenario: Validate a full IRR

{
  "appointedReportingCompany": true,
  "agentDetails": {
    "agentActingOnBehalfOfCompany": true,
    "agentName": "some agent"
  },
  "reportingCompany": {
    "companyName": "Company Name ltd",
    "ctutr": "1123456789",
    "sameAsUltimateParent": false
  },
  "parentCompany": {
    "ultimateParent": {
      "companyName": "Company Name ltd",
      "isUk": true,
      "ctutr": "1123456789"
    }
  },
  "groupCompanyDetails": {
    "accountingPeriod": {
      "startDate": "2019-02-18",
      "endDate": "2020-08-17"
    }
  },
  "submissionType": "revised",
  "revisedReturnDetails": "some details",
  "groupLevelElections": {
    "groupRatio": {
      "isElected": true,
      "groupEBITDAChargeableGains": true,
      "activeGroupEBITDAChargeableGains": false,
      "groupRatioBlended": {
        "isElected": true,
        "investorGroups": [
          {
            "groupName": "some investor group",
            "elections": [
              "groupRatioBlended",
              "groupEBITDA",
              "interestAllowanceAlternativeCalculation",
              "interestAllowanceNonConsolidatedInvestment",
              "interestAllowanceConsolidatedPartnership"
            ]
          },
          {
            "groupName": "some investor group",
            "elections": [
              "interestAllowanceAlternativeCalculation",
              "interestAllowanceNonConsolidatedInvestment",
              "interestAllowanceConsolidatedPartnership"
            ]
          }
        ]
      }
    },
    "interestAllowanceAlternativeCalculation": true,
    "activeInterestAllowanceAlternativeCalculation": false,
    "interestAllowanceNonConsolidatedInvestment": {
      "isElected": true,
      "nonConsolidatedInvestments": [
        {
          "investmentName": "some Investment"
        }
      ]
    },
    "interestAllowanceConsolidatedPartnership": {
      "isElected": true,
      "isActive": false,
      "consolidatedPartnerships": [
        {
          "partnershipName": "some partner",
          "sautr": "1123456789"
        }
      ]
    }
  },
  "ukCompanies": [
    {
      "companyName": "Company Name ltd",
      "utr": "1123456789",
      "consenting": true,
      "qicElection": true,
      "netTaxInterestExpense": 0,
      "netTaxInterestIncome": 50,
      "taxEBITDA": 5,
      "allocatedReactivations": {
        "currentPeriodReactivation": 2
      }
    },
    {
      "companyName": "Company Name ltd",
      "utr": "1123456789",
      "consenting": true,
      "qicElection": true,
      "netTaxInterestExpense": 0,
      "netTaxInterestIncome": 50,
      "taxEBITDA": 5,
      "allocatedReactivations": {
        "currentPeriodReactivation": 2
      }
    }
  ],
  "angie": 1.11,
  "returnContainsEstimates": false,
  "groupSubjectToInterestRestrictions": false,
  "groupSubjectToInterestReactivation": true,
  "totalReactivation": 4,
  "totalRestrictions": 0,
  "groupLevelAmount": {
    "interestReactivationCap": 300,
    "interestAllowanceBroughtForward": 3,
    "interestAllowanceForPeriod": 4,
    "interestCapacityForPeriod": 5
  },
  "adjustedGroupInterest": {
    "qngie": 100,
    "groupEBITDA": 200,
    "groupRatio": 50
  },
  "declaration": true
}

Name	Description
appointedReportingCompany boolean required	Indicate if reporting company appointed
agentDetails object required	Details of the agent where an agent is submitting on behalf of the reporting company
agentActingOnBehalfOfCompany boolean required	Is an agent acting on behalf of the reporting company
agentName string optional	Name of the agent where an agent is acting on behalf of the reporting company Must conform to the regular expression ^[ -~¡-ÿĀ-ʯḀ-ỿ‐-―‘-‟₠-₿ÅK]{1,160}$
reportingCompany object required	Details of the reporting company
companyName string required	Name of the reporting company Must conform to the regular expression ^[ -~¡-ÿĀ-ʯḀ-ỿ‐-―‘-‟₠-₿ÅK]{1,160}$
ctutr string required	Reporting company's Corporation Tax Unique Taxpayer Reference Must conform to the regular expression ^[0-9]{10}$
sameAsUltimateParent boolean required	Indicate whether the reporting company is also the ultimate parent company
parentCompany object optional	Details of the parent company, which can be ultimate parent or deemed parent
ultimateParent object optional	Details of the ultimate parent company
isUk boolean required	Indicate whether the ultimate parent company is a UK company
companyName string required	Name of the ultimate parent company Must conform to the regular expression ^[ -~¡-ÿĀ-ʯḀ-ỿ‐-―‘-‟₠-₿ÅK]{1,160}$
ctutr string optional	Ultimate parent's Corporation Tax Unique Taxpayer Reference. Must conform to the regular expression ^[0-9]{10}$
sautr string optional	Ultimate parent company's self assessment Unique Taxpayer Reference Must conform to the regular expression ^[0-9]{10}$
countryOfIncorporation string optional	Country of incorporation where the ultimate parent company is not a UK company. A valid ISO 3166-1 2 Alpha Country Code For example: US
legalEntityIdentifier string optional	A Legal Entity Identifier (LEI); format is as per the ISO 17442 standard - 18 uppercase alphabetic or numeric characters followed by 2 numeric characters Must conform to the regular expression ^[0-9A-Z]{18}[0-9]{2}$
deemedParent array optional	Details of the entities that make up the deemed parent company
isUk boolean required	Indicate if the entity is a UK company
companyName string required	Name of the entity Must conform to the regular expression ^[ -~¡-ÿĀ-ʯḀ-ỿ‐-―‘-‟₠-₿ÅK]{1,160}$
ctutr string optional	Entity's Corporation Tax Unique Taxpayer Reference Must conform to the regular expression ^[0-9]{10}$
sautr string optional	Entity's Self Assessment Unique Taxpayer Reference Must conform to the regular expression ^[0-9]{10}$
countryOfIncorporation string optional	Country of incorporation where the entity is not a UK company. A valid ISO 3166-1 2 alpha country code For example: US
legalEntityIdentifier string optional	A Legal Entity Identifier (LEI); format is as per the ISO 17442 standard - 18 uppercase alphabetic or numeric characters followed by 2 numeric characters Must conform to the regular expression ^[0-9A-Z]{18}[0-9]{2}$
groupCompanyDetails object required	Details of the worldwide group
accountingPeriod object required	Worldwide group's period of account
startDate string required	Start date of the group's period of account, which cannot be before 2016-10-01 Must conform to the regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$
endDate string required	End date of the group's period of account, which must be within 18 months of the start date Must conform to the regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$
submissionType string required	Indicate whether this is the first (original) return or an amended (revised) return Limited to the following possible values: original revised
revisedReturnDetails string optional	What information has been revised since the original return Must conform to the regular expression ^[ -~¢-¥©®±×÷‐₠-₿−-∝≈≠≣-≥]{1,5000}$
angie number required	Adjusted net group-interest expense (ANGIE) amount
returnContainsEstimates boolean required	Indicate if the return contains estimated figures
groupEstimateReason string optional	Reasons for group level figures being estimated
groupSubjectToInterestRestrictions boolean required	Indicate if the group has an interest restriction
groupSubjectToInterestReactivation boolean required	Indicate if the group has a reactivation
groupLevelElections object required	Details of the calculation methods elected by the group
groupRatio object required	Details of the group ratio method of calculation
isElected boolean required	Indicate if the group wants to use the group ratio calculation
groupRatioBlended object optional	Details of the blended group ratio method of calculation
isElected boolean required	Indicate if the group also elects to use a blended group ratio calculation
investorGroups array optional	List investor groups the blended group ratio election relates to
groupName string required	Name of the investor group Must conform to the regular expression ^[ -~¡-ÿĀ-ʯḀ-ỿ‐-―‘-‟₠-₿ÅK]{1,160}$
elections array optional	Elections made by the investor group. Limited to the following possible values: groupRatioBlended groupEBITDA interestAllowanceAlternativeCalculation interestAllowanceNonConsolidatedInvestment interestAllowanceConsolidatedPartnership
groupEBITDAChargeableGains boolean required	Indicate if the group elects to use group-EBITDA chargeable gains election
activeGroupEBITDAChargeableGains boolean required	Indicate if the group has an active group-EBITDA chargeable gains election
interestAllowanceAlternativeCalculation boolean required	Indicate if the group elects interest allowance alternative calculation
activeInterestAllowanceAlternativeCalculation boolean required	Indicate if the group has an active interest allowance alternative calculation election
interestAllowanceNonConsolidatedInvestment object required	Details of interest allowance non-consolidated investment
isElected boolean required	Indicate whether the group elects to include interest allowance non-consolidated investments
nonConsolidatedInvestments array optional	List the non-consolidated investments
investmentName string required	Name of investment Must conform to the regular expression ^[ -~¢-¥©®±×÷‐₠-₿−-∝≈≠≣-≥]{1,5000}$
interestAllowanceConsolidatedPartnership object required	Details of interest allowance consolidated partnership
isElected boolean required	Indicate if the group elects interest allowance consolidated partnership
isActive boolean required	Indicate if the group has an active interest allowance consolidated partnership election
consolidatedPartnerships array optional	List partnerships
partnershipName string required	Name of partnership Must conform to the regular expression ^[ -~¡-ÿĀ-ʯḀ-ỿ‐-―‘-‟₠-₿ÅK]{1,160}$
sautr string optional	Partnership's Self Assessment Unique Taxpayer Reference. Must conform to the regular expression ^[0-9]{10}$
ukCompanies array required	Details of all the UK companies in the group
companyName string required	Name of the UK company Must conform to the regular expression ^[ -~¡-ÿĀ-ʯḀ-ỿ‐-―‘-‟₠-₿ÅK]{1,160}$
utr string required	UK company's Unique Taxpayer Reference. Must conform to the regular expression ^[0-9]{10}$
consenting boolean required	Indicate if the UK company agrees to take on the group's restriction in its Corporation Tax return
qicElection boolean required	Indicate whether any of the UK companies in the group has made a qualifying infrastructure company (QIC) election
netTaxInterestExpense number required	Amount of net tax-interest expense
netTaxInterestIncome number required	Amount of net tax-interest income
allocatedRestrictions object optional	Details of the disallowances for the company's accounting periods
ap1EndDate string required	End date of the first accounting period that a company can apportion a disallowance to. For example: 2020-04-06 Must conform to the regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$
ap2EndDate string optional	End date of the second accounting period that a company can apportion a disallowance to. For example: 2020-07-06 Must conform to the regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$
ap3EndDate string optional	End date of the third accounting period that a company can apportion a disallowance to. For example: 2020-10-06 Must conform to the regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$
disallowanceAp1 number required	Amount of disallowance for the first accounting period
disallowanceAp2 number optional	Amount of disallowance for the second accounting period
disallowanceAp3 number optional	Amount of disallowance for the third accounting period
totalDisallowances number required	Total disallowances for all accounting periods
allocatedReactivations object optional	Details of reactivations for the group's period of account
currentPeriodReactivation number required	Amount reactivated for group's period of account
taxEBITDA number required	Amount of earnings before interest, tax, depreciation and amortisation (EBITDA)
companyEstimateReason string optional	Reasons for company level figures being estimated
groupLevelAmount object required	Group level amounts
interestReactivationCap number required	Interest reactivation cap
interestAllowanceBroughtForward number required	Interest allowance brought forward
interestAllowanceForPeriod number required	Amount of interest allowance used for the period of account
interestCapacityForPeriod number required	Amount of interest capacity for the period of account to carry forward
adjustedGroupInterest object optional	Amount of adjusted group interest
qngie number required	Amount of qualifying net interest expense (QNGIE) for the group
groupEBITDA number required	Amount of earnings before interest, tax, depreciation and amortisation (EBITDA) for the group
groupRatio number required	QNGIE divided by the group-EBITDA
totalRestrictions number required	Total of all allocated restrictions for each UK company
declaration boolean required	Statement to confirm the truth of the information given

Response

HTTP status: 204 (No Content)

Error scenarios

Scenario	HTTP status	Code
Matching resource not found.	404 (Not Found)	MATCHING_RESOURCE_NOT_FOUND
The requested resource could not be found.	404 (Not Found)	NOT_FOUND
Invalid request.	400 (Bad Request)	INVALID_REQUEST
Expecting text/json or application/json body.	400 (Bad Request)	INVALID_BODY_TYPE
The client and/or agent is not authorised.	401 (Unauthorized)	CLIENT_OR_AGENT_NOT_AUTHORISED
The accept header is missing or invalid.	406 (Not Acceptable)	ACCEPT_HEADER_INVALID

For error scenarios that are common across all APIs, and for error formats, see our reference guide.

Close Section

/organisations/interest-restriction/return/abbreviated

Post an Abbreviated Interest Restriction Return

POST

Validates the payload for an Abbreviated Interest Restriction Return without submitting the return

Authorisation

This endpoint is user-restricted and requires an Authorization header containing an OAuth 2.0 Bearer Token with the write:interest-restriction-return scope.

Request headers

Name	Description
Accept required	Specifies the response format and the version of the API to use. For example: application/vnd.hmrc.1.0+json
Content-Type required	Specifies the format of the request body, which must be JSON. For example: application/json
Authorization required	An OAuth 2.0 Bearer Token with the write:interest-restriction-return scope. For example: Bearer bb7fed3fe10dd235a2ccda3d50fb

See also fraud prevention.

Request

Scenario: Abbreviated Return

{
  "appointedReportingCompany": true,
  "agentDetails": {
    "agentActingOnBehalfOfCompany": true,
    "agentName": "AAgent"
  },
  "reportingCompany": {
    "companyName": "ACompany",
    "ctutr": "1123456789",
    "sameAsUltimateParent": false
  },
  "parentCompany": {
    "ultimateParent": {
      "companyName": "BCompany",
      "isUk": true,
      "ctutr": "1123456789"
    }
  },
  "groupCompanyDetails": {
    "accountingPeriod": {
      "startDate": "2018-07-27",
      "endDate": "2020-01-26"
    }
  },
  "submissionType": "revised",
  "revisedReturnDetails": "Reason for revision",
  "groupLevelElections": {
    "groupRatio": {
      "isElected": true,
      "groupEBITDAChargeableGains": true,
      "activeGroupEBITDAChargeableGains": false,
      "groupRatioBlended": {
        "isElected": true,
        "investorGroups": [
          {
            "groupName": "AInvestor"
          },
          {
            "groupName": "BInvestor"
          },
          {
            "groupName": "CInvestor"
          }
        ]
      }
    },
    "interestAllowanceAlternativeCalculation": true,
    "activeInterestAllowanceAlternativeCalculation": false,
    "interestAllowanceNonConsolidatedInvestment": {
      "isElected": true,
      "nonConsolidatedInvestments": [
        {
          "investmentName": "AInvestment"
        },
        {
          "investmentName": "BInvestment"
        }
      ]
    },
    "interestAllowanceConsolidatedPartnership": {
      "isElected": true,
      "isActive": false,
      "consolidatedPartnerships": [
        {
          "partnershipName": "APartnership",
          "sautr": "1123456789"
        },
        {
          "partnershipName": "BPartnership",
          "sautr": "1123456789"
        }
      ]
    }
  },
  "ukCompanies": [
    {
      "companyName": "ACompany",
      "utr": "1123456789",
      "consenting": true,
      "qicElection": false
    },
    {
      "companyName": "BCompany",
      "utr": "1123456789",
      "consenting": true,
      "qicElection": false
    },
    {
      "companyName": "CCompany",
      "utr": "1123456789",
      "consenting": false,
      "qicElection": true
    }
  ],
  "declaration": true
}

Name	Description
appointedReportingCompany boolean required	Indicate if reporting company appointed
agentDetails object required	Details of the agent where an agent is submitting on behalf of the reporting company
agentActingOnBehalfOfCompany boolean required	Is an agent acting on behalf of the reporting company
agentName string optional	Name of the agent where an agent is acting on behalf of the reporting company Must conform to the regular expression ^[ -~¡-ÿĀ-ʯḀ-ỿ‐-―‘-‟₠-₿ÅK]{1,160}$
reportingCompany object required	Details of the reporting company
companyName string required	Name of the reporting company Must conform to the regular expression ^[ -~¡-ÿĀ-ʯḀ-ỿ‐-―‘-‟₠-₿ÅK]{1,160}$
ctutr string required	Reporting company's Corporation Tax Unique Taxpayer Reference Must conform to the regular expression ^[0-9]{10}$
sameAsUltimateParent boolean required	Indicate whether the reporting company is also the ultimate parent company
parentCompany object optional	Details of the parent company, which can be ultimate parent or deemed parent
ultimateParent object optional	Details of the ultimate parent company
isUk boolean required	Indicate whether the ultimate parent company is a UK company
companyName string required	Name of the ultimate parent company Must conform to the regular expression ^[ -~¡-ÿĀ-ʯḀ-ỿ‐-―‘-‟₠-₿ÅK]{1,160}$
ctutr string optional	Ultimate parent's Corporation Tax Unique Taxpayer Reference. Must conform to the regular expression ^[0-9]{10}$
sautr string optional	Ultimate parent company's self assessment Unique Taxpayer Reference Must conform to the regular expression ^[0-9]{10}$
countryOfIncorporation string optional	Country of incorporation where the ultimate parent company is not a UK company. A valid ISO 3166-1 2 Alpha Country Code For example: US
legalEntityIdentifier string optional	A Legal Entity Identifier (LEI); format is as per the ISO 17442 standard - 18 uppercase alphabetic or numeric characters followed by 2 numeric characters Must conform to the regular expression ^[0-9A-Z]{18}[0-9]{2}$
deemedParent array optional	Details of the entities that make up the deemed parent company
isUk boolean required	Indicate if the entity is a UK company
companyName string required	Name of the entity Must conform to the regular expression ^[ -~¡-ÿĀ-ʯḀ-ỿ‐-―‘-‟₠-₿ÅK]{1,160}$
ctutr string optional	Entity's Corporation Tax Unique Taxpayer Reference Must conform to the regular expression ^[0-9]{10}$
sautr string optional	Entity's Self Assessment Unique Taxpayer Reference Must conform to the regular expression ^[0-9]{10}$
countryOfIncorporation string optional	Country of incorporation where the entity is not a UK company. A valid ISO 3166-1 2 alpha country code For example: US
legalEntityIdentifier string optional	A Legal Entity Identifier (LEI); format is as per the ISO 17442 standard - 18 uppercase alphabetic or numeric characters followed by 2 numeric characters Must conform to the regular expression ^[0-9A-Z]{18}[0-9]{2}$
groupCompanyDetails object required	Details of the worldwide group
accountingPeriod object required	Worldwide group's period of account
startDate string required	Start date of the group's period of account, which cannot be before 2016-10-01 Must conform to the regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$
endDate string required	End date of the group's period of account, which must be within 18 months of the start date Must conform to the regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$
submissionType string required	Indicate whether this is the first (original) return or an amended (revised) return Limited to the following possible values: original revised
revisedReturnDetails string optional	What information has been revised since the original return. Must conform to the regular expression ^[ -~¢-¥©®±×÷‐₠-₿−-∝≈≠≣-≥]{1,5000}$
groupLevelElections object optional	Details of the calculation methods elected by the group
groupRatio object required	Details of the group ratio method of calculation
isElected boolean required	Indicate if the group wants to use the group ratio calculation
groupRatioBlended object optional	Details of the blended group ratio method of calculation
isElected boolean required	Indicate if the group also elects to use a blended group ratio calculation
investorGroups array optional	List investor groups the blended group ratio election relates to
groupName string required	Name of the investor group Must conform to the regular expression ^[ -~¡-ÿĀ-ʯḀ-ỿ‐-―‘-‟₠-₿ÅK]{1,160}$
elections array optional	Elections made by the investor group. Limited to the following possible values: groupRatioBlended groupEBITDA interestAllowanceAlternativeCalculation interestAllowanceNonConsolidatedInvestment interestAllowanceConsolidatedPartnership
groupEBITDAChargeableGains boolean required	Indicate if the group elects to use group-EBITDA chargeable gains election
activeGroupEBITDAChargeableGains boolean required	Indicate if the group has an active group-EBITDA chargeable gains election
interestAllowanceAlternativeCalculation boolean required	Indicate if the group elects interest allowance alternative calculation
activeInterestAllowanceAlternativeCalculation boolean required	Indicate if the group has an active interest allowance alternative calculation election
interestAllowanceNonConsolidatedInvestment object required	Details of interest allowance non-consolidated investment
isElected boolean required	Indicate whether the group elects to include interest allowance non-consolidated investments
nonConsolidatedInvestments array optional	List the non-consolidated investments
investmentName string required	Name of investment Must conform to the regular expression ^[ -~¢-¥©®±×÷‐₠-₿−-∝≈≠≣-≥]{1,5000}$
interestAllowanceConsolidatedPartnership object required	Details of interest allowance consolidated partnership
isElected boolean required	Indicate if the group elects interest allowance consolidated partnership
isActive boolean required	Indicate if the group has an active interest allowance consolidated partnership election
consolidatedPartnerships array optional	List partnerships
partnershipName string required	Name of partnership Must conform to the regular expression ^[ -~¡-ÿĀ-ʯḀ-ỿ‐-―‘-‟₠-₿ÅK]{1,160}$
sautr string optional	Partnership's Self Assessment Unique Taxpayer Reference. Must conform to the regular expression ^[0-9]{10}$
ukCompanies array required	Details of all the UK companies in the group
companyName string required	Name of the UK company Must conform to the regular expression ^[ -~¡-ÿĀ-ʯḀ-ỿ‐-―‘-‟₠-₿ÅK]{1,160}$
utr string required	UK company's Unique Taxpayer Reference. Must conform to the regular expression ^[0-9]{10}$
consenting boolean required	Indicate if the UK company agrees to take on the group's restriction in its Corporation Tax return
qicElection boolean required	Indicate whether any of the UK companies in the group has made a qualifying infrastructure company (QIC) election
declaration boolean required	Statement to confirm the truth of the information given

Response

HTTP status: 200 (OK)

Typical response received

{
  "acknowledgementReference": "XAIRR00000012345678"
}

Name	Description
acknowledgementReference string required

Error scenarios

Scenario	HTTP status	Code
Matching resource not found.	404 (Not Found)	MATCHING_RESOURCE_NOT_FOUND
The requested resource could not be found.	404 (Not Found)	NOT_FOUND
An internal server error occurred.	500 (Internal Server Error)	INTERNAL_SERVER_ERROR
Invalid request.	400 (Bad Request)	INVALID_REQUEST
Expecting text/json or application/json body.	400 (Bad Request)	INVALID_BODY_TYPE
The client and/or agent is not authorised.	401 (Unauthorized)	CLIENT_OR_AGENT_NOT_AUTHORISED
The accept header is missing or invalid.	406 (Not Acceptable)	ACCEPT_HEADER_INVALID

For error scenarios that are common across all APIs, and for error formats, see our reference guide.

Close Section

/organisations/interest-restriction/return/abbreviated/validate

Validate an Abbreviated Interest Restriction Return

POST

Validates the payload for an Abbreviated Interest Restriction Return without submitting the return

Authorisation

This endpoint is user-restricted and requires an Authorization header containing an OAuth 2.0 Bearer Token with the write:interest-restriction-return scope.

Request headers

Name	Description
Accept required	Specifies the response format and the version of the API to use. For example: application/vnd.hmrc.1.0+json
Content-Type required	Specifies the format of the request body, which must be JSON. For example: application/json
Authorization required	An OAuth 2.0 Bearer Token with the write:interest-restriction-return scope. For example: Bearer bb7fed3fe10dd235a2ccda3d50fb

See also fraud prevention.

Request

Scenario: Abbreviated Return

{
  "appointedReportingCompany": true,
  "agentDetails": {
    "agentActingOnBehalfOfCompany": true,
    "agentName": "AAgent"
  },
  "reportingCompany": {
    "companyName": "ACompany",
    "ctutr": "1123456789",
    "sameAsUltimateParent": false
  },
  "parentCompany": {
    "ultimateParent": {
      "companyName": "BCompany",
      "isUk": true,
      "ctutr": "1123456789"
    }
  },
  "groupCompanyDetails": {
    "accountingPeriod": {
      "startDate": "2018-07-27",
      "endDate": "2020-01-26"
    }
  },
  "submissionType": "revised",
  "revisedReturnDetails": "Reason for revision",
  "groupLevelElections": {
    "groupRatio": {
      "isElected": true,
      "groupEBITDAChargeableGains": true,
      "activeGroupEBITDAChargeableGains": false,
      "groupRatioBlended": {
        "isElected": true,
        "investorGroups": [
          {
            "groupName": "AInvestor"
          },
          {
            "groupName": "BInvestor"
          },
          {
            "groupName": "CInvestor"
          }
        ]
      }
    },
    "interestAllowanceAlternativeCalculation": true,
    "activeInterestAllowanceAlternativeCalculation": false,
    "interestAllowanceNonConsolidatedInvestment": {
      "isElected": true,
      "nonConsolidatedInvestments": [
        {
          "investmentName": "AInvestment"
        },
        {
          "investmentName": "BInvestment"
        }
      ]
    },
    "interestAllowanceConsolidatedPartnership": {
      "isElected": true,
      "isActive": false,
      "consolidatedPartnerships": [
        {
          "partnershipName": "APartnership",
          "sautr": "1123456789"
        },
        {
          "partnershipName": "BPartnership",
          "sautr": "1123456789"
        }
      ]
    }
  },
  "ukCompanies": [
    {
      "companyName": "ACompany",
      "utr": "1123456789",
      "consenting": true,
      "qicElection": false
    },
    {
      "companyName": "BCompany",
      "utr": "1123456789",
      "consenting": true,
      "qicElection": false
    },
    {
      "companyName": "CCompany",
      "utr": "1123456789",
      "consenting": false,
      "qicElection": true
    }
  ],
  "declaration": true
}

Name	Description
appointedReportingCompany boolean required	Indicate if reporting company appointed
agentDetails object required	Details of the agent where an agent is submitting on behalf of the reporting company
agentActingOnBehalfOfCompany boolean required	Is an agent acting on behalf of the reporting company
agentName string optional	Name of the agent where an agent is acting on behalf of the reporting company Must conform to the regular expression ^[ -~¡-ÿĀ-ʯḀ-ỿ‐-―‘-‟₠-₿ÅK]{1,160}$
reportingCompany object required	Details of the reporting company
companyName string required	Name of the reporting company Must conform to the regular expression ^[ -~¡-ÿĀ-ʯḀ-ỿ‐-―‘-‟₠-₿ÅK]{1,160}$
ctutr string required	Reporting company's Corporation Tax Unique Taxpayer Reference Must conform to the regular expression ^[0-9]{10}$
sameAsUltimateParent boolean required	Indicate whether the reporting company is also the ultimate parent company
parentCompany object optional	Details of the parent company, which can be ultimate parent or deemed parent
ultimateParent object optional	Details of the ultimate parent company
isUk boolean required	Indicate whether the ultimate parent company is a UK company
companyName string required	Name of the ultimate parent company Must conform to the regular expression ^[ -~¡-ÿĀ-ʯḀ-ỿ‐-―‘-‟₠-₿ÅK]{1,160}$
ctutr string optional	Ultimate parent's Corporation Tax Unique Taxpayer Reference. Must conform to the regular expression ^[0-9]{10}$
sautr string optional	Ultimate parent company's self assessment Unique Taxpayer Reference Must conform to the regular expression ^[0-9]{10}$
countryOfIncorporation string optional	Country of incorporation where the ultimate parent company is not a UK company. A valid ISO 3166-1 2 Alpha Country Code For example: US
legalEntityIdentifier string optional	A Legal Entity Identifier (LEI); format is as per the ISO 17442 standard - 18 uppercase alphabetic or numeric characters followed by 2 numeric characters Must conform to the regular expression ^[0-9A-Z]{18}[0-9]{2}$
deemedParent array optional	Details of the entities that make up the deemed parent company
isUk boolean required	Indicate if the entity is a UK company
companyName string required	Name of the entity Must conform to the regular expression ^[ -~¡-ÿĀ-ʯḀ-ỿ‐-―‘-‟₠-₿ÅK]{1,160}$
ctutr string optional	Entity's Corporation Tax Unique Taxpayer Reference Must conform to the regular expression ^[0-9]{10}$
sautr string optional	Entity's Self Assessment Unique Taxpayer Reference Must conform to the regular expression ^[0-9]{10}$
countryOfIncorporation string optional	Country of incorporation where the entity is not a UK company. A valid ISO 3166-1 2 alpha country code For example: US
legalEntityIdentifier string optional	A Legal Entity Identifier (LEI); format is as per the ISO 17442 standard - 18 uppercase alphabetic or numeric characters followed by 2 numeric characters Must conform to the regular expression ^[0-9A-Z]{18}[0-9]{2}$
groupCompanyDetails object required	Details of the worldwide group
accountingPeriod object required	Worldwide group's period of account
startDate string required	Start date of the group's period of account, which cannot be before 2016-10-01 Must conform to the regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$
endDate string required	End date of the group's period of account, which must be within 18 months of the start date Must conform to the regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$
submissionType string required	Indicate whether this is the first (original) return or an amended (revised) return Limited to the following possible values: original revised
revisedReturnDetails string optional	What information has been revised since the original return. Must conform to the regular expression ^[ -~¢-¥©®±×÷‐₠-₿−-∝≈≠≣-≥]{1,5000}$
groupLevelElections object optional	Details of the calculation methods elected by the group
groupRatio object required	Details of the group ratio method of calculation
isElected boolean required	Indicate if the group wants to use the group ratio calculation
groupRatioBlended object optional	Details of the blended group ratio method of calculation
isElected boolean required	Indicate if the group also elects to use a blended group ratio calculation
investorGroups array optional	List investor groups the blended group ratio election relates to
groupName string required	Name of the investor group Must conform to the regular expression ^[ -~¡-ÿĀ-ʯḀ-ỿ‐-―‘-‟₠-₿ÅK]{1,160}$
elections array optional	Elections made by the investor group. Limited to the following possible values: groupRatioBlended groupEBITDA interestAllowanceAlternativeCalculation interestAllowanceNonConsolidatedInvestment interestAllowanceConsolidatedPartnership
groupEBITDAChargeableGains boolean required	Indicate if the group elects to use group-EBITDA chargeable gains election
activeGroupEBITDAChargeableGains boolean required	Indicate if the group has an active group-EBITDA chargeable gains election
interestAllowanceAlternativeCalculation boolean required	Indicate if the group elects interest allowance alternative calculation
activeInterestAllowanceAlternativeCalculation boolean required	Indicate if the group has an active interest allowance alternative calculation election
interestAllowanceNonConsolidatedInvestment object required	Details of interest allowance non-consolidated investment
isElected boolean required	Indicate whether the group elects to include interest allowance non-consolidated investments
nonConsolidatedInvestments array optional	List the non-consolidated investments
investmentName string required	Name of investment Must conform to the regular expression ^[ -~¢-¥©®±×÷‐₠-₿−-∝≈≠≣-≥]{1,5000}$
interestAllowanceConsolidatedPartnership object required	Details of interest allowance consolidated partnership
isElected boolean required	Indicate if the group elects interest allowance consolidated partnership
isActive boolean required	Indicate if the group has an active interest allowance consolidated partnership election
consolidatedPartnerships array optional	List partnerships
partnershipName string required	Name of partnership Must conform to the regular expression ^[ -~¡-ÿĀ-ʯḀ-ỿ‐-―‘-‟₠-₿ÅK]{1,160}$
sautr string optional	Partnership's Self Assessment Unique Taxpayer Reference. Must conform to the regular expression ^[0-9]{10}$
ukCompanies array required	Details of all the UK companies in the group
companyName string required	Name of the UK company Must conform to the regular expression ^[ -~¡-ÿĀ-ʯḀ-ỿ‐-―‘-‟₠-₿ÅK]{1,160}$
utr string required	UK company's Unique Taxpayer Reference. Must conform to the regular expression ^[0-9]{10}$
consenting boolean required	Indicate if the UK company agrees to take on the group's restriction in its Corporation Tax return
qicElection boolean required	Indicate whether any of the UK companies in the group has made a qualifying infrastructure company (QIC) election
declaration boolean required	Statement to confirm the truth of the information given

Response

HTTP status: 204 (No Content)

Error scenarios

Scenario	HTTP status	Code
Matching resource not found.	404 (Not Found)	MATCHING_RESOURCE_NOT_FOUND
The requested resource could not be found.	404 (Not Found)	NOT_FOUND
Invalid request.	400 (Bad Request)	INVALID_REQUEST
Expecting text/json or application/json body.	400 (Bad Request)	INVALID_BODY_TYPE
The client and/or agent is not authorised.	401 (Unauthorized)	CLIENT_OR_AGENT_NOT_AUTHORISED
The accept header is missing or invalid.	406 (Not Acceptable)	ACCEPT_HEADER_INVALID

For error scenarios that are common across all APIs, and for error formats, see our reference guide.

Close Section

Skip to main content

Is this page not working properly? (opens in new tab)