This version is in beta - expect some breaking changes.
Interest Restriction Return API
Available in Sandbox | Yes |
---|---|
Sandbox base URL | https://test-api.service.hmrc.gov.uk |
Available in Production | No |
Overview
The API in its current state supports the following functions:
- Revoke an existing Reporting Company from submitting Interest Restriction Returns
- Appoint a new Reporting Company for submitting Interest Restriction Returns
- Submit an Interest Restriction Return (full)
- Submit an Interest Restriction Return (abbreviated)
Support
Raise non-technical or platform-related issues with the Software Development Support Team (SDST).
Raise technical issues on the interest-restriction-return issues page
Changelog
You can find the change log on the interest-restriction-return wiki page.
Versioning
When an API changes in a way that is backwards-incompatible, we increase the version number of the API. See our reference guide for more on versioning.
Errors
We use standard HTTP status codes to show whether an API request succeeded or not. They are usually in the range:
- 200 to 299 if it succeeded, including code 202 if it was accepted by an API that needs to wait for further action
- 400 to 499 if it failed because of a client error by your application
- 500 to 599 if it failed because of an error on our server
Errors specific to each API are shown in the Endpoints section, under Response. See our reference guide for more on errors.
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
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 for other request headers which will become mandatory.
Request
{ "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
|
Required. If the agent is acting on behalf of the reporting company then the agent's name should be provided |
agentActingOnBehalfOfCompany
boolean
required
|
|
agentName
string
optional
|
Allow Unicode blocks Basic Latin (Space to Tilde), printable Latin-1 Supplement (¡ to ÿ), and all of Latin Extended-A and Latin Extended-B and IP Extensions (Ā to ʯ), all the Latin Extended Additional characters (Ḁ to ỿ), General Punctuation characters Hyphen to Horizontal Bar (‐ to ―), General Punctuation characters (‘ to ‟), Currency Symbol characters (₠ to ₿), Letterlike Symbols Å and K
Must conform to the regular expression |
reportingCompany
object
required
|
Required. The details of the reporting company |
companyName
string
required
|
Allow Unicode blocks Basic Latin (Space to Tilde), printable Latin-1 Supplement (¡ to ÿ), and all of Latin Extended-A and Latin Extended-B and IP Extensions (Ā to ʯ), all the Latin Extended Additional characters (Ḁ to ỿ), General Punctuation characters Hyphen to Horizontal Bar (‐ to ―), General Punctuation characters (‘ to ‟), Currency Symbol characters (₠ to ₿), Letterlike Symbols Å and K
Must conform to the regular expression |
ctutr
string
required
|
A UTR of 10 numeric characters
Must conform to the regular expression |
sameAsUltimateParent
boolean
required
|
Indicate whether the reporting company is the same as the ultimate parent |
authorisingCompanies
array
required
|
Required. The details of the authorising companies |
companyName
string
required
|
Allow Unicode blocks Basic Latin (Space to Tilde), printable Latin-1 Supplement (¡ to ÿ), and all of Latin Extended-A and Latin Extended-B and IP Extensions (Ā to ʯ), all the Latin Extended Additional characters (Ḁ to ỿ), General Punctuation characters Hyphen to Horizontal Bar (‐ to ―), General Punctuation characters (‘ to ‟), Currency Symbol characters (₠ to ₿), Letterlike Symbols Å and K
Must conform to the regular expression |
utr
string
required
|
A UTR of 10 numeric characters
Must conform to the regular expression |
consenting
boolean
optional
|
Has the company consented to this return |
isReportingCompanyAppointingItself
boolean
required
|
|
identityOfAppointingCompany
object
optional
|
Optional. The details of the appointing company |
companyName
string
required
|
Allow Unicode blocks Basic Latin (Space to Tilde), printable Latin-1 Supplement (¡ to ÿ), and all of Latin Extended-A and Latin Extended-B and IP Extensions (Ā to ʯ), all the Latin Extended Additional characters (Ḁ to ỿ), General Punctuation characters Hyphen to Horizontal Bar (‐ to ―), General Punctuation characters (‘ to ‟), Currency Symbol characters (₠ to ₿), Letterlike Symbols Å and K
Must conform to the regular expression |
countryOfIncorporation
string
optional
|
List of ISO 3166-1 2 Alpha Country Codes Limited to the following possible values: AD
AE
AF
AG
AI
AL
AM
AN
AO
AQ
AR
AS
AT
AU
AW
AX
AZ
BA
BB
BD
BE
BF
BG
BH
BI
BJ
BM
BN
BO
BQ
BR
BS
BT
BV
BW
BY
BZ
CA
CC
CD
CF
CG
CH
CI
CK
CL
CM
CN
CO
CR
CS
CU
CV
CW
CX
CY
CZ
DD
DE
DJ
DK
DM
DO
DZ
EC
EE
EG
EH
ER
ES
ET
EU
FI
FJ
FK
FM
FO
FR
GA
GD
GE
GF
GG
GH
GI
GL
GM
GN
GP
GQ
GR
GS
GT
GU
GW
GY
HK
HM
HN
HR
HT
HU
ID
IE
IL
IM
IN
IO
IQ
IR
IS
IT
JE
JM
JO
JP
KE
KG
KH
KI
KM
KN
KP
KR
KW
KY
KZ
LA
LB
LC
LI
LK
LR
LS
LT
LU
LV
LY
MA
MC
MD
ME
MF
MG
MH
MK
ML
MM
MN
MO
MP
MQ
MR
MS
MT
MU
MV
MW
MX
MY
MZ
NA
NC
NE
NF
NG
NI
NL
NO
NP
NR
NT
NU
NZ
OM
PA
PE
PF
PG
PH
PK
PL
PM
PN
PR
PS
PT
PW
PY
QA
RE
RO
RS
RU
RW
SA
SB
SC
SD
SE
SG
SH
SI
SJ
SK
SL
SM
SN
SO
SR
SS
ST
SV
SX
SY
SZ
TC
TD
TF
TG
TH
TJ
TK
TL
TM
TN
TO
TP
TR
TT
TV
TW
TZ
UA
UG
UK
UM
UN
US
UY
UZ
VA
VC
VE
VG
VI
VN
VU
WF
WS
YE
YT
ZA
ZM
ZW
|
ctutr
string
optional
|
A UTR of 10 numeric characters
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
|
Required. |
companyName
string
required
|
Allow Unicode blocks Basic Latin (Space to Tilde), printable Latin-1 Supplement (¡ to ÿ), and all of Latin Extended-A and Latin Extended-B and IP Extensions (Ā to ʯ), all the Latin Extended Additional characters (Ḁ to ỿ), General Punctuation characters Hyphen to Horizontal Bar (‐ to ―), General Punctuation characters (‘ to ‟), Currency Symbol characters (₠ to ₿), Letterlike Symbols Å and K
Must conform to the regular expression |
ctutr
string
optional
|
A UTR of 10 numeric characters
Must conform to the regular expression |
sautr
string
optional
|
A UTR of 10 numeric characters
Must conform to the regular expression |
knownAs
string
optional
|
Allow Unicode blocks Basic Latin (Space to Tilde), printable Latin-1 Supplement (¡ to ÿ), and all of Latin Extended-A and Latin Extended-B and IP Extensions (Ā to ʯ), all the Latin Extended Additional characters (Ḁ to ỿ), General Punctuation characters Hyphen to Horizontal Bar (‐ to ―), General Punctuation characters (‘ to ‟), Currency Symbol characters (₠ to ₿), Letterlike Symbols Å and K
Must conform to the regular expression |
countryOfIncorporation
string
optional
|
List of ISO 3166-1 2 Alpha Country Codes Limited to the following possible values: AD
AE
AF
AG
AI
AL
AM
AN
AO
AQ
AR
AS
AT
AU
AW
AX
AZ
BA
BB
BD
BE
BF
BG
BH
BI
BJ
BM
BN
BO
BQ
BR
BS
BT
BV
BW
BY
BZ
CA
CC
CD
CF
CG
CH
CI
CK
CL
CM
CN
CO
CR
CS
CU
CV
CW
CX
CY
CZ
DD
DE
DJ
DK
DM
DO
DZ
EC
EE
EG
EH
ER
ES
ET
EU
FI
FJ
FK
FM
FO
FR
GA
GD
GE
GF
GG
GH
GI
GL
GM
GN
GP
GQ
GR
GS
GT
GU
GW
GY
HK
HM
HN
HR
HT
HU
ID
IE
IL
IM
IN
IO
IQ
IR
IS
IT
JE
JM
JO
JP
KE
KG
KH
KI
KM
KN
KP
KR
KW
KY
KZ
LA
LB
LC
LI
LK
LR
LS
LT
LU
LV
LY
MA
MC
MD
ME
MF
MG
MH
MK
ML
MM
MN
MO
MP
MQ
MR
MS
MT
MU
MV
MW
MX
MY
MZ
NA
NC
NE
NF
NG
NI
NL
NO
NP
NR
NT
NU
NZ
OM
PA
PE
PF
PG
PH
PK
PL
PM
PN
PR
PS
PT
PW
PY
QA
RE
RO
RS
RU
RW
SA
SB
SC
SD
SE
SG
SH
SI
SJ
SK
SL
SM
SN
SO
SR
SS
ST
SV
SX
SY
SZ
TC
TD
TF
TG
TH
TJ
TK
TL
TM
TN
TO
TP
TR
TT
TV
TW
TZ
UA
UG
UK
UM
UN
US
UY
UZ
VA
VC
VE
VG
VI
VN
VU
WF
WS
YE
YT
ZA
ZM
ZW
|
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
|
Required. |
startDate
string
required
|
The start date of the accounting period
Must conform to the regular expression |
endDate
string
required
|
The end date of the accounting period
Must conform to the regular expression |
declaration
boolean
required
|
Declaration to confirm the listed companies constitute at least 50% of the eligible companies |
Response
HTTP status: 200 (OK)
{ "acknowledgementReference": "XAIRR00000012345678" }
Name | Description |
---|---|
acknowledgementReference
string
required
|
|
/organisations/interest-restriction/reporting-company/revoke
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 for other request headers which will become mandatory.
Request
{ "agentDetails": { "agentActingOnBehalfOfCompany": true, "agentName": "AAgent" }, "reportingCompany": { "companyName": "ACompany", "ctutr": "1123456789", "sameAsUltimateParent": false }, "isReportingCompanyRevokingItself":false, "companyMakingRevocation": { "companyName": "BCompany", "ctutr": "9999999999" }, "ultimateParent": { "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
|
Required. If the agent is acting on behalf of the reporting company then the agent's name should be provided |
agentActingOnBehalfOfCompany
boolean
required
|
|
agentName
string
optional
|
Allow Unicode blocks Basic Latin (Space to Tilde), printable Latin-1 Supplement (¡ to ÿ), and all of Latin Extended-A and Latin Extended-B and IP Extensions (Ā to ʯ), all the Latin Extended Additional characters (Ḁ to ỿ), General Punctuation characters Hyphen to Horizontal Bar (‐ to ―), General Punctuation characters (‘ to ‟), Currency Symbol characters (₠ to ₿), Letterlike Symbols Å and K
Must conform to the regular expression |
reportingCompany
object
required
|
Required. The details of the reporting company |
companyName
string
required
|
Allow Unicode blocks Basic Latin (Space to Tilde), printable Latin-1 Supplement (¡ to ÿ), and all of Latin Extended-A and Latin Extended-B and IP Extensions (Ā to ʯ), all the Latin Extended Additional characters (Ḁ to ỿ), General Punctuation characters Hyphen to Horizontal Bar (‐ to ―), General Punctuation characters (‘ to ‟), Currency Symbol characters (₠ to ₿), Letterlike Symbols Å and K
Must conform to the regular expression |
ctutr
string
required
|
A UTR of 10 numeric characters
Must conform to the regular expression |
sameAsUltimateParent
boolean
required
|
Indicate whether the reporting company is the same as the ultimate parent |
isReportingCompanyRevokingItself
boolean
required
|
|
companyMakingRevocation
object
optional
|
Optional. The details of the appointing company |
companyName
string
required
|
Allow Unicode blocks Basic Latin (Space to Tilde), printable Latin-1 Supplement (¡ to ÿ), and all of Latin Extended-A and Latin Extended-B and IP Extensions (Ā to ʯ), all the Latin Extended Additional characters (Ḁ to ỿ), General Punctuation characters Hyphen to Horizontal Bar (‐ to ―), General Punctuation characters (‘ to ‟), Currency Symbol characters (₠ to ₿), Letterlike Symbols Å and K
Must conform to the regular expression |
countryOfIncorporation
string
optional
|
List of ISO 3166-1 2 Alpha Country Codes Limited to the following possible values: AD
AE
AF
AG
AI
AL
AM
AN
AO
AQ
AR
AS
AT
AU
AW
AX
AZ
BA
BB
BD
BE
BF
BG
BH
BI
BJ
BM
BN
BO
BQ
BR
BS
BT
BV
BW
BY
BZ
CA
CC
CD
CF
CG
CH
CI
CK
CL
CM
CN
CO
CR
CS
CU
CV
CW
CX
CY
CZ
DD
DE
DJ
DK
DM
DO
DZ
EC
EE
EG
EH
ER
ES
ET
EU
FI
FJ
FK
FM
FO
FR
GA
GD
GE
GF
GG
GH
GI
GL
GM
GN
GP
GQ
GR
GS
GT
GU
GW
GY
HK
HM
HN
HR
HT
HU
ID
IE
IL
IM
IN
IO
IQ
IR
IS
IT
JE
JM
JO
JP
KE
KG
KH
KI
KM
KN
KP
KR
KW
KY
KZ
LA
LB
LC
LI
LK
LR
LS
LT
LU
LV
LY
MA
MC
MD
ME
MF
MG
MH
MK
ML
MM
MN
MO
MP
MQ
MR
MS
MT
MU
MV
MW
MX
MY
MZ
NA
NC
NE
NF
NG
NI
NL
NO
NP
NR
NT
NU
NZ
OM
PA
PE
PF
PG
PH
PK
PL
PM
PN
PR
PS
PT
PW
PY
QA
RE
RO
RS
RU
RW
SA
SB
SC
SD
SE
SG
SH
SI
SJ
SK
SL
SM
SN
SO
SR
SS
ST
SV
SX
SY
SZ
TC
TD
TF
TG
TH
TJ
TK
TL
TM
TN
TO
TP
TR
TT
TV
TW
TZ
UA
UG
UK
UM
UN
US
UY
UZ
VA
VC
VE
VG
VI
VN
VU
WF
WS
YE
YT
ZA
ZM
ZW
|
ctutr
string
optional
|
A UTR of 10 numeric characters
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 |
ultimateParent
object
optional
|
Details of the ultimate parent company |
isUk
boolean
required
|
Required. |
companyName
string
required
|
Allow Unicode blocks Basic Latin (Space to Tilde), printable Latin-1 Supplement (¡ to ÿ), and all of Latin Extended-A and Latin Extended-B and IP Extensions (Ā to ʯ), all the Latin Extended Additional characters (Ḁ to ỿ), General Punctuation characters Hyphen to Horizontal Bar (‐ to ―), General Punctuation characters (‘ to ‟), Currency Symbol characters (₠ to ₿), Letterlike Symbols Å and K
Must conform to the regular expression |
ctutr
string
optional
|
A UTR of 10 numeric characters
Must conform to the regular expression |
sautr
string
optional
|
A UTR of 10 numeric characters
Must conform to the regular expression |
knownAs
string
optional
|
Allow Unicode blocks Basic Latin (Space to Tilde), printable Latin-1 Supplement (¡ to ÿ), and all of Latin Extended-A and Latin Extended-B and IP Extensions (Ā to ʯ), all the Latin Extended Additional characters (Ḁ to ỿ), General Punctuation characters Hyphen to Horizontal Bar (‐ to ―), General Punctuation characters (‘ to ‟), Currency Symbol characters (₠ to ₿), Letterlike Symbols Å and K
Must conform to the regular expression |
countryOfIncorporation
string
optional
|
List of ISO 3166-1 2 Alpha Country Codes Limited to the following possible values: AD
AE
AF
AG
AI
AL
AM
AN
AO
AQ
AR
AS
AT
AU
AW
AX
AZ
BA
BB
BD
BE
BF
BG
BH
BI
BJ
BM
BN
BO
BQ
BR
BS
BT
BV
BW
BY
BZ
CA
CC
CD
CF
CG
CH
CI
CK
CL
CM
CN
CO
CR
CS
CU
CV
CW
CX
CY
CZ
DD
DE
DJ
DK
DM
DO
DZ
EC
EE
EG
EH
ER
ES
ET
EU
FI
FJ
FK
FM
FO
FR
GA
GD
GE
GF
GG
GH
GI
GL
GM
GN
GP
GQ
GR
GS
GT
GU
GW
GY
HK
HM
HN
HR
HT
HU
ID
IE
IL
IM
IN
IO
IQ
IR
IS
IT
JE
JM
JO
JP
KE
KG
KH
KI
KM
KN
KP
KR
KW
KY
KZ
LA
LB
LC
LI
LK
LR
LS
LT
LU
LV
LY
MA
MC
MD
ME
MF
MG
MH
MK
ML
MM
MN
MO
MP
MQ
MR
MS
MT
MU
MV
MW
MX
MY
MZ
NA
NC
NE
NF
NG
NI
NL
NO
NP
NR
NT
NU
NZ
OM
PA
PE
PF
PG
PH
PK
PL
PM
PN
PR
PS
PT
PW
PY
QA
RE
RO
RS
RU
RW
SA
SB
SC
SD
SE
SG
SH
SI
SJ
SK
SL
SM
SN
SO
SR
SS
ST
SV
SX
SY
SZ
TC
TD
TF
TG
TH
TJ
TK
TL
TM
TN
TO
TP
TR
TT
TV
TW
TZ
UA
UG
UK
UM
UN
US
UY
UZ
VA
VC
VE
VG
VI
VN
VU
WF
WS
YE
YT
ZA
ZM
ZW
|
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
|
Required. |
startDate
string
required
|
The start date of the accounting period
Must conform to the regular expression |
endDate
string
required
|
The end date of the accounting period
Must conform to the regular expression |
authorisingCompanies
array
required
|
Required. The details of the authorising companies |
companyName
string
required
|
Allow Unicode blocks Basic Latin (Space to Tilde), printable Latin-1 Supplement (¡ to ÿ), and all of Latin Extended-A and Latin Extended-B and IP Extensions (Ā to ʯ), all the Latin Extended Additional characters (Ḁ to ỿ), General Punctuation characters Hyphen to Horizontal Bar (‐ to ―), General Punctuation characters (‘ to ‟), Currency Symbol characters (₠ to ₿), Letterlike Symbols Å and K
Must conform to the regular expression |
utr
string
required
|
A UTR of 10 numeric characters
Must conform to the regular expression |
consenting
boolean
optional
|
Has the company consented to this return |
declaration
boolean
required
|
Declaration to confirm the listed companies constitute at least 50% of the eligible companies |
Response
HTTP status: 200 (OK)
{ "acknowledgementReference": "XAIRR00000012345678" }
Name | Description |
---|---|
acknowledgementReference
string
required
|
|
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
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 for other request headers which will become mandatory.
Request
{ "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" } }, "publicInfrastructure": true, "groupCompanyDetails": { "totalCompanies": 1, "accountingPeriod": { "startDate": "2019-02-18", "endDate": "2020-08-17" } }, "submissionType": "revised", "revisedReturnDetails": "some details", "groupLevelElections": { "groupRatio": { "isElected": true, "groupEBITDAChargeableGains": true, "groupRatioBlended": { "isElected": true, "investorGroups": [{ "groupName": "some investor group", "elections": ["groupRatioBlended", "groupEBITDA", "interestAllowanceAlternativeCalculation", "interestAllowanceNonConsolidatedInvestment", "interestAllowanceConsolidatedPartnership"] }, { "groupName": "some investor group", "elections": ["interestAllowanceAlternativeCalculation", "interestAllowanceNonConsolidatedInvestment", "interestAllowanceConsolidatedPartnership"] }] } }, "interestAllowanceAlternativeCalculation": true, "interestAllowanceNonConsolidatedInvestment": { "isElected": true, "nonConsolidatedInvestments": [{ "investmentName": "some Investment" }] }, "interestAllowanceConsolidatedPartnership": { "isElected": true, "consolidatedPartnerships": [{ "partnershipName": "some partner", "sautr": "1234567890" }] } }, "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 } }], "numberOfUkCompanies": 2, "aggregateNetTaxInterestExpense": 20, "aggregateTaxEBITDA": 5, "aggregateAllocatedRestrictions": 6, "aggregateAllocatedReactivations": 2, "angie": 1.11, "returnContainsEstimates": true, "groupSubjectToInterestRestrictions": false, "groupSubjectToInterestReactivation": true, "totalReactivation": 4, "totalRestrictions": 0, "groupLevelAmount": { "interestReactivationCap": 300, "interestAllowanceBroughtForward": 3, "interestAllowanceForPeriod": 4, "interestCapacityForPeriod": 5 }, "adjustedGroupInterest": { "qngie": 100, "groupEBITDA": 200, "groupRatio": 50 } }
Name | Description |
---|---|
appointedReportingCompany
boolean
required
|
|
agentDetails
object
required
|
Required. If the agent is acting on behalf of the reporting company then the agent's name should be provided |
agentActingOnBehalfOfCompany
boolean
required
|
|
agentName
string
optional
|
Allow Unicode blocks Basic Latin (Space to Tilde), printable Latin-1 Supplement (¡ to ÿ), and all of Latin Extended-A and Latin Extended-B and IP Extensions (Ā to ʯ), all the Latin Extended Additional characters (Ḁ to ỿ), General Punctuation characters Hyphen to Horizontal Bar (‐ to ―), General Punctuation characters (‘ to ‟), Currency Symbol characters (₠ to ₿), Letterlike Symbols Å and K
Must conform to the regular expression |
reportingCompany
object
required
|
Required. The details of the reporting company |
companyName
string
required
|
Allow Unicode blocks Basic Latin (Space to Tilde), printable Latin-1 Supplement (¡ to ÿ), and all of Latin Extended-A and Latin Extended-B and IP Extensions (Ā to ʯ), all the Latin Extended Additional characters (Ḁ to ỿ), General Punctuation characters Hyphen to Horizontal Bar (‐ to ―), General Punctuation characters (‘ to ‟), Currency Symbol characters (₠ to ₿), Letterlike Symbols Å and K
Must conform to the regular expression |
ctutr
string
required
|
A UTR of 10 numeric characters
Must conform to the regular expression |
sameAsUltimateParent
boolean
required
|
Indicate whether the reporting company is the same as the ultimate parent |
parentCompany
object
optional
|
Details of the parent company, this can be either an ultimate parent company or a deemed parent Limited to the following possible values:
|
publicInfrastructure
boolean
required
|
Indicate if any of the companies has made a qualifying infrastructure company (QIC) election |
groupCompanyDetails
object
required
|
Required. Details of the group company. |
totalCompanies
integer
required
|
Total number of companies within the worldwide group |
accountingPeriod
object
required
|
The worldwide groups accounting period |
startDate
string
required
|
The start date of the accounting period
Must conform to the regular expression |
endDate
string
required
|
The end date of the accounting period
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
|
Must conform to the regular expression |
angie
number
optional
|
Adjusted Net Group-Interest Expense (ANGIE) amount |
returnContainsEstimates
boolean
required
|
Indicator for whether the return contains figures which are estimated |
groupEstimateReason
string
optional
|
Must conform to the regular expression |
companiesEstimateReason
string
optional
|
Must conform to the regular expression |
groupSubjectToInterestRestrictions
boolean
required
|
Indicator for whether the group is subject to interest restrictions |
groupSubjectToInterestReactivation
boolean
required
|
Indicator for whether the group is subject to interest reactivations |
revisedReturnDifferences
string
optional
|
Must conform to the regular expression |
groupLevelElections
object
required
|
Details of the calculation elections made by the group |
groupRatio
object
required
|
Required. |
isElected
boolean
required
|
Indicate if the group has elected to use the group ratio calculation. If this is false then fixed ratio is used |
groupRatioBlended
object
optional
|
Optional. |
isElected
boolean
required
|
Indicate if the group has elected to use the group ratio blended calculation. Can only be elected if group ratio is elected |
investorGroups
array
optional
|
List the investor groups to which the group ratio blended election relates. Can only be supplied if group ratio blended is elected |
groupName
string
required
|
Allow Unicode blocks Basic Latin (Space to Tilde), printable Latin-1 Supplement (¡ to ÿ), and all of Latin Extended-A and Latin Extended-B and IP Extensions (Ā to ʯ), all the Latin Extended Additional characters (Ḁ to ỿ), General Punctuation characters Hyphen to Horizontal Bar (‐ to ―), General Punctuation characters (‘ to ‟), Currency Symbol characters (₠ to ₿), Letterlike Symbols Å and K
Must conform to the regular expression |
elections
array
optional
|
The elections made by this investor group Limited to the following possible values: groupRatioBlended
groupEBITDA
interestAllowanceAlternativeCalculation
interestAllowanceNonConsolidatedInvestment
interestAllowanceConsolidatedPartnership
|
groupEBITDAChargeableGains
boolean
optional
|
Indicate if the group has elected to use the group EBITDA chargeable gains election. Can only be elected if group ratio is elected |
interestAllowanceAlternativeCalculation
boolean
required
|
Indicate if the group has elected to use the Interest Allowance Alternative Calculation election |
interestAllowanceNonConsolidatedInvestment
object
required
|
Required. |
isElected
boolean
required
|
Indicate if the group has elected to use the Interest Allowance Non-Consolidated Investment election |
nonConsolidatedInvestments
array
optional
|
List the investors |
investmentName
string
required
|
Investment name
Must conform to the regular expression |
interestAllowanceConsolidatedPartnership
object
required
|
Required. |
isElected
boolean
required
|
Indicate if the group has elected to use the Interest Allowance Consolidated Partnership election |
consolidatedPartnerships
array
optional
|
List the partnerships |
partnershipName
string
required
|
Partnership name
Must conform to the regular expression |
sautr
string
optional
|
A UTR of 10 numeric characters
Must conform to the regular expression |
ukCompanies
array
required
|
Details of all the UK Companies which form part of the group |
companyName
string
required
|
Allow Unicode blocks Basic Latin (Space to Tilde), printable Latin-1 Supplement (¡ to ÿ), and all of Latin Extended-A and Latin Extended-B and IP Extensions (Ā to ʯ), all the Latin Extended Additional characters (Ḁ to ỿ), General Punctuation characters Hyphen to Horizontal Bar (‐ to ―), General Punctuation characters (‘ to ‟), Currency Symbol characters (₠ to ₿), Letterlike Symbols Å and K
Must conform to the regular expression |
utr
string
required
|
A UTR of 10 numeric characters
Must conform to the regular expression |
consenting
boolean
required
|
Indicate whether the reporting company is the same as the ultimate parent |
qicElection
boolean
required
|
Indicate whether the UK Company participated in a QIC election |
netTaxInterestExpense
number
required
|
The Net Tax Interest Expense amount |
netTaxInterestIncome
number
required
|
The Net Tax Interest Income amount |
allocatedRestrictions
object
optional
|
|
ap1EndDate
string
required
|
End date for the first Accounting Period apportioned dissallowances
Must conform to the regular expression |
ap2EndDate
string
optional
|
End date for the second Accounting Period apportioned dissallowances, if applicable. If supplied must be after ap1EndDate
Must conform to the regular expression |
ap3EndDate
string
optional
|
End date for the third Accounting Period apportioned dissallowances, if applicable. If supplied must be after ap2EndDate
Must conform to the regular expression |
disallowanceAp1
number
optional
|
Amount for the first Accounting Period apportioned dissallowances, must be supplied if ap1EndDate is supplied |
disallowanceAp2
number
optional
|
Amount for the second Accounting Period apportioned dissallowances, must be supplied if ap2EndDate is supplied |
disallowanceAp3
number
optional
|
Amount for the third Accounting Period apportioned dissallowances, must be supplied if ap3EndDate is supplied |
totalDisallowances
number
required
|
Total of disallowanceAp1, disallowanceAp2 and disallowanceAp3 |
allocatedReactivations
object
optional
|
|
currentPeriodReactivation
number
required
|
Amount being reactivated for current period of account |
taxEBITDA
number
required
|
Earnings Before Interest, Tax, Depreciation and Amortization (EBITDA) amount |
groupLevelAmount
object
required
|
Group level amounts |
interestReactivationCap
number
required
|
Interest Reactivation Cap |
interestAllowanceBroughtForward
number
required
|
Interest Allowance Brought Forward |
interestAllowanceForPeriod
number
required
|
Interest Allowance used for this period |
interestCapacityForPeriod
number
required
|
Interest Capacity for period to carry forward for future period |
adjustedGroupInterest
object
optional
|
Optional. |
qngie
number
required
|
Qualifying Net Group-Interest Expense (QNGIE) amount |
groupEBITDA
number
required
|
Earnings Before Interest, Tax, Depreciation and Amortization (EBITDA) amount |
groupRatio
number
required
|
Percentage figure, capped at 100%. Should be calculated as the QNGIE divided by the EBITDA, if negative result then set to 100% |
totalReactivation
number
required
|
Total of all allocated reactivations for each UK company |
totalRestrictions
number
required
|
Total of all allocated restrictions for each UK company |
Response
HTTP status: 200 (OK)
{ "acknowledgementReference": "XAIRR00000012345678" }
Name | Description |
---|---|
acknowledgementReference
string
required
|
|
/organisations/interest-restriction/return/abbreviated
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 for other request headers which will become mandatory.
Request
{ "appointedReportingCompany" : true, "agentDetails" : { "agentActingOnBehalfOfCompany" : true, "agentName" : "AAgent" }, "reportingCompany" : { "companyName" : "ACompany", "ctutr" : "1123456789", "sameAsUltimateParent" : false }, "parentCompany" : { "ultimateParent" : { "companyName" : "BCompany", "isUk": true, "ctutr" : "9999999999" } }, "publicInfrastructure" : true, "groupCompanyDetails" : { "totalCompanies" : 1, "accountingPeriod" : { "startDate" : "2018-07-27", "endDate" : "2020-01-26" } }, "submissionType" : "revised", "revisedReturnDetails" : "Reason for revision", "groupLevelElections" : { "groupRatio" : { "isElected" : true, "groupEBITDAChargeableGains" : true, "groupRatioBlended" : { "isElected" : true, "investorGroups" : [{ "groupName" : "AInvestor" }, { "groupName" : "BInvestor" }, { "groupName" : "CInvestor" }] } }, "interestAllowanceAlternativeCalculation" : true, "interestAllowanceNonConsolidatedInvestment" : { "isElected" : true, "nonConsolidatedInvestments" : [{ "investmentName" : "AInvestment" }, { "investmentName" : "BInvestment" }] }, "interestAllowanceConsolidatedPartnership" : { "isElected" : true, "consolidatedPartnerships" : [{ "partnershipName" : "APartnership", "sautr" : "1234567890" }, { "partnershipName" : "BPartnership", "sautr" : "1111111111" }] } }, "ukCompanies" : [{ "companyName" : "ACompany", "utr" : "1123456789", "consenting" : true, "qicElection" : false }, { "companyName" : "BCompany", "utr" : "9999999999", "consenting" : true, "qicElection" : false }, { "companyName" : "CCompany", "utr" : "2222222222", "consenting" : false, "qicElection" : true }] }
Name | Description |
---|---|
appointedReportingCompany
boolean
required
|
|
agentDetails
object
required
|
If an Agent is submitting this return on behalf of the reporting company and group details are supplied here |
agentActingOnBehalfOfCompany
boolean
required
|
|
agentName
string
optional
|
Allow Unicode blocks Basic Latin (Space to Tilde), printable Latin-1 Supplement (¡ to ÿ), and all of Latin Extended-A and Latin Extended-B and IP Extensions (Ā to ʯ), all the Latin Extended Additional characters (Ḁ to ỿ), General Punctuation characters Hyphen to Horizontal Bar (‐ to ―), General Punctuation characters (‘ to ‟), Currency Symbol characters (₠ to ₿), Letterlike Symbols Å and K
Must conform to the regular expression |
reportingCompany
object
required
|
Required. The details of the reporting company |
companyName
string
required
|
Allow Unicode blocks Basic Latin (Space to Tilde), printable Latin-1 Supplement (¡ to ÿ), and all of Latin Extended-A and Latin Extended-B and IP Extensions (Ā to ʯ), all the Latin Extended Additional characters (Ḁ to ỿ), General Punctuation characters Hyphen to Horizontal Bar (‐ to ―), General Punctuation characters (‘ to ‟), Currency Symbol characters (₠ to ₿), Letterlike Symbols Å and K
Must conform to the regular expression |
ctutr
string
required
|
A UTR of 10 numeric characters
Must conform to the regular expression |
sameAsUltimateParent
boolean
required
|
Indicate whether the reporting company is the same as the ultimate parent |
parentCompany
object
optional
|
Details of the parent company, this can be either an ultimate parent company or a deemed parent Limited to the following possible values:
|
publicInfrastructure
boolean
required
|
Indicate if any of the companies has made a qualifying infrastructure company (QIC) election |
groupCompanyDetails
object
required
|
Required. Details of the group company. |
totalCompanies
integer
required
|
Total number of companies within the worldwide group |
accountingPeriod
object
required
|
The worldwide groups accounting period |
startDate
string
required
|
The start date of the accounting period
Must conform to the regular expression |
endDate
string
required
|
The end date of the accounting period
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
|
Must conform to the regular expression |
angie
number
optional
|
Adjusted net group interest expense |
ukCompanies
array
required
|
Details of all the UK Companies which form part of the group |
companyName
string
required
|
Allow Unicode blocks Basic Latin (Space to Tilde), printable Latin-1 Supplement (¡ to ÿ), and all of Latin Extended-A and Latin Extended-B and IP Extensions (Ā to ʯ), all the Latin Extended Additional characters (Ḁ to ỿ), General Punctuation characters Hyphen to Horizontal Bar (‐ to ―), General Punctuation characters (‘ to ‟), Currency Symbol characters (₠ to ₿), Letterlike Symbols Å and K
Must conform to the regular expression |
utr
string
required
|
A UTR of 10 numeric characters
Must conform to the regular expression |
consenting
boolean
required
|
Indicate whether the reporting company is the same as the ultimate parent |
qicElection
boolean
required
|
Indicate whether the UK Company participated in a QIC election |
groupLevelElections
object
optional
|
Details of the calculation elections made by the group |
groupRatio
object
required
|
Required. |
isElected
boolean
required
|
Indicate if the group has elected to use the group ratio calculation. If this is false then fixed ratio is used |
groupRatioBlended
object
optional
|
Optional. |
isElected
boolean
required
|
Indicate if the group has elected to use the group ratio blended calculation. Can only be elected if group ratio is elected |
investorGroups
array
optional
|
List the investor groups to which the group ratio blended election relates. Can only be supplied if group ratio blended is elected |
groupName
string
required
|
Allow Unicode blocks Basic Latin (Space to Tilde), printable Latin-1 Supplement (¡ to ÿ), and all of Latin Extended-A and Latin Extended-B and IP Extensions (Ā to ʯ), all the Latin Extended Additional characters (Ḁ to ỿ), General Punctuation characters Hyphen to Horizontal Bar (‐ to ―), General Punctuation characters (‘ to ‟), Currency Symbol characters (₠ to ₿), Letterlike Symbols Å and K
Must conform to the regular expression |
elections
array
optional
|
The elections made by this investor group Limited to the following possible values: groupRatioBlended
groupEBITDA
interestAllowanceAlternativeCalculation
interestAllowanceNonConsolidatedInvestment
interestAllowanceConsolidatedPartnership
|
groupEBITDAChargeableGains
boolean
optional
|
Indicate if the group has elected to use the group EBITDA chargeable gains election. Can only be elected if group ratio is elected |
interestAllowanceAlternativeCalculation
boolean
required
|
Indicate if the group has elected to use the Interest Allowance Alternative Calculation election |
interestAllowanceNonConsolidatedInvestment
object
required
|
Required. |
isElected
boolean
required
|
Indicate if the group has elected to use the Interest Allowance Non-Consolidated Investment election |
nonConsolidatedInvestments
array
optional
|
List the investors |
investmentName
string
required
|
Investment name
Must conform to the regular expression |
interestAllowanceConsolidatedPartnership
object
required
|
Required. |
isElected
boolean
required
|
Indicate if the group has elected to use the Interest Allowance Consolidated Partnership election |
consolidatedPartnerships
array
optional
|
List the partnerships |
partnershipName
string
required
|
Partnership name
Must conform to the regular expression |
sautr
string
optional
|
A UTR of 10 numeric characters
Must conform to the regular expression |
Response
HTTP status: 200 (OK)
{ "acknowledgementReference": "XAIRR00000012345678" }
Name | Description |
---|---|
acknowledgementReference
string
required
|
|