Business Details (MTD) 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
This API allows a developer to list all businesses and retrieve additional information about the details of a user’s business.
For information on how to connect to this API see the Income Tax MTD end-to-end service guide.
Send fraud prevention data
HMRC monitors transactions to help protect your customers' confidential data from criminals and fraudsters.
Check the data you need to send. You can also use the Test API during initial development and as part of your quality assurance checks.
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.
Single errors will be returned in the following format:
{
"code": "FORMAT_FIELD_NAME",
"message": "The provided FieldName is invalid"
}
Where possible, multiple errors will be returned with INVALID_REQUEST
in the following format:
{
"code": "INVALID_REQUEST",
"message": "Invalid request",
"errors": [
{
"code": "RULE_FIELD_NAME",
"message": "The provided FieldName is not allowed"
},
{
"code": "FORMAT_FIELD_NAME",
"message": "The provided FieldName is invalid"
}
]
}
Changelog
You can find the changelog in the income-tax-mtd-changelog GitHub wiki.
Support
- Raise non-technical or platform-related issues with the Software Development Support Team (SDST).
- Raise technical issues on the income-tax-mtd-changelog GitHub page.
Testing
You can use the sandbox environment to test this API. You can use the Create Test User API or it's frontend service to create test users.
It may not be possible to test all scenarios in the sandbox. You can test some scenarios by passing the Gov-Test-Scenario header. Documentation for each endpoint includes a Test data section, which explains the scenarios that you can simulate using the Gov-Test-Scenario header.
If you have a specific testing need that is not supported in the sandbox, contact our support team.
Some APIs may be marked [test only]. This means that they are not available for use in production and may change.
Endpoints
/individuals/business/details/{nino}/list
List All Businesses
GET
This endpoint allows a developer to retrieve all details of a user's business income sources. The unique account reference (National Insurance number) must be provided.
Path parameters
Name | Description |
---|---|
nino
string
required
|
National Insurance number, in the format AA999999A.
For example: |
Request headers
Name | Description |
---|---|
Accept
required
|
Specifies the response format and the version of the API to be used. application/vnd.hmrc.1.0+json
|
Gov-Test-Scenario
optional
|
Only in sandbox environment. See Test Data table for all header values. -
|
Authorization
required
|
An
OAuth 2.0 Bearer Token
with the read:self-assessment scope.
For example: Bearer bb7fed3fe10dd235a2ccda3d50fb
|
See also fraud prevention.
Responses
HTTP status 200 (OK)
Response headers
Name | Description |
---|---|
X-CorrelationId
required
|
Unique ID for operation tracking c75f40a6-a3df-4429-a697-471eeec46435
|
See also fraud prevention.
Example response
{ "listOfBusinesses":[ { "typeOfBusiness": "self-employment", "businessId": "XAIS12345678910", "tradingName": "RCDTS", "links": [ { "href": "/individuals/business/details/NZ345734C/XAIS12345678910", "method": "GET", "rel": "retrieve-business-details" } ] }, { "typeOfBusiness": "foreign-property", "businessId": "XAIS23456789101", "links": [ { "href": "/individuals/business/details/NZ345734C/XAIS23456789101", "method": "GET", "rel": "retrieve-business-details" } ] } ], "links": [ { "href": "/individuals/business/details/NZ345734C/list", "method": "GET", "rel": "self" } ] }
Name | Description |
---|---|
listOfBusinesses
array
required
|
An array containing the details of all the business income sources held against the specified National insurance number. |
typeOfBusiness
string
required
|
The type of business income source. Limited to the following possible values: self-employment
uk-property
foreign-property
property-unspecified
|
businessId
string
required
|
A unique identifier for the business income source. Previously known as selfEmploymentId.
Must conform to the regular expression
For example: |
tradingName
string
optional
|
The trading name of the business.
For example: |
links
array
optional
|
A list of endpoint links that indicate possible actions related to the current resource. |
href
string
required
|
The relative url of the endpoint.
For example: |
rel
string
required
|
A label for the endpoint, which describes how it is related to the current resource The rel will be `self` where the action is retrieval of the same resource. Limited to the following possible values: retrieve-business-details
|
method
string
required
|
The HTTP method type for the endpoint. Limited to the following possible values: GET
|
links
array
optional
|
A list of endpoint links that indicate possible actions related to the current resource. |
href
string
required
|
The relative url of the endpoint.
For example: |
rel
string
required
|
A label for the endpoint, which describes how it is related to the current resource The rel will be self where the action is retrieval of the same resource. Limited to the following possible values: self
|
method
string
required
|
The HTTP method type for the endpoint. Limited to the following possible values: GET
|
Error scenarios
Scenario | HTTP status | Code |
---|---|---|
The format of the supplied NINO field is not valid. |
400 (Bad Request) |
FORMAT_NINO |
The client or agent is not authorised. This is because: the client is not subscribed to MTD, the agent is not subscribed to Agent Services or the client has not authorised the agent to act on their behalf. |
403 (Forbidden) |
CLIENT_OR_AGENT_NOT_AUTHORISED |
The matching resource is not found. |
404 (Not Found) |
MATCHING_RESOURCE_NOT_FOUND |
For error scenarios that are common across all APIs, and for error formats, see our reference guide.
Test data
Scenario simulations using Gov-Test-Scenario headers is only available in the sandbox environment.
Header Value (Gov-Test-Scenario) | Scenario |
---|---|
N/A - DEFAULT |
Simulate a successful response with a self-employment business. |
PROPERTY |
Simulate a successful response with a uk-property business. |
FOREIGN_PROPERTY |
Simulate a successful response with a foreign-property business. |
BUSINESS_AND_PROPERTY |
Simulate a successful response with a self-employment, uk-property and foreign-property business. |
UNSPECIFIED |
Simulate a successful response with a property-unspecified business. |
NOT_FOUND |
Simulate a scenario where no data is found. |
Close Section
/individuals/business/details/{nino}/{businessId}
Retrieve business details
GET
This endpoint allows a developer to retrieve additional information for one of a user's business income source. The unique account reference (National Insurance number) must be provided as well as the unique business identifier.
Path parameters
Name | Description |
---|---|
nino
string
required
|
National Insurance number, in the format AA999999A.
For example: |
businessId
string
required
|
A unique identifier for the business income source. It must conform to the following regular expression:
For example: |
Request headers
Name | Description |
---|---|
Accept
required
|
Specifies the response format and the version of the API to be used. application/vnd.hmrc.1.0+json
|
Gov-Test-Scenario
optional
|
Only in sandbox environment. See Test Data table for all header values. -
|
Authorization
required
|
An
OAuth 2.0 Bearer Token
with the read:self-assessment scope.
For example: Bearer bb7fed3fe10dd235a2ccda3d50fb
|
See also fraud prevention.
Responses
HTTP status 200 (OK)
Response headers
Name | Description |
---|---|
X-CorrelationId
required
|
Unique ID for operation tracking c75f40a6-a3df-4429-a697-471eeec46435
|
See also fraud prevention.
Example response
{ "businessId": "XAIS12345678910", "typeOfBusiness": "self-employment", "tradingName": "ABC Ltd.", "accountingPeriods": [ { "start": "2018-04-06", "end": "2019-04-05" } ], "accountingType": "ACCRUALS", "commencementDate": "2016-09-24", "cessationDate": "2020-03-24", "businessAddressLineOne": "1 Acme Rd.", "businessAddressLineTwo": "London", "businessAddressLineThree": "Greater London", "businessAddressLineFour": "United Kingdom", "businessAddressPostcode": "M1 1AG", "businessAddressCountryCode": "GB", "links": [ { "href": "/individuals/business/details/ET009363D/XAIS12345678910", "method": "GET", "rel": "self" } ] }
Name | Description |
---|---|
businessId
string
required
|
A unique identifier for the business income source. Previously known as selfEmploymentId.
Must conform to the regular expression
For example: |
typeOfBusiness
string
required
|
The type of business income source. Limited to the following possible values: self-employment
uk-property
foreign-property
property-unspecified
|
tradingName
string
optional
|
The trading name of the business.
For example: |
accountingPeriods
array
required
|
A list of the accounting periods for the business. |
start
string
required
|
Date your books or accounts start - the beginning of your accounting period.
For example: |
end
string
required
|
Date your books or accounts are made up to - the end of your accounting period.
For example: |
accountingType
string
optional
|
CASH if you used the cash basis, money actually received and paid out, to calculate your income and expenses. Otherwise ACCRUALS. Limited to the following possible values: CASH
ACCRUALS
|
commencementDate
string
optional
|
Business start date, must be in the past.
For example: |
cessationDate
string
optional
|
Business cessation date.
For example: |
businessAddressLineOne
string
optional
|
First line of the business address.
For example: |
businessAddressLineTwo
string
optional
|
Second line of the business address.
For example: |
businessAddressLineThree
string
optional
|
Third line of the business address.
For example: |
businessAddressLineFour
string
optional
|
Fourth line of the business address.
For example: |
businessAddressPostcode
string
optional
|
Business code.
For example: |
businessAddressCountryCode
string
optional
|
The two letter code for a country must adhere to ISO 3166.
For example: |
links
array
optional
|
A list of endpoint links that indicate possible actions related to the current resource. |
href
string
required
|
The relative url of the endpoint.
For example: |
rel
string
required
|
A label for the endpoint, which describes how it is related to the current resource The rel will be self where the action is retrieval of the same resource. Limited to the following possible values: self
|
method
string
required
|
The HTTP method type for the endpoint. Limited to the following possible values: GET
|
Error scenarios
Scenario | HTTP status | Code |
---|---|---|
The format of the supplied NINO field is not valid. |
400 (Bad Request) |
FORMAT_NINO |
The format of the supplied Business ID field is not valid. |
400 (Bad Request) |
FORMAT_BUSINESS_ID |
The client or agent is not authorised. This is because: the client is not subscribed to MTD, the agent is not subscribed to Agent Services or the client has not authorised the agent to act on their behalf. |
403 (Forbidden) |
CLIENT_OR_AGENT_NOT_AUTHORISED |
No business found for given NINO with given Business ID. |
404 (Not Found) |
NO_BUSINESS_FOUND |
The matching resource is not found. |
404 (Not Found) |
MATCHING_RESOURCE_NOT_FOUND |
For error scenarios that are common across all APIs, and for error formats, see our reference guide.
Test data
Scenario simulations using Gov-Test-Scenario headers is only available in the sandbox environment.
Header Value (Gov-Test-Scenario) | Scenario |
---|---|
N/A - DEFAULT |
Simulate a successful response with a self-employment business. Use the following businessId for this scenario:
|
PROPERTY |
Simulate a successful response with a uk-property business. Use the following businessId for this scenario:
|
FOREIGN_PROPERTY |
Simulate a successful response with a foreign-property business. Use the following businessId for this scenario:
|
UNSPECIFIED |
Simulate a successful response with a property-unspecified business. Use the following businessId for this scenario:
|
NOT_FOUND |
Simulate a scenario where no data is found. |
Close Section