### Example Request for Advice Stub

Source: https://developer.service.hmrc.gov.uk/guides/trader-goods-profile-service-guide/documentation/API-reference.html

This is an example JSON payload for the POST /advice endpoint. It includes actor ID, requestor name, and email.

```json
{
  "actorId": "GB987654321098",
  "requestorName": "Mr. Phil Edwards",
  "requestorEmail": "Phil.Edwards@gmail.com"
}
```

--------------------------------

### Push Notification Example

Source: https://developer.service.hmrc.gov.uk/api-documentation/docs/api/service/push-pull-notifications-api/1.0

This is an example of the JSON payload sent via POST request to the configured Push/Callback URL when a notification is created.

```APIDOC
## Push Notification Payload

### Description
This is an example of the JSON payload sent via POST request to the configured Push/Callback URL when a notification is created.

### Request Body
- **notificationId** (string) - Description of the notification ID.
- **boxId** (string) - Description of the box ID.
- **messageContentType** (string) - The content type of the message.
- **message** (string) - The notification message content, potentially JSON stringified.
- **status** (string) - The current status of the notification (e.g., PENDING, ACKNOWLEDGED, FAILED).
- **createdDateTime** (string) - The date and time when the notification was created.

### Request Example
```json
{
    "notificationId": "1ed5f407-8096-40d1-87ef-9a2a103eeb85",
    "boxId": "50dca3fc-c37c-4f03-b719-63571333624c",
    "messageContentType": "application/json",
    "message": "{\"key\":\"value\"}",
    "status": "PENDING",
    "createdDateTime": "2020-06-01T10:20:23.160+0000"
}
```
```

--------------------------------

### Retrieve Obligations and Submissions

Source: https://developer.service.hmrc.gov.uk/guides/pillar2-service-guide/documentation/btn.html

Check an organisation's requirements by sending a GET request to retrieve obligations and submissions. This example sets the status to 'Open' for 'UKTR' and 'GIR' obligation types.

```APIDOC
## Retrieve Obligations and Submissions

### Description
Retrieves the current obligations and submission status for an organization within a specified date range.

### Method
GET

### Endpoint
/organisations/pillar-two/obligations-and-submissions

### Parameters
#### Query Parameters
- **fromDate** (string) - Required - The start date for the period to retrieve obligations for.
- **toDate** (string) - Required - The end date for the period to retrieve obligations for.

### Request Example
```bash
curl --request GET \
  --url 'https://test-api.service.hmrc.gov.uk/organisations/pillar-two/obligations-and-submissions?fromDate=2024-01-01&toDate=2024-12-31' \
  --header 'Authorization: Bearer YOUR_BEARER_TOKEN' \
  --header 'X-Pillar2-Id: YOUR_PILLAR2_ID' \
  --header 'Accept: application/vnd.hmrc.1.0+json'
```

### Response
#### Success Response (200)
- **processingDate** (string) - The date and time the processing occurred.
- **accountingPeriodDetails** (array) - Details of accounting periods.
  - **startDate** (string) - The start date of the accounting period.
  - **endDate** (string) - The end date of the accounting period.
  - **dueDate** (string) - The due date for the accounting period.
  - **underEnquiry** (boolean) - Indicates if the period is under enquiry.
  - **obligations** (array) - Details of obligations within the period.
    - **obligationType** (string) - The type of obligation (e.g., UKTR, GIR).
    - **status** (string) - The current status of the obligation (e.g., Open, Fulfilled).
    - **canAmend** (boolean) - Indicates if the obligation can be amended.
    - **submissions** (array) - List of submissions for the obligation.
      - **submissionType** (string) - The type of submission (e.g., BTN, UKTR_CREATE).
      - **receivedDate** (string) - The date the submission was received.

#### Response Example
```json
{
  "processingDate": "2025-07-09T09:17:42Z",
  "accountingPeriodDetails": [
    {
      "startDate": "2024-01-01",
      "endDate": "2024-12-31",
      "dueDate": "2025-07-01",
      "underEnquiry": false,
      "obligations": [
        {
          "obligationType": "UKTR",
          "status": "Open",
          "canAmend": true,
          "submissions": []
        },
        {
          "obligationType": "GIR",
          "status": "Open",
          "canAmend": true,
          "submissions": []
        }
      ]
    }
  ]
}
```
```

--------------------------------

### Error Response Example (404 Not Found)

Source: https://developer.service.hmrc.gov.uk/guides/emcs-api-testing-guide/documentation/test-scenarios.html

Example structure of a 404 Not Found error response.

```APIDOC
## Error Response Example (404 Not Found)

A 404 Not Found error response will take the form of

```json
{
  "dateTime": "2021-12-17T09:30:47Z",
  "message": "Received error response from server",
  "debugMessage": "Connection refused; nested exception is java.net.ConnectException: Connection refused",
  "correlationId": "3e8dae97-b586-4cef-8511-68ac12da9028"
}
```
```

--------------------------------

### Successful Authorisation Redirect Example

Source: https://developer.service.hmrc.gov.uk/api-documentation/docs/authorisation/user-restricted-endpoints

This is an example of a redirect URL issued after a successful user authorisation. It includes an authorisation code and the state parameter.

```url
https://www.example.com/auth-redirect?code=6589c5d9fc4b9872b1f9013583c2f39d&state=30de877c-ee2f-15db-8314-0800200c9a66
```

--------------------------------

### Error Response Example (503 Service Unavailable)

Source: https://developer.service.hmrc.gov.uk/guides/emcs-api-testing-guide/documentation/test-scenarios.html

Example structure of a 503 Service Unavailable error response.

```APIDOC
## Error Response Example (503 Service Unavailable)

A 503 Service Unavailable error response will take the form of

```json
{
  "dateTime": "2021-12-17T09:30:47Z",
  "message": "CIRCUIT_BREAKER - 815_CB is OPEN",
  "debugMessage": "CircuitBreaker '815_CB' is OPEN and does not permit further calls",
  "correlationId": "3e8dae97-b586-4cef-8511-68ac12da9028"
}
```
```

--------------------------------

### Example Open Access Endpoint

Source: https://developer.service.hmrc.gov.uk/api-documentation/docs/authorisation/open-access-endpoints

This example demonstrates how to access an open access endpoint using curl. These endpoints are unrestricted and service general data held by HMRC.

```APIDOC
## GET /hello/world

### Description
This is an example of an open access endpoint that returns general data. It does not require authentication and can be accessed by anyone.

### Method
GET

### Endpoint
https://test-api.service.hmrc.gov.uk/hello/world

### Headers
- **Accept**: application/vnd.hmrc.1.0+json
```

--------------------------------

### Valid Redirect URI Examples

Source: https://developer.service.hmrc.gov.uk/api-documentation/docs/reference-guide

These examples demonstrate valid redirect URIs for application registration and authorization requests. Ensure your redirect URIs are percent-encoded when used in authorization calls.

```text
https://www.example.com/auth-redirect
```

```text
https://www.example.com
```

```text
https%3A%2F%2Fwww.example.com%2Fauth-redirect
```

```text
https://www.example.com:8080/auth-redirect
```

```text
https://www.example.com:8080/auth-redirect?some_parameter=some_value
```

```text
http://localhost:8080
```

```text
urn:ietf:wg:oauth:2.0:oob
```

```text
urn:ietf:wg:oauth:2.0:oob:auto
```

--------------------------------

### Example Request for Withdraw Advice Stub

Source: https://developer.service.hmrc.gov.uk/guides/trader-goods-profile-service-guide/documentation/API-reference.html

This is an example JSON payload for the PUT /advice endpoint when withdrawing an advice request. It includes the reason for withdrawal.

```json
{
    "withdrawReason": "No longer needed"
}
```

--------------------------------

### Unsuccessful Authorisation Redirect Example

Source: https://developer.service.hmrc.gov.uk/api-documentation/docs/authorisation/user-restricted-endpoints

This is an example of a redirect URL issued after an unsuccessful user authorisation. It includes error details and the state parameter.

```url
https://www.example.com/auth-redirect?error=access_denied&error_description=user+denied+the+authorization&error_code=USER_DENIED_AUTHORIZATION&state=30de877c-ee2f-15db-8314-0800200c9a66
```

--------------------------------

### Success Response for Get Excise Movements

Source: https://developer.service.hmrc.gov.uk/guides/emcs-api-testing-guide-4-2/documentation/test-scenarios.html

Example of a successful response when retrieving multiple excise movements.

```json
[
  {
    "movementId" : "cfdb20c7-d0b0-4b8b-a071-737d68dede5e",
    "consignorId": "GBWK002281023",
    "localReferenceNumber": "LRNQA20230909022221",
    "consigneeId": "GBWKQOZ8OVLYR",
    "administrativeReferenceCode": "35WE3B5EDSYSZ86STVKH8",
    "lastUpdated": "2024-01-17T12:25:29.540Z"
  },
  {
    "movementId" : "0055d33f-579e-4560-a3ee-03482d8d9dad",
    "consignorId": "GBWK002281023",
    "consigneeId": "GBWKQOZ8OVLYQ",
    "localReferenceNumber": "LRNQA20230909022224",
    "lastUpdated": "2024-01-17T15:25:29.540Z"
  }
]
```

--------------------------------

### Say hello world

Source: https://developer.service.hmrc.gov.uk/api-documentation/docs/api/service/api-example-microservice/1.0

An example of an unrestricted endpoint that returns a simple greeting.

```APIDOC
## GET /hello/world

### Description
This endpoint returns a simple greeting and is an example of an unrestricted resource.

### Method
GET

### Endpoint
/hello/world

### Response
#### Success Response (200)
- **message** (string) - A greeting message.
```

--------------------------------

### Success Response for Get Single Excise Movement

Source: https://developer.service.hmrc.gov.uk/guides/emcs-api-testing-guide-4-2/documentation/test-scenarios.html

Example of a successful response when retrieving a single excise movement by its ID.

```json
{
  "movementId" : "cfdb20c7-d0b0-4b8b-a071-737d68dede5e",
  "consignorId": "GBWK002281023",
  "localReferenceNumber": "LRNQA20230909022221",
  "consigneeId": "GBWKQOZ8OVLYR",
  "administrativeReferenceCode": "35WE3B5EDSYSZ86STVKH8",
  "lastUpdated": "2024-01-17T15:25:29.540Z"
}
```

--------------------------------

### Access Open Hello World Endpoint

Source: https://developer.service.hmrc.gov.uk/api-documentation/docs/tutorials

Use this snippet to make a GET request to an unrestricted endpoint. Ensure the Accept header is set to application/vnd.hmrc.1.0+json.

```java
// construct the GET request for our Hello World endpoint
HttpClient client = HttpClientBuilder.create().build();
HttpGet request = new HttpGet("https://test-api.service.hmrc.gov.uk/hello/world");
request.addHeader("Accept", "application/vnd.hmrc.1.0+json");

// execute the request
HttpResponse response = client.execute(request);

// extract the HTTP status code and response body
int statusCode = response.getStatusLine().getStatusCode();
String responseBody = EntityUtils.toString(response.getEntity());

```

--------------------------------

### Initiate File Upload Request (With Optional Elements)

Source: https://developer.service.hmrc.gov.uk/guides/customs-declarations-end-to-end-service-guide/documentation/uploading-supporting-documents.html

This XML example demonstrates initiating a file upload request including optional SuccessRedirect and ErrorRedirect elements. These are useful for UI applications to handle upload outcomes.

```xml
<hmrc:FileUploadRequest xmlns:hmrc="hmrc:fileupload">
          <hmrc:DeclarationID>23GBXXXXXXXXXXXXXX</hmrc:DeclarationID>
          <hmrc:FileGroupSize>1</hmrc:FileGroupSize>
          <hmrc:Files>
            <hmrc:File>
              <hmrc:FileSequenceNo>1</hmrc:FileSequenceNo>
              <hmrc:DocumentType>Licence</hmrc:DocumentType>
              <hmrc:SuccessRedirect>https://success-redirect.com</hmrc:SuccessRedirect>
              <hmrc:ErrorRedirect>https://error-redirect.com</hmrc:ErrorRedirect>
            </hmrc:File>
          </hmrc:Files>
        </hmrc:FileUploadRequest>
```

--------------------------------

### Example VAT Obligations Response

Source: https://developer.service.hmrc.gov.uk/guides/vat-mtd-end-to-end-service-guide/documentation/obligations.html

This JSON structure represents the response from the Retrieve VAT obligations endpoint, showing open obligations with their start, end, due dates, status, and period key.

```json
{
  "obligations":[
    {
      "start":"2018-11-01",
      "end":"2019-01-31",
      "due":"2019-03-07",
      "status":"O",
      "periodKey":"18A4"
    },
    {
      "start":"2018-08-01",
      "end":"2018-10-31",
      "due":"2018-12-07",
      "status":"O",
      "periodKey":"18A3"
    }
  ]
}
```

--------------------------------

### Example Response: Initial Obligations

Source: https://developer.service.hmrc.gov.uk/guides/pillar2-service-guide/documentation/btn.html

This JSON response shows the initial state of obligations, where both 'UKTR' and 'GIR' obligation types have a status of 'Open'.

```json
{
  "processingDate": "2025-07-09T09:17:42Z",
  "accountingPeriodDetails": [
    {
      "startDate": "2024-01-01",
      "endDate": "2024-12-31",
      "dueDate": "2025-07-01",
      "underEnquiry": false,
      "obligations": [
        {
          "obligationType": "UKTR",
          "status": "Open",
          "canAmend": true,
          "submissions": []
        },
        {
          "obligationType": "GIR",
          "status": "Open",
          "canAmend": true,
          "submissions": []
        }
      ]
    }
  ]
}
```

--------------------------------

### Retrieve Obligations and Submissions Response Example

Source: https://developer.service.hmrc.gov.uk/guides/pillar2-service-guide/documentation/obligations-submissions.html

This JSON response shows a fulfilled 'UKTR' obligation and an open 'GIR' obligation for the specified accounting period. It includes details like start and end dates, due dates, and submission information.

```json
{
  "processingDate": "2025-03-17T09:26:17Z",
  "accountingPeriodDetails": [
    {
      "startDate": "2024-01-01",
      "endDate": "2024-12-31",
      "dueDate": "2025-01-31",
      "underEnquiry": false,
      "obligations": [
        {
          "obligationType": "UKTR",
          "status": "Fulfilled",
          "canAmend": true,
          "submissions": [
            {
              "submissionType": "UKTR_CREATE",
              "receivedDate": "2025-03-17T09:26:17Z"
            }
          ]
        },
        {
          "obligationType": "GIR",
          "status": "Open",
          "canAmend": true,
          "submissions": []
        }
      ]
    }
  ]
}
```

--------------------------------

### Calculate Scottish Capital Gains Tax

Source: https://developer.service.hmrc.gov.uk/guides/tax-logic-service-guide/documentation/tax-calculation.html

This code calculates the tax on capital gains by first adjusting available tax bands and then allocating the gains income across the starting rate, PSA, basic, higher, and additional rate bands. It concludes by calculating the tax for each band and summing them to get the total gains tax.

```javascript
// Adjust the bands
remainingPSA = savingsPSALimit - savingsPSA
remainingSSR = savingsStartingRateLimit - savingsStartingRateAllocatedIncome
remainingGainsTaxableIncome = totalGainsTaxableIncome - remainingPSA
remainingBasicRateBand = max(remainingBasicRateBand - remainingPSA - remainingSSR, 0) // Ensure non-negative value

// Allocate gains income
if remainingGainsTaxableIncome <= remainingSSR then
gainsStartingRateAllocatedIncome = remainingGainsTaxableIncome
gainsBasicRateAllocatedIncome = 0
gainsHigherRateAllocatedIncome = 0
gainsAdditionalRateAllocatedIncome = 0
else if remainingGainsTaxableIncome <= remainingBasicRateBand then
gainsStartingRateAllocatedIncome = remainingSSR
gainsBasicRateAllocatedIncome = remainingGainsTaxableIncome
gainsHigherRateAllocatedIncome = 0
gainsAdditionalRateAllocatedIncome = 0
else if remainingGainsTaxableIncome <= (remainingBasicRateBand + remainingHigherRateBand) then
gainsStartingRateAllocatedIncome = remainingSSR
gainsBasicRateAllocatedIncome = remainingBasicRateBand
gainsHigherRateAllocatedIncome = remainingGainsTaxableIncome - remainingBasicRateBand
gainsAdditionalRateAllocatedIncome = 0
else
gainsStartingRateAllocatedIncome = remainingSSR
gainsBasicRateAllocatedIncome = remainingBasicRateBand
gainsHigherRateAllocatedIncome = remainingHigherRateBand
gainsAdditionalRateAllocatedIncome = remainingGainsTaxableIncome - (savingsStartingRateLimit + remainingBasicRateBand + remainingHigherRateBand)
end if

// Calculate gains tax
gainsStartingRateTax = roundDown(gainsStartingRateAllocatedIncome * (gainsStartingRate / 100), 2) // Round down to 2 decimal places
gainsPSATax = roundDown(remainingPSA * (gainsPSARate / 100), 2) // Round down to 2 decimal places
gainsBasicRateTax = roundDown(gainsBasicRateAllocatedIncome * (gainsBasicRate / 100), 2) // Round down to 2 decimal places
gainsHigherRateTax = roundDown(gainsHigherRateAllocatedIncome * (gainsHigherRate / 100), 2) // Round down to 2 decimal places
gainsAdditionalRateTax = roundDown(gainsAdditionalRateAllocatedIncome * (gainsAdditionalRate / 100), 2) // Round down to 2 decimal places

// Sum total gains tax across bands
totalGainsTax = gainsStartingRateTax + gainsPSATax + gainsBasicRateTax + gainsHigherRateTax + gainsAdditionalRateTax

// Final calculation
incomeTaxCharged = totalTaxPPP + totalSavingsTax + totalDividendTax + totalLumpSumsTax + totalGainsTax

```

--------------------------------

### Say hello application

Source: https://developer.service.hmrc.gov.uk/api-documentation/docs/api/service/api-example-microservice/1.0

An example of an application-restricted endpoint that requires application authentication.

```APIDOC
## GET /hello/application

### Description
This endpoint returns a greeting that is specific to the authenticated application. It requires application-level authorization.

### Method
GET

### Endpoint
/hello/application

### Response
#### Success Response (200)
- **message** (string) - An application-specific greeting message.
```

--------------------------------

### Error Response Example

Source: https://developer.service.hmrc.gov.uk/api-documentation/docs/api/service/self-assessment-bsas-api/7.0/oas/page

Example of a common error response format for the API.

```APIDOC
## Error Response

### Description
This is an example of an error response that might be returned by the API.

### Response Example
```json
{
  "code": "FORMAT_NINO",
  "message": "The provided NINO is invalid"
}
```

### Common Error Codes
- **FORMAT_NINO**: The format of the supplied NINO field is not valid.
- **FORMAT_CALCULATION_ID**: The format of the supplied Calculation ID is not valid.
- **FORMAT_VALUE**: The format of the supplied value is not valid.
- **RULE_BOTH_EXPENSES_SUPPLIED**: Both expenses and disallowable expenses were supplied.
- **RULE_TYPE_OF_BUSINESS_INCORRECT**: The type of business specified is incorrect.
- **RULE_INCORRECT_OR_EMPTY_BODY_SUBMITTED**: The request body submitted is incorrect or empty.
- **RULE_SUMMARY_STATUS_INVALID**: The summary status is invalid.
- **RULE_SUMMARY_STATUS_SUPERSEDED**: The summary status has been superseded.
- **RULE_ALREADY_ADJUSTED**: The item has already been adjusted.
- **RULE_RESULTING_VALUE_NOT_PERMITTED**: The resulting value is not permitted.
- **RULE_OVER_CONSOLIDATED_EXPENSES_THRESHOLD**: The consolidated expenses threshold has been exceeded.
- **RULE_TRADING_INCOME_ALLOWANCE_CLAIMED**: Trading income allowance has been claimed.
- **RULE_ZERO_ADJUSTMENTS_INVALID**: Zero adjustments are invalid.
- **RULE_BOTH_ADJUSTMENTS_SUPPLIED**: Both adjustments were supplied.
- **RULE_OUTSIDE_AMENDMENT_WINDOW**: The request is outside the amendment window.
- **RULE_TAX_YEAR_NOT_SUPPORTED**: The specified tax year is not supported.
- **FORMAT_TAX_YEAR**: The format of the tax year is invalid.
- **RULE_TAX_YEAR_RANGE_INVALID**: The tax year range is invalid.
- **RULE_INCORRECT_GOV_TEST_SCENARIO**: The government test scenario is incorrect.
- **FORMAT_NINO**: The format of the supplied NINO field is not valid.
```

--------------------------------

### Initiate File Upload Request

Source: https://developer.service.hmrc.gov.uk/guides/customs-declarations-end-to-end-service-guide/documentation/uploading-supporting-documents.html

This example shows how to initiate a file upload request with two files, specifying the Declaration ID and the number of files in the group.

```APIDOC
## Initiate File Upload Request

### Description
Initiates a file upload request for a customs declaration. Allows specifying multiple files within a single request.

### Method
POST

### Endpoint
/file-upload

### Headers
- **Accept**: application/vnd.hmrc.2.0+xml (or other environment-specific value)
- **Content-Type**: application/xml; charset=UTF-8
- **X-Badge-Identifier**: (Optional, for CSPs)
- **X-Eori-Identifier**: (Optional, for CSPs)

### Request Body
```xml
<hmrc:FileUploadRequest xmlns:hmrc="hmrc:fileupload">
       <hmrc:DeclarationID>23GBXXXXXXXXXXXXXX</hmrc:DeclarationID>
       <hmrc:FileGroupSize>2</hmrc:FileGroupSize>
       <hmrc:Files>
         <hmrc:File>
           <hmrc:FileSequenceNo>1</hmrc:FileSequenceNo>
         </hmrc:File>
         <hmrc:File>
           <hmrc:FileSequenceNo>2</hmrc:FileSequenceNo>
         </hmrc:File>
       </hmrc:Files>
      </hmrc:FileUploadRequest>
```

### Parameters
#### Request Body Parameters
- **DeclarationID** (string) - Required - The unique identifier for the customs declaration.
- **FileGroupSize** (integer) - Required - The total number of files in this upload request. Maximum of 11.
- **Files** (object) - Required - Contains a list of files to be uploaded.
  - **File** (object) - Represents a single file.
    - **FileSequenceNo** (integer) - Required - The sequence number of the file within the group (starting from 1).

### Response
#### Success Response (200 OK)
Returns an S3 `Href` and a `Fields` collection for each file upload initiated.

#### Error Response (400 Bad Request)
Returned for invalid XML payload.
```xml
<errorResponse>
  <code>BAD_REQUEST</code>
  <message>Payload is not valid according to schema</message>
  <errors>
    <error>
      <code>xml_validation_error</code>
      <message>Error at line 13, column 13: no declaration found for element 'unknown'</message>
    </error>
  </errors>
</errorResponse>
```

#### Error Response (500 Internal Server Error)
Returned for internal server errors.
```xml
<errorResponse>
  <code>INTERNAL_SERVER_ERROR</code>
  <message>Internal server error</message>
</errorResponse>
```
```

--------------------------------

### Initiate File Upload Request with Redirects and Document Type

Source: https://developer.service.hmrc.gov.uk/guides/customs-declarations-end-to-end-service-guide/documentation/uploading-supporting-documents.html

This example demonstrates an initiate file upload request including optional redirect URLs for success and errors, and specifies the document type.

```APIDOC
## Initiate File Upload Request with Redirects and Document Type

### Description
Initiates a file upload request, including optional parameters for redirecting the user upon successful or failed uploads, and specifying the type of document being uploaded. This is particularly useful for UI applications.

### Method
POST

### Endpoint
/file-upload

### Headers
- **Accept**: application/vnd.hmrc.2.0+xml (or other environment-specific value)
- **Content-Type**: application/xml; charset=UTF-8
- **X-Badge-Identifier**: (Optional, for CSPs)
- **X-Eori-Identifier**: (Optional, for CSPs)

### Request Body
```xml
<hmrc:FileUploadRequest xmlns:hmrc="hmrc:fileupload">
          <hmrc:DeclarationID>23GBXXXXXXXXXXXXXX</hmrc:DeclarationID>
          <hmrc:FileGroupSize>1</hmrc:FileGroupSize>
          <hmrc:Files>
            <hmrc:File>
              <hmrc:FileSequenceNo>1</hmrc:FileSequenceNo>
              <hmrc:DocumentType>Licence</hmrc:DocumentType>
              <hmrc:SuccessRedirect>https://success-redirect.com</hmrc:SuccessRedirect>
              <hmrc:ErrorRedirect>https://error-redirect.com</hmrc:ErrorRedirect>
            </hmrc:File>
          </hmrc:Files>
        </hmrc:FileUploadRequest>
```

### Parameters
#### Request Body Parameters
- **DeclarationID** (string) - Required - The unique identifier for the customs declaration.
- **FileGroupSize** (integer) - Required - The total number of files in this upload request. Maximum of 11.
- **Files** (object) - Required - Contains a list of files to be uploaded.
  - **File** (object) - Represents a single file.
    - **FileSequenceNo** (integer) - Required - The sequence number of the file within the group (starting from 1).
    - **DocumentType** (string) - Optional - The type of document being uploaded (e.g., 'Licence').
    - **SuccessRedirect** (string) - Optional - URL to redirect to upon successful upload.
    - **ErrorRedirect** (string) - Optional - URL to redirect to upon failed upload.

### Response
#### Success Response (200 OK)
Returns an S3 `Href` and a `Fields` collection for each file upload initiated.

#### Error Response (400 Bad Request)
Returned for invalid XML payload.
```xml
<errorResponse>
  <code>BAD_REQUEST</code>
  <message>Payload is not valid according to schema</message>
  <errors>
    <error>
      <code>xml_validation_error</code>
      <message>Error at line 13, column 13: no declaration found for element 'unknown'</message>
    </error>
  </errors>
</errorResponse>
```

#### Error Response (500 Internal Server Error)
Returned for internal server errors.
```xml
<errorResponse>
  <code>INTERNAL_SERVER_ERROR</code>
  <message>Internal server error</message>
</errorResponse>
```
```

--------------------------------

### Get Trader Information

Source: https://developer.service.hmrc.gov.uk/guides/emcs-api-service-guide/documentation/get-trader-information.html

Use the POST endpoint Get information relating to an excise trader to get information about an excise trader. The request body must include the excise reference number (ERN), entity group and authorisation request.

```APIDOC
## POST /trader-information

### Description
Retrieves information about an excise trader based on provided details.

### Method
POST

### Endpoint
/trader-information

### Parameters
#### Request Body
- **excise_reference_number** (string) - Required - The excise reference number of the trader.
- **entity_group** (string) - Required - The entity group of the trader. Available options: UK Record, EU Trader, EU Warehouse, EU Temporary Authorisation.
- **authorisation_request** (object) - Required - Details of the authorisation request.

### Response
#### Success Response (200)
- **validation_timestamp** (string) - The timestamp of the validation.
- **ern** (string) - The excise reference number.
- **entity_group** (string) - The entity group.
- **valid_trader** (boolean) - Indicates if the trader is valid.
- **trader_type** (string) - The type of the trader. Available options: Warehouse Keeper, Tax Warehouse, Registered Consignor, Registered Consignee, Temporary Registered Consignee, Temporary Registered Authorisation, Other.
- **validate_product_authorisation_response** (object) - Response from product authorisation validation.
- **error_code** (string) - Optional - Error code if the validation resulted in a business error.
- **error_text** (string) - Optional - Error text if the validation resulted in a business error.

#### Error Response (400)
- **DateTime** (string) - The date and time of the error.
- **message** (string) - A message describing the error.
- **debug_message** (string) - A debug message for the error.

#### Error Response (500)
- **DateTime** (string) - The date and time of the error.
- **message** (string) - A message describing the error.
- **debug_message** (string) - A debug message for the error.
```

--------------------------------

### Example JSON Response for Business Source Adjustable Summary

Source: https://developer.service.hmrc.gov.uk/api-documentation/docs/api/service/self-assessment-bsas-api/7.0/oas/page

This is an example of a successful JSON response containing business source summaries. It includes details for different business types, accounting periods, and tax years, along with calculation IDs and status.

```json
{
  "businessSources": [
    {
      "businessId": "XBIS12345678901",
      "typeOfBusiness": "self-employment",
      "accountingPeriod": {
        "startDate": "2018-10-11",
        "endDate": "2019-10-10"
      },
      "taxYear": "2019-20",
      "summaries": [
        {
          "calculationId": "76350054-0f11-4024-a811-99bcf5ced792",
          "requestedDateTime": "2019-10-14T11:33:27Z",
          "summaryStatus": "valid",
          "adjustedSummary": false
        },
        {
          "calculationId": "ef1a6fd7-3faa-4323-9a9d-fe5cc8ed1c43",
          "requestedDateTime": "2019-10-10T09:01:35Z",
          "summaryStatus": "superseded",
          "adjustedSummary": true,
          "adjustedDateTime": "2019-10-11T09:01:35Z"
        }
      ]
    },
    {
      "businessId": "XBIS12345678904",
      "typeOfBusiness": "uk-property-fhl",
      "accountingPeriod": {
        "startDate": "2019-04-06",
        "endDate": "2020-04-05"
      },
      "taxYear": "2019-20",
      "summaries": [
        {
          "calculationId": "56f0a4fe-cfa7-4a21-8aa8-6c8f4642b792",
          "requestedDateTime": "2020-05-14T12:17:15Z",
          "summaryStatus": "valid",
          "adjustedSummary": false
        },
        {
          "calculationId": "7f1fd081-3f59-4fd6-9b1c-c90521e0f7a8",
          "requestedDateTime": "2020-04-10T13:03:17Z",
          "summaryStatus": "superseded",
          "adjustedSummary": true,
          "adjustedDateTime": "2020-04-11T13:03:17Z"
        }
      ]
    },
    {
      "businessId": "XBIS12345678915",
      "typeOfBusiness": "foreign-property",
      "accountingPeriod": {
        "startDate": "2021-04-06",
        "endDate": "2022-04-05"
      },
      "taxYear": "2019-20",
      "summaries": [
        {
          "calculationId": "16332284-c01b-4046-a055-6c00454467a2",
          "requestedDateTime": "2022-05-14T12:17:15Z",
          "summaryStatus": "valid",
          "adjustedSummary": false
        },
        {
          "calculationId": "7ef31d49-ce57-4622-94fc-f4248b72b2cd",
          "requestedDateTime": "2020-04-10T13:03:17Z",
          "summaryStatus": "superseded",
          "adjustedSummary": true,
          "adjustedDateTime": "2020-04-11T13:03:17Z"
        }
      ]
    }
  ]
}
```

--------------------------------

### Error Response Example (400 Bad Request)

Source: https://developer.service.hmrc.gov.uk/guides/emcs-api-testing-guide/documentation/test-scenarios.html

Example structure of a 400 Bad Request error response.

```APIDOC
## Error Response Example (400 Bad Request)

A 400 Bad Request error response will take the form of

```json
{
  "dateTime": "2021-12-17T09:30:47Z",
  "message": "Json validation failed",
  "debugMessage": "user is missing but it is required",
  "correlationId": "3e8dae97-b586-4cef-8511-68ac12da9028"
}
```
```

--------------------------------

### Example EORI Numbers

Source: https://developer.service.hmrc.gov.uk/guides/uknw-auth-checker-api-service-guide

Examples of EORI numbers for businesses based in Great Britain (GB) and Northern Ireland (XI).

```text
GB205672212000 # EORI number originating in GB (Wales, England or Scotland)
XI347643313000 # EORI number originating in NI
```