Get Documents

Retrieve a list of purchase e-invoice documents filtered by date range, type, and pagination.

Request Method

GET

Request URL

https://api.eu.cleartax.com/be/einvoice/v1/documents/query

Request Headers

Parameter	Data Type	Field Validations	Description
x-cleartax-auth-token	String	Cannot be empty	Mandatory. User auth token.
x-clear-vat	String	Cannot be empty	Mandatory. VAT 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.
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	PURCHASE	Mandatory. It is a fixed value and must be passed as PURCHASE
page-number	Integer		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 is no request body for this API.

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
5XX	Unhandled exception

Response Schema

Parameter	Data Type	Field Validations	Description
Success	String	true/false	Identifies whether the request processing was successful or not
Documents	Array		List of documents based on the filters
ErrorDetails	Array	NA	Array of api level error details, is null when no errors are there
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.
DocumentNumber	String	NA	Document number is the name/number given to it by the supplier
Status	String	For PURCHASE “Validated”	Validated: The purchase e-invoice has been verified and is confirmed as valid.
ErrorDetails	Array	NA	Optional. List of error objects, empty in case no errors are present.

Sample Request and Response

Request

There is no request body for this API.

Response - Success:

HTTP Status Code: 200

{
    "Success": "true",
    "Documents": [
        {
            "DocumentId": "688b691a0cc65a6767f69193",
            "DocumentNumber": "om-22",
            "Status": "Validated",
            "ErrorDetails": []
        },
        {
            "DocumentId": "688b6f310cc65a6767f69194",
            "DocumentNumber": "om-22",
            "Status": "Validated",
            "ErrorDetails": []
        }
    ],
    "ErrorDetails": null,
    "PageNumber": 0,
    "PageSize": 2
}

Response - Failure:

HTTP Status Code: 400

Response Body (when start-date is not provided, similar messages for end-date, date range exceeding 3 day limit, etc will be shown)

{
    "ErrorDetails": [
        {
            "ErrorCode": "400",
            "ErrorMessage": "start-date is required",
            "ErrorSource": "CLEARTAX",
            "Path": null
        }
    ]
}

HTTP Status Code: 401

When the Authentication token is not provided in the API headers or the provided value is wrong.

{
    "ErrorDetails": [
        {
            "ErrorCode": "401",
            "ErrorMessage": "Unauthorized",
            "ErrorSource": "CLEARTAX",
            "Path": null
        }
    ]
}

HTTP Status Code: 403

When the VAT is not provided in the API headers or the provided value is wrong.

{
    "ErrorDetails": [
        {
            "ErrorCode": "403",
            "ErrorMessage": "FORBIDDEN",
            "ErrorSource": "CLEARTAX",
            "Path": null
        }
    ]
}

API Limitations

A Maximum of 1000 records can be fetched in one API call.

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 get a list of documents, then the API will return HTTP Status Code 403. The user, whose auth token is used, should have an Admin role.

3. Results are paginated using page-number (0-based) and page-size. the first record on a page is offset = page-number * page-size. page-number >= 0. page-size ∈ [1, 1000]. For example: to fetch the 1300th record (0-based index): request page-number=1 and page-size=1000 (returns records 1000–1999).