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	No

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)

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.

Validation errors will be returned with INVALID_REQUEST in the following format:

[
    {
        "field": "/accountingPeriod/endDate",
        "value": "2019-12-01",
        "errors": [
            "End Date must be after start date"
        ]
    }
]

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

Request headers Table
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
}

Request table
Name	Description
agentDetails object required	If an Agent is submitting this on behalf of the reporting company and group details are supplied here
agentActingOnBehalfOfCompany boolean required	Indicate whether the agent is acting on behalf of the reporting company
agentName string optional	If the agent is acting on behalf of the reporting company then the agent's name must be provided Must conform to the regular expression `^[ -~¡-ÿĀ-ʯḀ-ỿ‐-―‘-‟₠-₿ÅK]{1,160}$`
reportingCompany object required	The details of the reporting company
companyName string required	Name of the reporting company Must conform to the regular expression `^[ -~¡-ÿĀ-ʯḀ-ỿ‐-―‘-‟₠-₿ÅK]{1,160}$`
ctutr string required	The 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 the same as the ultimate parent
authorisingCompanies array required	The details of the authorising companies
companyName string required	Must conform to the regular expression `^[ -~¡-ÿĀ-ʯḀ-ỿ‐-―‘-‟₠-₿ÅK]{1,160}$`
utr string required	A UTR of 10 numeric characters Must conform to the regular expression `^[0-9]{10}$`
consenting boolean optional	Has the company consented to this return
isReportingCompanyAppointingItself boolean required	Indicate whether the reporting company is appointing itself
identityOfAppointingCompany object optional	The details of the appointing company
companyName string required	Name of the company Must conform to the regular expression `^[ -~¡-ÿĀ-ʯḀ-ỿ‐-―‘-‟₠-₿ÅK]{1,160}$`
countryOfIncorporation string optional	Country of incorporation. A valid ISO 3166-1 2 Alpha Country Code For example: `US`
ctutr string optional	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 pays tax in the UK
companyName string required	Name of the company Must conform to the regular expression `^[ -~¡-ÿĀ-ʯḀ-ỿ‐-―‘-‟₠-₿ÅK]{1,160}$`
ctutr string optional	Corporation Tax Unique Taxpayer Reference Must conform to the regular expression `^[0-9]{10}$`
sautr string optional	Self Assessment Unique Taxpayer Reference Must conform to the regular expression `^[0-9]{10}$`
countryOfIncorporation string optional	Country of incorporation. 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	Period of account
startDate string required	The start date of the accounting period. It cannot be before 2016-10-01 Must conform to the regular expression `^[0-9]{4}-[0-9]{2}-[0-9]{2}$`
endDate string required	The end date of the accounting period. It must be within 18 months after the start date Must conform to the regular expression `^[0-9]{4}-[0-9]{2}-[0-9]{2}$`
declaration boolean required	Declaration to confirm the listed companies constitute at least 50% of the eligible companies

Response

HTTP status: 200 (OK)

Typical response received

{
  "acknowledgementReference": "XAIRR00000012345678"
}

Response table
Name	Description
acknowledgementReference string required

Error scenarios

Error scenarios table
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

Request headers Table
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
}

Request table
Name	Description
agentDetails object required	If an Agent is submitting this on behalf of the reporting company and group details are supplied here
agentActingOnBehalfOfCompany boolean required	Indicate whether the agent is acting on behalf of the reporting company
agentName string optional	If the agent is acting on behalf of the reporting company then the agent's name must be provided Must conform to the regular expression `^[ -~¡-ÿĀ-ʯḀ-ỿ‐-―‘-‟₠-₿ÅK]{1,160}$`
reportingCompany object required	The details of the reporting company
companyName string required	Name of the reporting company Must conform to the regular expression `^[ -~¡-ÿĀ-ʯḀ-ỿ‐-―‘-‟₠-₿ÅK]{1,160}$`
ctutr string required	The 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 the same as the ultimate parent
isReportingCompanyRevokingItself boolean required	Indicate whether the reporting company is revoking itself
companyMakingRevocation object optional	The details of the appointing company
companyName string required	Name of the company Must conform to the regular expression `^[ -~¡-ÿĀ-ʯḀ-ỿ‐-―‘-‟₠-₿ÅK]{1,160}$`
countryOfIncorporation string optional	Country of incorporation. A valid ISO 3166-1 2 Alpha Country Code For example: `US`
ctutr string optional	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 pays tax in the UK
companyName string required	Name of the company Must conform to the regular expression `^[ -~¡-ÿĀ-ʯḀ-ỿ‐-―‘-‟₠-₿ÅK]{1,160}$`
ctutr string optional	Corporation Tax Unique Taxpayer Reference Must conform to the regular expression `^[0-9]{10}$`
sautr string optional	Self Assessment Unique Taxpayer Reference Must conform to the regular expression `^[0-9]{10}$`
countryOfIncorporation string optional	Country of incorporation. 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	Period of account
startDate string required	The start date of the accounting period. It cannot be before 2016-10-01 Must conform to the regular expression `^[0-9]{4}-[0-9]{2}-[0-9]{2}$`
endDate string required	The end date of the accounting period. It must be within 18 months after the start date Must conform to the regular expression `^[0-9]{4}-[0-9]{2}-[0-9]{2}$`
authorisingCompanies array required	The details of the authorising companies
companyName string required	Must conform to the regular expression `^[ -~¡-ÿĀ-ʯḀ-ỿ‐-―‘-‟₠-₿ÅK]{1,160}$`
utr string required	A UTR of 10 numeric characters Must conform to the regular expression `^[0-9]{10}$`
consenting boolean optional	Has the company consented to this return
declaration boolean required	Declaration to confirm the listed companies constitute at least 50% of the eligible companies

Response

HTTP status: 200 (OK)

Typical response received

{
  "acknowledgementReference": "XAIRR00000012345678"
}

Response table
Name	Description
acknowledgementReference string required

Error scenarios

Error scenarios table
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

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

To submit a Full IRR

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

Request headers Table
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,
      "groupRatioBlended": {
        "isElected": true,
        "investorGroups": [{
          "groupName": "some investor group",
          "elections": ["groupRatioBlended", "groupEBITDA", "interestAllowanceAlternativeCalculation", "interestAllowanceNonConsolidatedInvestment", "interestAllowanceConsolidatedPartnership"]
        }, {
          "groupName": "some investor group",
          "elections": ["interestAllowanceAlternativeCalculation", "interestAllowanceNonConsolidatedInvestment", "interestAllowanceConsolidatedPartnership"]
        }]
      }
    },
    "interestAllowanceAlternativeCalculation": true,
    "interestAllowanceNonConsolidatedInvestment": {
      "isElected": true,
      "nonConsolidatedInvestments": [{
        "investmentName": "some Investment"
      }]
    },
    "interestAllowanceConsolidatedPartnership": {
      "isElected": true,
      "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": true,
  "groupSubjectToInterestRestrictions": false,
  "groupSubjectToInterestReactivation": true,
  "totalReactivation": 4,
  "totalRestrictions": 0,
  "groupLevelAmount": {
    "interestReactivationCap": 300,
    "interestAllowanceBroughtForward": 3,
    "interestAllowanceForPeriod": 4,
    "interestCapacityForPeriod": 5
  },
  "adjustedGroupInterest": {
    "qngie": 100,
    "groupEBITDA": 200,
    "groupRatio": 50
  }
}

Request table
Name	Description
appointedReportingCompany boolean required	Indicate whether a reporting company has been reported
agentDetails object required	If an Agent is submitting this return on behalf of the reporting company and group details are supplied here
agentActingOnBehalfOfCompany boolean required	Indicate whether the agent is acting on behalf of the reporting company
agentName string optional	If the agent is acting on behalf of the reporting company then the agent's name must be provided Must conform to the regular expression `^[ -~¡-ÿĀ-ʯḀ-ỿ‐-―‘-‟₠-₿ÅK]{1,160}$`
reportingCompany object required	The details of the reporting company
companyName string required	Name of the reporting company Must conform to the regular expression `^[ -~¡-ÿĀ-ʯḀ-ỿ‐-―‘-‟₠-₿ÅK]{1,160}$`
ctutr string required	The 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 the same as the ultimate parent
parentCompany object optional	Details of the parent company, this can be either an ultimate parent company or a deemed parent
ultimateParent object optional	Details of the ultimate parent company
isUk boolean required	Indicate whether the ultimate parent company pays tax in the UK
companyName string required	Name of the company Must conform to the regular expression `^[ -~¡-ÿĀ-ʯḀ-ỿ‐-―‘-‟₠-₿ÅK]{1,160}$`
ctutr string optional	Corporation Tax Unique Taxpayer Reference Must conform to the regular expression `^[0-9]{10}$`
sautr string optional	Self Assessment Unique Taxpayer Reference Must conform to the regular expression `^[0-9]{10}$`
countryOfIncorporation string optional	Country of incorporation. 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 deemed parent companies
isUk boolean required	Indicate whether the ultimate parent company pays tax in the UK
companyName string required	Name of the company Must conform to the regular expression `^[ -~¡-ÿĀ-ʯḀ-ỿ‐-―‘-‟₠-₿ÅK]{1,160}$`
ctutr string optional	Corporation Tax Unique Taxpayer Reference Must conform to the regular expression `^[0-9]{10}$`
sautr string optional	Self Assessment Unique Taxpayer Reference Must conform to the regular expression `^[0-9]{10}$`
countryOfIncorporation string optional	Country of incorporation. 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 group company.
accountingPeriod object required	The worldwide group's accounting period
startDate string required	The start date of the accounting period. It cannot be before 2016-10-01 Must conform to the regular expression `^[0-9]{4}-[0-9]{2}-[0-9]{2}$`
endDate string required	The end date of the accounting period. It must be within 18 months after 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	A description of why the return is being amended, this is mandatory if the submissionType is 'revised' Must conform to the regular expression `^[ -~¢-¥©®±×÷‐₠-₿−-∝≈≠≣-≥]{1,5000}$`
angie number optional	Adjusted Net Group-Interest Expense (ANGIE) amount
returnContainsEstimates boolean required	Indicator for whether the return contains figures which are estimated
groupSubjectToInterestRestrictions boolean required	Indicator for whether the group is subject to interest restrictions
groupSubjectToInterestReactivation boolean required	Indicator for whether the group is subject to interest reactivations
groupLevelElections object required	Details of the calculation elections made by the group
groupRatio object required	Group Ratio
isElected boolean required	Indicate if the group has elected to use the group ratio calculation. If this is false then fixed ratio is used
groupRatioBlended object optional	Group Ratio Blended
isElected boolean required	Indicate if the group has elected to use the group ratio blended calculation. Can only be elected if group ratio is elected
investorGroups array optional	List the investor groups to which the group ratio blended election relates. Can only be supplied if group ratio blended is elected
groupName string required	Name of the group Must conform to the regular expression `^[ -~¡-ÿĀ-ʯḀ-ỿ‐-―‘-‟₠-₿ÅK]{1,160}$`
elections array optional	The elections made by this investor group Limited to the following possible values: `groupRatioBlended` `groupEBITDA` `interestAllowanceAlternativeCalculation` `interestAllowanceNonConsolidatedInvestment` `interestAllowanceConsolidatedPartnership`
groupEBITDAChargeableGains boolean optional	Indicate if the group has elected to use the group EBITDA chargeable gains election. Can only be elected if group ratio is elected
interestAllowanceAlternativeCalculation boolean required	Indicate if the group has elected to use the Interest Allowance Alternative Calculation election
interestAllowanceNonConsolidatedInvestment object required	Interest Allowance Non-Consolidated Investment
isElected boolean required	Indicate if the group has elected to use the Interest Allowance Non-Consolidated Investment election
nonConsolidatedInvestments array optional	List the investors
investmentName string required	Investment name Must conform to the regular expression `^[ -~¢-¥©®±×÷‐₠-₿−-∝≈≠≣-≥]{1,5000}$`
interestAllowanceConsolidatedPartnership object required	Interest Allowance Consolidated Partnership
isElected boolean required	Indicate if the group has elected to use the Interest Allowance Consolidated Partnership election
consolidatedPartnerships array optional	List the partnerships
partnershipName string required	Partnership name Must conform to the regular expression `^[ -~¡-ÿĀ-ʯḀ-ỿ‐-―‘-‟₠-₿ÅK]{1,160}$`
sautr string optional	Self Assessment Unique Taxpayer Reference Must conform to the regular expression `^[0-9]{10}$`
ukCompanies array required	Details of all the UK Companies which form part of the group
companyName string required	Must conform to the regular expression `^[ -~¡-ÿĀ-ʯḀ-ỿ‐-―‘-‟₠-₿ÅK]{1,160}$`
utr string required	A UTR of 10 numeric characters Must conform to the regular expression `^[0-9]{10}$`
consenting boolean required	Indicate whether the UK Company is a consenting company
qicElection boolean required	Indicate whether the UK Company participated in a QIC election
netTaxInterestExpense number required	The Net Tax Interest Expense amount
netTaxInterestIncome number required	The Net Tax Interest Income amount
allocatedRestrictions object optional
ap1EndDate string required	End date for the first Accounting Period apportioned dissallowances Must conform to the regular expression `^[0-9]{4}-[0-9]{2}-[0-9]{2}$`
ap2EndDate string optional	End date for the second Accounting Period apportioned dissallowances, if applicable. If supplied must be after ap1EndDate Must conform to the regular expression `^[0-9]{4}-[0-9]{2}-[0-9]{2}$`
ap3EndDate string optional	End date for the third Accounting Period apportioned dissallowances, if applicable. If supplied must be after ap2EndDate Must conform to the regular expression `^[0-9]{4}-[0-9]{2}-[0-9]{2}$`
disallowanceAp1 number optional	Amount for the first Accounting Period apportioned dissallowances, must be supplied if ap1EndDate is supplied
disallowanceAp2 number optional	Amount for the second Accounting Period apportioned dissallowances, must be supplied if ap2EndDate is supplied
disallowanceAp3 number optional	Amount for the third Accounting Period apportioned dissallowances, must be supplied if ap3EndDate is supplied
totalDisallowances number required	Total of disallowanceAp1, disallowanceAp2 and disallowanceAp3
allocatedReactivations object optional
currentPeriodReactivation number required	Amount being reactivated for current period of account
taxEBITDA number required	Earnings Before Interest, Tax, Depreciation and Amortization (EBITDA) amount
groupLevelAmount object required	Group level amounts
interestReactivationCap number required	Interest Reactivation Cap
interestAllowanceBroughtForward number required	Interest Allowance Brought Forward
interestAllowanceForPeriod number required	Interest Allowance used for this period
interestCapacityForPeriod number required	Interest Capacity for period to carry forward for future period
adjustedGroupInterest object optional	Adjusted group interest
qngie number required	Qualifying Net Group-Interest Expense (QNGIE) amount
groupEBITDA number required	Earnings Before Interest, Tax, Depreciation and Amortization (EBITDA) amount
groupRatio number required	Percentage figure, capped at 100%. Should be calculated as the QNGIE divided by the EBITDA, if negative result then set to 100%
totalRestrictions number required	Total of all allocated restrictions for each UK company

Response

HTTP status: 200 (OK)

Typical response received

{
  "acknowledgementReference": "XAIRR00000012345678"
}

Response table
Name	Description
acknowledgementReference string required

Error scenarios

Error scenarios table
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

Abbreviated Return

POST

Request to submit an Abbreviated 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

Request headers Table
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,
      "groupRatioBlended" : {
        "isElected" : true,
        "investorGroups" : [{
          "groupName" : "AInvestor"
        },
          {
            "groupName" : "BInvestor"
          },
          {
            "groupName" : "CInvestor"
          }]
      }
    },
    "interestAllowanceAlternativeCalculation" : true,
    "interestAllowanceNonConsolidatedInvestment" : {
      "isElected" : true,
      "nonConsolidatedInvestments" : [{
        "investmentName" : "AInvestment"
      },
        {
          "investmentName" : "BInvestment"
        }]
    },
    "interestAllowanceConsolidatedPartnership" : {
      "isElected" : true,
      "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
    }]
}

Request table
Name	Description
appointedReportingCompany boolean required	Indicate whether a reporting company has been reported
agentDetails object required	If an Agent is submitting this return on behalf of the reporting company and group details are supplied here
agentActingOnBehalfOfCompany boolean required	Indicate whether the agent is acting on behalf of the reporting company
agentName string optional	If the agent is acting on behalf of the reporting company then the agent's name must be provided Must conform to the regular expression `^[ -~¡-ÿĀ-ʯḀ-ỿ‐-―‘-‟₠-₿ÅK]{1,160}$`
reportingCompany object required	The details of the reporting company
companyName string required	Name of the reporting company Must conform to the regular expression `^[ -~¡-ÿĀ-ʯḀ-ỿ‐-―‘-‟₠-₿ÅK]{1,160}$`
ctutr string required	The 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 the same as the ultimate parent
parentCompany object optional	Details of the parent company, this can be either an ultimate parent company or a deemed parent
ultimateParent object optional	Details of the ultimate parent company
isUk boolean required	Indicate whether the ultimate parent company pays tax in the UK
companyName string required	Name of the company Must conform to the regular expression `^[ -~¡-ÿĀ-ʯḀ-ỿ‐-―‘-‟₠-₿ÅK]{1,160}$`
ctutr string optional	Corporation Tax Unique Taxpayer Reference Must conform to the regular expression `^[0-9]{10}$`
sautr string optional	Self Assessment Unique Taxpayer Reference Must conform to the regular expression `^[0-9]{10}$`
countryOfIncorporation string optional	Country of incorporation. 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 deemed parent companies
isUk boolean required	Indicate whether the ultimate parent company pays tax in the UK
companyName string required	Name of the company Must conform to the regular expression `^[ -~¡-ÿĀ-ʯḀ-ỿ‐-―‘-‟₠-₿ÅK]{1,160}$`
ctutr string optional	Corporation Tax Unique Taxpayer Reference Must conform to the regular expression `^[0-9]{10}$`
sautr string optional	Self Assessment Unique Taxpayer Reference Must conform to the regular expression `^[0-9]{10}$`
countryOfIncorporation string optional	Country of incorporation. 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 group company.
accountingPeriod object required	The worldwide group's accounting period
startDate string required	The start date of the accounting period. It cannot be before 2016-10-01 Must conform to the regular expression `^[0-9]{4}-[0-9]{2}-[0-9]{2}$`
endDate string required	The end date of the accounting period. It must be within 18 months after 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	A description of why the return is being amended, this is mandatory if the submissionType is 'revised' Must conform to the regular expression `^[ -~¢-¥©®±×÷‐₠-₿−-∝≈≠≣-≥]{1,5000}$`
ukCompanies array required	Details of all the UK Companies which form part of the group
companyName string required	Must conform to the regular expression `^[ -~¡-ÿĀ-ʯḀ-ỿ‐-―‘-‟₠-₿ÅK]{1,160}$`
utr string required	A UTR of 10 numeric characters Must conform to the regular expression `^[0-9]{10}$`
consenting boolean required	Indicate whether the UK Company is a consenting company
qicElection boolean required	Indicate whether the UK Company participated in a QIC election
groupLevelElections object optional	Details of the calculation elections made by the group
groupRatio object required	Group Ratio
isElected boolean required	Indicate if the group has elected to use the group ratio calculation. If this is false then fixed ratio is used
groupRatioBlended object optional	Group Ratio Blended
isElected boolean required	Indicate if the group has elected to use the group ratio blended calculation. Can only be elected if group ratio is elected
investorGroups array optional	List the investor groups to which the group ratio blended election relates. Can only be supplied if group ratio blended is elected
groupName string required	Name of the group Must conform to the regular expression `^[ -~¡-ÿĀ-ʯḀ-ỿ‐-―‘-‟₠-₿ÅK]{1,160}$`
elections array optional	The elections made by this investor group Limited to the following possible values: `groupRatioBlended` `groupEBITDA` `interestAllowanceAlternativeCalculation` `interestAllowanceNonConsolidatedInvestment` `interestAllowanceConsolidatedPartnership`
groupEBITDAChargeableGains boolean optional	Indicate if the group has elected to use the group EBITDA chargeable gains election. Can only be elected if group ratio is elected
interestAllowanceAlternativeCalculation boolean required	Indicate if the group has elected to use the Interest Allowance Alternative Calculation election
interestAllowanceNonConsolidatedInvestment object required	Interest Allowance Non-Consolidated Investment
isElected boolean required	Indicate if the group has elected to use the Interest Allowance Non-Consolidated Investment election
nonConsolidatedInvestments array optional	List the investors
investmentName string required	Investment name Must conform to the regular expression `^[ -~¢-¥©®±×÷‐₠-₿−-∝≈≠≣-≥]{1,5000}$`
interestAllowanceConsolidatedPartnership object required	Interest Allowance Consolidated Partnership
isElected boolean required	Indicate if the group has elected to use the Interest Allowance Consolidated Partnership election
consolidatedPartnerships array optional	List the partnerships
partnershipName string required	Partnership name Must conform to the regular expression `^[ -~¡-ÿĀ-ʯḀ-ỿ‐-―‘-‟₠-₿ÅK]{1,160}$`
sautr string optional	Self Assessment Unique Taxpayer Reference Must conform to the regular expression `^[0-9]{10}$`

Response

HTTP status: 200 (OK)

Typical response received

{
  "acknowledgementReference": "XAIRR00000012345678"
}

Response table
Name	Description
acknowledgementReference string required

Error scenarios

Error scenarios table
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

Is this page not working properly? Is this page not working properly?