# 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** ```json { "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) ```json { "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. ```json { "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. ```json { "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).