Sign in

v1

latestOpenAPI 3.0.32026-07-13105113.9 KB

Retrieve Business Details

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.

Test data

Scenario simulations using <code>Gov-Test-Scenario</code> headers is only available in the sandbox environment.

Header Value (Gov-Test-Scenario)Scenario
N/A - DEFAULTSimulate a successful response with a self-employment business. <br/> Use the following businessId for this scenario: <br/> - XBIS12345678901
PROPERTYSimulate a successful response with a uk-property business. <br/> Use the following businessId for this scenario: <br/> - XPIS12345678901
FOREIGN_PROPERTYSimulate a successful response with a foreign-property business. <br/> Use the following businessId for this scenario: <br/> - XFIS12345678901
UNSPECIFIEDSimulate a successful response with a property-unspecified business. <br/> Use the following businessId for this scenario: <br/> - XAIS12345678901
NOT_FOUNDSimulate a scenario where no data is found.
DYNAMICReturns a dynamic response where the type of response will change corresponding to the businessId provided in the request: <br/> - For a response with a self-employment business, use businessId: <br/> -- XBIS12345678901 <br/> - For a response with a uk-property business, use businessId: <br/> -- XPIS12345678901 <br/> - For a response with a foreign-property business, use businessId: <br/> -- XFIS12345678901 <br/> - For a response with a property-unspecified business, use businessId: <br/> -- XAIS12345678901
STATEFULPerforms a stateful retrieve.
get/individuals/business/details/{nino}/{businessId}

Path parameters

ninostring required
Example:TC663795B

National Insurance number, in the format AA999999A

businessIdstring required
Example:XAIS12345678910

A unique identifier for the business income source. It must conform to the following regex: ^X[A-Z0-9]{1}IS[0-9]{11}$

Headers

Accept'application/vnd.hmrc.2.0+json' required

Specifies the response format and the version of the API to be used.

Authorizationstring required
Example:Bearer bb7fed3fe10dd235a2ccda3d50fb

An OAuth 2.0 Bearer Token with the read:self-assessment scope.

Gov-Test-Scenariostring
Example:-

Only in sandbox environment. See Test Data table for all header values.

Response

Success

businessIdstring required

A unique identifier for the business income source. Previously known as selfEmploymentId.

typeOfBusiness'self-employment' | 'uk-property' | 'foreign-property' | 'property-unspecified' required

The type of business income source.

tradingNamestring

The trading name of the business.

yearOfMigrationstring yyyy

Year of migration.

firstAccountingPeriodStartDatestring yyyy-MM-DD

The first accounting period start date.

Note: <b>Accounting period start and end dates should not be displayed to users of your software.</b>

firstAccountingPeriodEndDatestring yyyy-MM-DD

The first accounting period end date.

Note: <b>Accounting period start and end dates should not be displayed to users of your software.</b>

commencementDatestring

Business start date, must be in the past.

cessationDatestring

Business cessation date.

businessAddressLineOnestring

First line of the business address.

businessAddressLineTwostring

Second line of the business address.

businessAddressLineThreestring

Third line of the business address.

businessAddressLineFourstring

Fourth line of the business address.

businessAddressPostcodestring

Business code.

businessAddressCountryCodestring

ISO country code for the business if it is in a non-GB country. The two-letter code for a country must adhere to ISO 3166.

Example response

{
  "businessId": "XAIS12345678910",
  "tradingName": "ABC Ltd.",
  "yearOfMigration": "2022",
  "firstAccountingPeriodStartDate": "2019-09-30",
  "firstAccountingPeriodEndDate": "2020-02-29",
  "latencyDetails": {
    "latencyEndDate": "2020-02-27",
    "taxYear1": "2018-19",
    "latencyIndicator1": "A",
    "taxYear2": "2019-20",
    "latencyIndicator2": "A"
  },
  "quarterlyTypeChoice": {
    "quarterlyPeriodType": "standard",
    "taxYearOfChoice": "2023-24"
  },
  "accountingPeriods": [
    {
      "start": "2018-04-06",
      "end": "2019-04-05"
    }
  ],
  "commencementDate": "2016-09-24",
  "cessationDate": "2020-03-24",
  "businessAddressLineOne": "1 ABC Rd.",
  "businessAddressLineTwo": "London",
  "businessAddressLineThree": "Greater London",
  "businessAddressLineFour": "United Kingdom",
  "businessAddressPostcode": "M1 1AG",
  "businessAddressCountryCode": "FR"
}