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

https://api-sandbox.cleartax.com/middle-east/ksa/einvoicing/v1/businessHierarchy

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	If the 11th digit of VAT is equal to 1 then the org unit name should always be TIN. If the 11th digit of VAT is not equal to 1 then it can be free text.	Optional. The branch name of taxpayer and in case of Group VATs this field should be the 10 digit TIN number.

Sample Request

Request Body

{
   "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

{
   “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.