# Generate Device ID

Generates a Device ID in ClearTax.

{% hint style="warning" %}
**A new version is available!**

You can generate a Device ID, CSID, and PCSID, all in one go with the [Register Device API](generate-device-id).
{% endhint %}

### Request Method

POST

### Request URL

```
{{BASE_URL}}/onboarding/generate-csr
```

{% hint style="info" %}
Replace the `{{BASE_URL}}` with the one mentioned [here](..) 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](../../learn-e-invoicing-ksa-api-basics/how-to-get-e-invoicing-ksa-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                             |
| ------------------- | --------- | ----------------- | --------------------------------------- |
| DeviceDetails       | Object    | NA                | Mandatory. Device Details Object        |
| OrganizationDetails | Object    | NA                | Mandatory. Organization Details Object. |

#### Device Details Object

| Parameter       | Data Type | Field Validations                                                                                         | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| --------------- | --------- | --------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| CommonName      | String    | Cannot be empty.                                                                                          | Mandatory. Name or Asset Tracking Number used by the taxpayer for the Solution Unit being onboarded.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| EgsSerialNumber | String    | RegEx: ^1-(?\<manufacturer>\[a-zA-Z0-9]+)\[\|]2-(?\<model>\[a-zA-Z0-9]+)\[\|]3-(?\<serial>\[a-zA-Z0-9]+)$ | Mandatory. Manufacturer or Solution Provider Name, Model or Version and Serial Number.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| Location        | String    | Cannot be empty.                                                                                          | Mandatory. The address of the Branch or location where the device or solution unit is primarily situated                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| Industry        | String    | Cannot be empty.                                                                                          | Mandatory. Industry or sector for which the device or solution will generate invoices.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| InvoiceType     | String    | RegEx: ^(?!0{4})\[01]{2}\[00]{2}$                                                                         | <p>Optional. The document type that the Taxpayer’s solution unit will be issuing/generating in “TSXY” format where:</p><p>T = Standard Tax Invoice, S = Simplified Tax Invoice, X = Reserved placeholders, Y = Reserved placeholders.</p><p>The input for each place above should be using the digits 0 &#x26; 1 where: 0 = False/Not supported, 1= True/Supported</p><p>(X) and (Y) are for future use and should be set to 0 by default for the time being.</p><p>For example: 1000 would mean Solution will be generating Standard Invoices only. 0100 would mean Solution will be generating Simplified invoices only. and 1100 means Solution will be generating both Standard and Simplified invoices.</p><p>Default: 1100.</p> |

#### Organization Details Object

| Parameter            | Data Type | Field Validations                                                                                                         | Description                                                                                                                                                            |
| -------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Vat                  | String    | 15 digits, starting and ending with 3                                                                                     | Mandatory. VAT or Group VAT Registration Number.                                                                                                                       |
| OrganizationName     | String    | Cannot be empty                                                                                                           | Mandatory. Taxpayer/Organization Name.                                                                                                                                 |
| OrganizationUnitName | String    | <p>If 11th digit of Vat is not = 1 then free text.</p><p>If 11th digit of Vat = 1 then needs to be a 10 digit number.</p> | <p>Mandatory. If Vat is NOT Group Vat, then the branch name of the taxpayer.</p><p>If Vat is a Group VAT ID, then the 10-digit TIN of the individual group member.</p> |
| CountryCode          | String    | 2 letter country code (ISO 3166 Alpha-2)                                                                                  | Mandatory. Country Code.                                                                                                                                               |

### Sample Request

```json
{
    "DeviceDetails": {
        "CommonName": "116.197.153.161",
        "EgsSerialNumber": "egs013",
        "Location": "loc",
        "Industry": "industry",
        "InvoiceType": "1100"
    },
    "OrganizationDetails": {
        "Vat": "310123454345233",
        "OrganizationName": "DSPL",
        "OrganizationUnitName": "Jeddah Branch 1234",
        "CountryCode": "SA"
    }
}
```

### Response Status Codes

| HTTP Status Code | Description                                         |
| ---------------- | --------------------------------------------------- |
| 200              | For a successful CSR/DeviceId generation.           |
| 400              | For any kind of validation issues.                  |
| 401              | If the user is not authenticated for the operation. |
| 403              | If the user is not authorized for the operation.    |

### Response Schema

| Parameter | Data Type | Field Validations                         | Description                                                                                                                                                                            |
| --------- | --------- | ----------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Status    | String    | <p>Enum:</p><p>GENERATED</p><p>FAILED</p> | <p>Mandatory. The status of Device ID generation.</p><p></p><p>GENERATED - Device ID generation was successful.</p><p>FAILED - Device ID generation failed with validation errors.</p> |
| DeviceId  | String    | MaxLength: 36                             | UUID. An identifier to exclusively identify the device getting onboarded. On successful Device ID generation, the field value will contain a UUID.                                     |
| ErrorList | Array     | NA                                        | Validation Errors. An array of [Error Details Objects](../resources-and-masters/error-details-object). In case there are no errors, this will be an empty Array (\[]).                 |

### Sample Response

Success - HTTP Status Code - 200

```json
{
    "Status": "GENERATED",
    "DeviceId": "dac1aa05-92ba-4bd6-a834-b665e8f89930",
    "ErrorDetails": []
}
```

Success with Warning - HTTP Status Code - 200

```json
{
    "Status": "GENERATED",
    "DeviceId": "d0fad897-ba4a-4ef4-9e7a-550919861f0d",
    "ErrorList": [
        {
            "ErrorCode": "6002",
            "ErrorMessage": "A Device ID already exists with the same VAT and EGS serial number",
            "ErrorSource": "CLEARTAX"
        }
    ]
}
```

Error - HTTP Status Code - 400

```json
{
    "Status": "FAILED",
    "DeviceId": null,
    "ErrorList": [
        {
            "ErrorCode": "6002",
            "ErrorMessage": "Invalid invoice type, please provide a valid invoice type",
            "ErrorSource": "CLEARTAX",
            "Path": "DeviceDetails.InvoiceType"
        },
        {
            "ErrorCode": "6002",
            "ErrorMessage": "Invalid country code length, please provide a valid country code",
            "ErrorSource": "CLEARTAX",
            "Path": "OrganizationDetails.CountryCode"
        },
        {
            "ErrorCode": "6002",
            "ErrorMessage": "Invalid country code",
            "ErrorSource": "CLEARTAX",
            "Path": "OrganizationDetails.CountryCode"
        }
    ]
}
```

### API Validations

1. The VAT for which the device is being registered needs to be already present in ClearTax before making this API request.
2. There can be only one CSR against the `Vat` and `EgsSerialNumber` combination. In case of a duplicate request for CSR generation for the same `Vat` and `EgsSerialNumber`, the API will return the existing `DeviceId` along with Error Details. Such an error message may be treated as a warning message.

### API Constraints

1. This API needs to be authenticated with a valid user authentication token. If the auth token is not present or is invalid, the API will return HTTP Status Code 401.
2. If the auth token is valid, but the user does not have the authorization to generate device ID, then the API will return HTTP Status Code 403. The user, whose auth token is used, should have an Admin role for the particular VAT used in the request.
