Setting up your account

By default, the sandbox system will only accept the following GSTIN as the seller GSTIN. Please reach out to your Account Manager in Cleartax if you want to test with your own production GSTIN.

State	GSTIN
Karnataka	29AAFCD5862R000
Gujarat	24AAFCD5862R005
ANDAMAN AND NICOBAR ISLANDS	35AAFCD5862R010
ANDHRA PRADESH	37AAFCD5862R011
ASSAM	18AAFCD5862R020
BIHAR	10AAFCD5862R019
DELHI	07AAFCD5862R007
GUJARAT	24AAFCD5862R005
HARYANA	06AAFCD5862R017
JAMMU AND KASHMIR	01AAFCD5862R015
MAHARASHTRA	27AAFCD5862R013
PUNJAB	03AAFCD5862R016
TAMIL NADU	33AAFCD5862R009
TELANGANA	36AAFCD5862R014
UTTAR PRADESH	09AAFCD5862R006

This API is currently NOT available in the staging environment.

ClearTax E-Invoicing is a value-added platform between your ERP and the Government portal. To start making any transaction via ClearTax, first you will have to update your ClearTax account with your NIC credentials. This is generally a one-time activity per user account unless you decide to change the NIC credentials.

In this guide, you will learn how to update NIC credentials in your ClearTax E-Invoicing account.

Onboarding Seller GSTIN

You can use this API to onboard your GSTINs into your ClearTax workspace.

Request Method

POST

Request URL

{{HOST}}/einv/v1/gstin

Request Headers

Parameter	Data Type	Field Validations	Description
x-cleartax-auth-token	String	NA	Mandatory. The auth token generated from ClearTax user id and password. Know how?
Content-Type	String	NA	Mandatory. This will always be "application/json".

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
gstin	String	Yes	GSTIN of the entity
displayName	String	Yes	Name to display
vendor	Boolean	Yes	Indicates if the entity is a vendor

Response Status Codes

HTTP Status Code	Description
200	Success
400	Bad request
401	Unauthorized
500	Internal server error

Response Schema

Parameter	Data Type	Field Validations	Description
status	String	NA	Status of the API call (e.g., "success")

Sample Request and Response

Success Sample

Request:

curl --location 'https://api-sandbox.clear.in/einv/v1/gstin' \
--header 'x-cleartax-auth-token: ' \
--header 'Content-Type: application/json' \
--data '{
 "gstin": "29AAFCD5862R000",
 "displayName": "ABC",
 "vendor": false
}'

Response:

{
    "success": true
}

Error Sample

Request:

curl --location 'https://api-sandbox.clear.in/einv/v1/gstin' \
--header 'x-cleartax-auth-token: ' \
--header 'Content-Type: application/json' \
--data '{
 "gstin": "INVALID_GSTIN",
 "displayName": "InvalidEntity",
 "vendor": false
}'

Response:

{
    "success": false,
    "errorDetail": {
        "errorCode": "6002",
        "errorMessage": "Invalid GSTIN Number 29AAFCD5862R00",
        "errorSource": "CLEARTAX"
    }
}

API Validations

GSTIN Format must be a valid 15-character GSTIN

API Constraints

• The gstin field must adhere to the GSTIN format.

• The x-cleartax-auth-token must be valid and unexpired.

Adding/Updating NIC Credentials

You can add or update NIC credentials in ClearTax by sending a POST request to E-Invoicing API with the following request headers.

x-cleartax-auth-token: {{USER_AUTH_TOKEN}}
x-cleartax-product: EInvoice
Content-Type: application/json
gstin: {{GSTIN}}

Note: If you already have NIC credentials on your account, using this API will override existing credentials for the specified owner_id.

Request URL

POST: {{HOST}}/einv/v2/nic_credentials/store_nic_credentials

Sample URL

POST: https://api.clear.in/einv/v2/nic_credentials/store_nic_credentials

Request Header

Parameter	Data Type	Field Validations	Description
X-Cleartax-Auth-Token	String	NA	Mandatory. The auth token generated from ClearTax user id and password. Know how?
Content-Type	String	NA	Mandatory. This will always be "application/json".
gstin	String	NA	Mandatory. GSTIN number of the user

Request Path Params

There are no path parameters for this API.

Request Query Params

Parameter	Data Type	Field Validations	Description
shouldPersist	Boolean	NA	Optional. If true, credentials will be saved to the database. Otherwise the credentials will only be authenticated. Default - true

Request Body

Parameter	Data Type	Field Validations	Description
gstin	String	15 Characters	User's GSTIN
username	String	NA	User's NIC Username
password	String	NA	User's NIC Password

Sample Request

{
    "gstin": "29AAFCD5862R000",
    "username": "API_TEST",
    "password": "pwd@2022#"
}

Sample Response

Success

{
    "success": true,
    "errorDetails": null
}

Error

{
    "success": false,
    "errorDetails": {
        "error_code": "1019",
        "error_message": "NIC API credentials are not correct. Please update correct NIC credentials on CT Portal",
        "error_source": "GOVT"
    }
}