# 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](https://docs.cleartax.in/cleartax-docs/e-invoicing-ksa-api/e-invoicing-ksa-api-reference) 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.