# Add Business units API

Add VAT and/or Branch to the business hierarchy of your account in a single request.

### Request Method

POST

### Request URL

```
{{BASE_URL}}/v1/businessHierarchy
```

{% hint style="info" %}
Replace the `{{BASE_URL}}` with the one mentioned [here](/cleartax-docs/e-invoicing-ksa-api/e-invoicing-ksa-api-reference.md) based on whether you are using sandbox or production.
{% endhint %}

### Request Headers

| Parameter             | Data Type | Field Validations | Description                                |
| --------------------- | --------- | ----------------- | ------------------------------------------ |
| x-cleartax-auth-token | String    | Cannot be empty   | Mandatory. User auth token.                |
| vat                   | String    | Cannot be empty   | Mandatory. VAT or Group VAT of the entity. |

### Request Path Params

There are no path parameters for this API. 

### Request Query Params

There are no query parameters for this API.

### Request Body

| Parameter            | Data Type | Field Validations                                                                                                                                                                    | Description                                                                                                                                  |
| -------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------- |
| Vat                  | String    | Must contain 15 digits. The first and the last digits should be “3”.                                                                                                                 | Mandatory.                                                                                                                                   |
| VatDisplayName       | String    | NA                                                                                                                                                                                   | Optional. The registered business name of the VAT which will be visible on the web portal and for device registration.                       |
| Branch               | String    | NA                                                                                                                                                                                   | Optional. Name of the branch or store to be added in the taxpayer account under a certain VAT.                                               |
| OrganizationUnitName | String    | <p>If the 11th digit of VAT is equal to 1 then the org unit name should always be TIN.</p><p><br>If the 11th digit of VAT is not equal to 1 then it can be free text.</p><p><br></p> | <p>Optional. The branch name of taxpayer and in case of</p><p>Group VATs this field should be the 10 digit </p><p>TIN number.</p><p><br></p> |

### Sample Request

Request Body

```json
{
   "Vat":"300492946901103",
   "VatDisplayName" : "vatName",
   "Branch":"branchName",
   “OrganizationUnitName”:”legalName”
}
```

### Response Status Codes

| HTTP Status Code | Description                                         |
| ---------------- | --------------------------------------------------- |
| 200              | For successful retrieval.                           |
| 400              | Bad request Unable to process JSON.                 |
| 401              | If the user is not authenticated for the operation. |
| 5XX              | Unhandled exception.                                |

### Response Schema

| Parameter            | Data Type | Field Validation | Description              |
| -------------------- | --------- | ---------------- | ------------------------ |
| success              | Boolean   | NA               | True or false            |
| Vat                  | String    | NA               | VAT registration number. |
| VatDisplayName       | String    | NA               |                          |
| Branch               | String    | NA               | If given.                |
| OrganizationUnitName | String    | NA               |                          |

### Sample Response

```json
{
   “Success”:true,
   "Vat":"300492946901103",
   "VatDisplayName" : "vatName",
   "Branch":"branchName",
   “OrganizationUnitName”:”legalName”
}
```

### API Validations

* Only VAT will be validated with gcc rules.
* VAT should be 15 digit number.
* Only numeric values allowed.

### API Constraints

* This API needs to be authenticated with a valid user authentication token. If the authtoken is not present or is invalid, the API will return HTTP Status Code 401.
* If the user wants to add Branch, then the “Branch” field should be present in the request field, otherwise it will throw an error for an already existing vat.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.cleartax.in/cleartax-docs/e-invoicing-ksa-api/e-invoicing-ksa-api-reference/generating-e-invoice/add-business-units-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.