GOV.UK
This version is in beta - expect some breaking changes.
Business Details (MTD) API
| 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 business details API allows a developer to:
- list all businesses
- retrieve additional information for a user's business details
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 business-details-api GitHub wiki.
Support
- Raise non-technical or platform-related issues with the Software Development Support Team (SDST).
- Raise technical issues on the business-details-api 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
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.
Authorisation
This endpoint is
user-restricted
and requires an Authorization header containing an OAuth 2.0 Bearer Token with the read:self-assessment scope.
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. For example: application/vnd.hmrc.1.0+json
|
|
Gov-Test-Scenario
optional
|
Only in sandbox environment. See Test Data table for all header values. For example: -
|
|
Authorization
required
|
An
OAuth 2.0 Bearer Token
with the read:self-assessment scope.
For example: Bearer bb7fed3fe10dd235a2ccda3d50fb
|
See also fraud prevention.
Response headers
| Name | Description |
|---|---|
|
X-CorrelationId
required
|
Unique ID for operation tracking For example: c75f40a6-a3df-4429-a697-471eeec46435
|
See also fraud prevention.
Response
HTTP status: 200 (OK)
{
"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.
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. |
/individuals/business/details/{nino}/{businessId}
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.
Authorisation
This endpoint is
user-restricted
and requires an Authorization header containing an OAuth 2.0 Bearer Token with the read:self-assessment scope.
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. For example: application/vnd.hmrc.1.0+json
|
|
Gov-Test-Scenario
optional
|
Only in sandbox environment. See Test Data table for all header values. For example: -
|
|
Authorization
required
|
An
OAuth 2.0 Bearer Token
with the read:self-assessment scope.
For example: Bearer bb7fed3fe10dd235a2ccda3d50fb
|
See also fraud prevention.
Response headers
| Name | Description |
|---|---|
|
X-CorrelationId
required
|
Unique ID for operation tracking For example: c75f40a6-a3df-4429-a697-471eeec46435
|
See also fraud prevention.
Response
HTTP status: 200 (OK)
{
"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.
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. |