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

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/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

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

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/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

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

Skip to main content

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