Generate CSID and PCSID

Generates CSID and PCSID from ZATCA for the given Device ID.

A new version is available!

You can generate a Device ID, CSID, and PCSID, all in one go with the Register Device API.

Request Method

POST

Request URL

{{BASE_URL}}/onboarding/generate-csid

Replace the {{BASE_URL}} with the one mentioned here based on whether you are using sandbox or production.

Request Headers

ParameterData TypeField ValidationsDescription

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

ParameterData TypeField ValidationsDescription

DeviceId

String

Cannot be empty.

Mandatory. The Device ID received in the Generate Device ID API.

Otp

String

Should be a valid OTP.

Mandatory. The one time password generated by the user on the ZATCA portal. OTP once generated is valid only for 1 hour.

Sample Request

{
    "DeviceId": "4f190640-9b36-42e9-88d1-0c31a961898d",
    "Otp": "123345"
}

Response Status Codes

HTTP Status CodeDescription

200

For a successful CSID generation and PCSID generation trigger.

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

ParameterData TypeField ValidationsDescription

Status

String

Enum:

GENERATED,

FAILED

Mandatory. CSID Generation Status.

GENERATED: CSID was generated successful. FAILED: CSID failed to generate (had validation errors).

DeviceId

String

NA

Mandatory. Device ID sent in the request.

PcsidGenerationActivityId

String

MaxLength: 24

Optional. PCSID Generation Activity ID. Save this to poll status later using the Get PCSID Generation Status API.

ErrorList

Array

NA

Optional. Array of Error Details objects.

Sample Response

Success - HTTP Status Code - 200

{
    "DeviceId": "e0649f12-011c-47ac-a867-651f38426450",
    "Status": "GENERATED",
    "PcsidGenerationActivityId": "62972e815bc1fa6cd2835c41",
    "ErrorList": []
}

Error - HTTP Status Code - 400

{
    "DeviceId": "dac1aa05-92ba-4bd6-a834-b665e8f89930",
    "Status": "FAILED",
    "ErrorList": [
        {
            "ErrorCode": "6002",
            "ErrorMessage": "Production CSID already generated for device",
            "ErrorSource": "CLEARTAX"
        }
    ]
}

API Validations

  1. A PCSID should not have been already generated for the Device ID. This API is not idempotent. In case of a duplicate request, this will throw an exception.

  2. A CSR should have been already created for the Device ID in ClearTax.

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.

Last updated