Get Documents

Request Method

GET

Request URL

{{HOST}}/einvoice/v1/documents/query

Rate Limit : 1000 API requests per minute

Request Headers

Parameter	Data Type	Field Validations	Description
x-cleartax-auth-token	String	Cannot be empty	Mandatory. User auth token.
x-clear-tin	String	Cannot be empty	Mandatory. TIN of the entity
x-clear-branch	String	Should be a valid branch from the user account	Optional. Branch name (store name) added in the user account which maps to a TIN of the entity.
x-request-id	UUID	Should be unique for every request	Optional. Unique request ID.

Request Path Params

There are no path parameters for this API.

Request Query Params

Parameter	Data Type	Field Validations	Description
start-date	Date	Format - ISO.DATE E.g - 2024-07-20	Mandatory. Document Start date
end-date	Date	Format - ISO.DATE E.g - 2024-07-22	Mandatory. Document End Date The difference between start date & end date should not be more than 3 days
einvoice-type	ENUM	SALES, SALES_B2C, PURCHASE, SALES_CONSOLIDATED, PURCHASE_CONSOLIDATED	Mandatory.
page-number	Integer	NA	Optional. Default: 0 Specifies the current page number for which data is to be retrieved. The value 0 represents the first page.
page-size	Integer	Minimum: 1, Maximum: 1000	Optional. Default: 100 Defines the maximum number of documents to be returned in a single API call. The value must be between 1 and 1000.

Request Body

There will be no request body for this API.

Sample Request

Request Body

NA

Response Status Codes

HTTP Status Code	Description
200	For a successful retrieval
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
429	Too many requests
5XX	Unhandled exception

Response Schema

Parameter	Data Type	Field Validations	Description
Success	Boolean	true/false	Identifies whether the request processing was successful or not
Documents	Array	NA	Mandatory. List of documents based on the filters
ErrorDetails	Array	NA	Optional. List of error objects.
PageNumber	Integer	NA	Indicates the current page number being accessed
PageSize	Integer	NA	Indicates the number of records returned in the response

Documents Object

Parameter	Data Type	Field Validations	Description
DocumentId	String	NA	DocumentId generated by ClearTax uniquely identifies the document.
Status	String	VALID/ INVALID/ SUBMITTED/ NOT_GENERATED/ CANCELLED/ FAILED/ CONSOLIDATED	Mandatory. Status of Document Processing VALID: E-Invoice is generated for the document and is Valid. INVALID: E-Invoice has validation errors from LHDN SUBMITTED: E-Invoice Generation is in Progress NOT_GENERATED: E-Invoice is not submitted for the Document CANCELLED : E-Invoice is cancelled FAILED : E-Invoice Generation failed. CONSOLIDATED: E-Invoice is consolidated.
UUID	String	NA	Unique document ID in e-Invoice, shared by LHDN for the document
LongId	String	NA	Unique long temporary Id that can be used to query document data anonymously
InternalId	String	NA	Internal ID used in submission for the document to LHDN, link document number
DateTimeValidated	DateTime	NA	The date and time when the document passed all validations and moved to the valid state.
CancelDateTime	DateTime	NA	Refer to the document cancellation that has been initiated by the taxpayer “issuer” of the document on the system, will be in UTC format
RejectRequestDateTime	DateTime	NA	Refer to the document rejection request that has been initiated by the taxpayer “receiver” of the document on the system, will be in UTC format
ConsolidatedDocumentId	String	NA	This will come only in case the status is “CONSOLIDATED”. It will represent the ClearTax generated DocumentId of the consolidated Document.
ConsolidatedDocumentStatus	String	NA	This will come only in case the status is “CONSOLIDATED”. It will represent the status of the consolidated Document.
ErrorDetails	Array	NA	Optional. List of error objects.

Sample Response (Success)

HTTP Status Code: 200

Response Body - 1

{
    "Success": "true",
    "Documents": [
        {
            "DocumentId": "66befcb7c465be7e9d3b9012",
            "DocumentNumber": "2024-07-17-60",
            "Status": "VALID",
            "UUID": "GGWX0HS8NFHJ8MFJTX441D5J10",
            "LongId": "QQGV37423WR2NF4AVX441D5J10KsaNUM1723793019",
            "InternalId": "2024-07-17-60",
            "DateTimeValidated": "2024-08-16T15:23:40",
            "CancelDateTime": null,
            "RejectRequestDateTime": null,
            "ConsolidatedDocumentId": "",
            "ConsolidatedDocumentStatus": "",
            "ErrorDetails": []
        }
    ],
    "ErrorDetails": null,
    "PageNumber": 0,
    "PageSize": 1
}

Response Body - 2

{
    "Success": "true",
    "Documents": [
        {
            "DocumentId": "66befdb283e43b65c86dc09b",
            "DocumentNumber": "B2C+INV0000355",
            "Status": "CONSOLIDATED",
            "UUID": "545DM5QYDZ32Z1YC3JYY9D7J10",
            "LongId": "9Y420DYS8XSG80S73JYY9D7J10cZh0Xp1725949770",
            "InternalId": "CINV_SALES_B2C_2409_0000002",
            "DateTimeValidated": "2024-09-10T14:29:30",
            "CancelDateTime": null,
            "RejectRequestDateTime": null,
            "ConsolidatedDocumentId": "66dfe749a0c21f09d11aacfe",
            "ConsolidatedDocumentStatus": "VALID",
            "ErrorDetails": []
        }

    ],
    "ErrorDetails": null,
    "PageNumber": 0,
    "PageSize": 1
}

Sample Response (Error)

HTTP Status Code: 200

Response Body

{
    "ErrorDetails": [
        {
            "ErrorCode": "400",
            "ErrorMessage": "Invalid Request Parameter passed.",
            "ErrorSource": "CLEARTAX",
            "Path": null
        }
    ]
}

API Validations

Currently, there are no known validations.

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. Each customer is allowed to send a limited number of requests per minute to prevent server overload. If the limit is exceeded, the server will respond with a 429 Too Many Requests status code.

3. If the auth token is valid, but the user does not have the authorization to get list of documents, then the API will return HTTP Status Code 403. The user, whose auth token is used, should have an Admin role for the particular TIN used in the request.