Interest Restriction Return API
Date | Amount |
---|---|
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.
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
Request headers
Name | Description |
---|---|
Accept
required
|
Specifies the response format and the version of the API to use. application/vnd.hmrc.1.0+json
|
Content-Type
required
|
Specifies the format of the request body, which must be JSON. 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 |
reportingCompany
object
required
|
Details of the reporting company |
companyName
string
required
|
Name of the reporting company
Must conform to the regular expression |
ctutr
string
required
|
Reporting company's Corporation Tax Unique Taxpayer Reference
Must conform to the regular expression |
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 |
utr
string
required
|
Authorising company's Unique Tax Reference.
Must conform to the regular expression |
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 |
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: |
ctutr
string
optional
|
Where the appointing company is a UK company, the Corporation Tax Unique Taxpayer Reference
Must conform to the regular expression |
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 |
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 |
ctutr
string
optional
|
Ultimate parent's Corporation Tax Unique Taxpayer Reference.
Must conform to the regular expression |
sautr
string
optional
|
Ultimate parent company's self assessment Unique Taxpayer Reference
Must conform to the regular expression |
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: |
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 |
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 |
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 |
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 |
Responses
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 |
You are unable to access this service as an individual. This service is only available to individual companies or groups of companies. |
403 (Forbidden) |
FORBIDDEN |
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
Request headers
Name | Description |
---|---|
Accept
required
|
Specifies the response format and the version of the API to use. application/vnd.hmrc.1.0+json
|
Content-Type
required
|
Specifies the format of the request body, which must be JSON. 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 |
reportingCompany
object
required
|
Details of the reporting company |
companyName
string
required
|
Name of the reporting company
Must conform to the regular expression |
ctutr
string
required
|
Reporting company's Corporation Tax Unique Taxpayer Reference
Must conform to the regular expression |
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 |
utr
string
required
|
Authorising company's Unique Tax Reference.
Must conform to the regular expression |
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 |
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: |
ctutr
string
optional
|
Where the appointing company is a UK company, the Corporation Tax Unique Taxpayer Reference
Must conform to the regular expression |
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 |
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 |
ctutr
string
optional
|
Ultimate parent's Corporation Tax Unique Taxpayer Reference.
Must conform to the regular expression |
sautr
string
optional
|
Ultimate parent company's self assessment Unique Taxpayer Reference
Must conform to the regular expression |
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: |
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 |
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 |
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 |
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 |
Responses
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 |
You are unable to access this service as an individual. This service is only available to individual companies or groups of companies. |
403 (Forbidden) |
FORBIDDEN |
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
Request headers
Name | Description |
---|---|
Accept
required
|
Specifies the response format and the version of the API to use. application/vnd.hmrc.1.0+json
|
Content-Type
required
|
Specifies the format of the request body, which must be JSON. 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 |
reportingCompany
object
required
|
Details of the reporting company |
companyName
string
required
|
Name of the reporting company
Must conform to the regular expression |
ctutr
string
required
|
Reporting company's Corporation Tax Unique Taxpayer Reference
Must conform to the regular expression |
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 |
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: |
ctutr
string
optional
|
Revoking company's Corporation Tax Unique Taxpayer Reference.
Must conform to the regular expression |
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 |
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 |
ctutr
string
optional
|
Ultimate parent's Corporation Tax Unique Taxpayer Reference.
Must conform to the regular expression |
sautr
string
optional
|
Ultimate parent company's self assessment Unique Taxpayer Reference
Must conform to the regular expression |
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: |
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 |
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 |
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 |
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 |
utr
string
required
|
Authorising company's Unique Tax Reference.
Must conform to the regular expression |
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 |
Responses
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 |
You are unable to access this service as an individual. This service is only available to individual companies or groups of companies. |
403 (Forbidden) |
FORBIDDEN |
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
Request headers
Name | Description |
---|---|
Accept
required
|
Specifies the response format and the version of the API to use. application/vnd.hmrc.1.0+json
|
Content-Type
required
|
Specifies the format of the request body, which must be JSON. 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 |
reportingCompany
object
required
|
Details of the reporting company |
companyName
string
required
|
Name of the reporting company
Must conform to the regular expression |
ctutr
string
required
|
Reporting company's Corporation Tax Unique Taxpayer Reference
Must conform to the regular expression |
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 |
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: |
ctutr
string
optional
|
Revoking company's Corporation Tax Unique Taxpayer Reference.
Must conform to the regular expression |
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 |
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 |
ctutr
string
optional
|
Ultimate parent's Corporation Tax Unique Taxpayer Reference.
Must conform to the regular expression |
sautr
string
optional
|
Ultimate parent company's self assessment Unique Taxpayer Reference
Must conform to the regular expression |
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: |
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 |
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 |
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 |
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 |
utr
string
required
|
Authorising company's Unique Tax Reference.
Must conform to the regular expression |
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 |
Responses
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 |
You are unable to access this service as an individual. This service is only available to individual companies or groups of companies. |
403 (Forbidden) |
FORBIDDEN |
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
Request headers
Name | Description |
---|---|
Accept
required
|
Specifies the response format and the version of the API to use. application/vnd.hmrc.1.0+json
|
Content-Type
required
|
Specifies the format of the request body, which must be JSON. 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 |
reportingCompany
object
required
|
Details of the reporting company |
companyName
string
required
|
Name of the reporting company
Must conform to the regular expression |
ctutr
string
required
|
Reporting company's Corporation Tax Unique Taxpayer Reference
Must conform to the regular expression |
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 |
ctutr
string
optional
|
Ultimate parent's Corporation Tax Unique Taxpayer Reference.
Must conform to the regular expression |
sautr
string
optional
|
Ultimate parent company's self assessment Unique Taxpayer Reference
Must conform to the regular expression |
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: |
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 |
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 |
ctutr
string
optional
|
Entity's Corporation Tax Unique Taxpayer Reference
Must conform to the regular expression |
sautr
string
optional
|
Entity's Self Assessment Unique Taxpayer Reference
Must conform to the regular expression |
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: |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
sautr
string
optional
|
Partnership's Self Assessment Unique Taxpayer Reference.
Must conform to the regular expression |
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 |
utr
string
required
|
UK company's Unique Taxpayer Reference.
Must conform to the regular expression |
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 |
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 |
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 |
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 |
Responses
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 |
You are unable to access this service as an individual. This service is only available to individual companies or groups of companies. |
403 (Forbidden) |
FORBIDDEN |
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
Request headers
Name | Description |
---|---|
Accept
required
|
Specifies the response format and the version of the API to use. application/vnd.hmrc.1.0+json
|
Content-Type
required
|
Specifies the format of the request body, which must be JSON. 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 |
reportingCompany
object
required
|
Details of the reporting company |
companyName
string
required
|
Name of the reporting company
Must conform to the regular expression |
ctutr
string
required
|
Reporting company's Corporation Tax Unique Taxpayer Reference
Must conform to the regular expression |
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 |
ctutr
string
optional
|
Ultimate parent's Corporation Tax Unique Taxpayer Reference.
Must conform to the regular expression |
sautr
string
optional
|
Ultimate parent company's self assessment Unique Taxpayer Reference
Must conform to the regular expression |
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: |
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 |
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 |
ctutr
string
optional
|
Entity's Corporation Tax Unique Taxpayer Reference
Must conform to the regular expression |
sautr
string
optional
|
Entity's Self Assessment Unique Taxpayer Reference
Must conform to the regular expression |
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: |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
sautr
string
optional
|
Partnership's Self Assessment Unique Taxpayer Reference.
Must conform to the regular expression |
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 |
utr
string
required
|
UK company's Unique Taxpayer Reference.
Must conform to the regular expression |
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 |
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 |
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 |
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 |
Responses
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 |
You are unable to access this service as an individual. This service is only available to individual companies or groups of companies. |
403 (Forbidden) |
FORBIDDEN |
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
Request headers
Name | Description |
---|---|
Accept
required
|
Specifies the response format and the version of the API to use. application/vnd.hmrc.1.0+json
|
Content-Type
required
|
Specifies the format of the request body, which must be JSON. 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 |
reportingCompany
object
required
|
Details of the reporting company |
companyName
string
required
|
Name of the reporting company
Must conform to the regular expression |
ctutr
string
required
|
Reporting company's Corporation Tax Unique Taxpayer Reference
Must conform to the regular expression |
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 |
ctutr
string
optional
|
Ultimate parent's Corporation Tax Unique Taxpayer Reference.
Must conform to the regular expression |
sautr
string
optional
|
Ultimate parent company's self assessment Unique Taxpayer Reference
Must conform to the regular expression |
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: |
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 |
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 |
ctutr
string
optional
|
Entity's Corporation Tax Unique Taxpayer Reference
Must conform to the regular expression |
sautr
string
optional
|
Entity's Self Assessment Unique Taxpayer Reference
Must conform to the regular expression |
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: |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
sautr
string
optional
|
Partnership's Self Assessment Unique Taxpayer Reference.
Must conform to the regular expression |
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 |
utr
string
required
|
UK company's Unique Taxpayer Reference.
Must conform to the regular expression |
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 |
Responses
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 |
You are unable to access this service as an individual. This service is only available to individual companies or groups of companies. |
403 (Forbidden) |
FORBIDDEN |
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
Request headers
Name | Description |
---|---|
Accept
required
|
Specifies the response format and the version of the API to use. application/vnd.hmrc.1.0+json
|
Content-Type
required
|
Specifies the format of the request body, which must be JSON. 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 |
reportingCompany
object
required
|
Details of the reporting company |
companyName
string
required
|
Name of the reporting company
Must conform to the regular expression |
ctutr
string
required
|
Reporting company's Corporation Tax Unique Taxpayer Reference
Must conform to the regular expression |
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 |
ctutr
string
optional
|
Ultimate parent's Corporation Tax Unique Taxpayer Reference.
Must conform to the regular expression |
sautr
string
optional
|
Ultimate parent company's self assessment Unique Taxpayer Reference
Must conform to the regular expression |
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: |
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 |
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 |
ctutr
string
optional
|
Entity's Corporation Tax Unique Taxpayer Reference
Must conform to the regular expression |
sautr
string
optional
|
Entity's Self Assessment Unique Taxpayer Reference
Must conform to the regular expression |
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: |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
sautr
string
optional
|
Partnership's Self Assessment Unique Taxpayer Reference.
Must conform to the regular expression |
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 |
utr
string
required
|
UK company's Unique Taxpayer Reference.
Must conform to the regular expression |
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 |
Responses
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 |
You are unable to access this service as an individual. This service is only available to individual companies or groups of companies. |
403 (Forbidden) |
FORBIDDEN |
For error scenarios that are common across all APIs, and for error formats, see our reference guide.
Close Section