Trigger File Ingestion

This API will trigger the ingestion to your Clear GST Account.

Request Method

POST

Request URL

{{BASE_URL}}/integration/v1/ingest/file/{{templateType}}

Request Headers

Parameter	Data Type	Field Validations	Description
x-cleartax-auth-token	String	NA	Mandatory. User auth token.

Request Path Params

Parameter	Data Type	Field Validations	Description
templateType	String	Enum: sales, purchase	Type of document. sales - Sales document. purchase - Purchase document.

Request Query Params

There are no query paramaters for this API.

Request Body

Parameter	Data Type	Field Validations	Description
externalId	String	NA	Deprecated. This field can be ignored.
userInputArgs	Object	NA	Mandatory. User Input Arguments Object
fileInfo	Object	NA	Mandatory. File Information Object

User Input Arguments Object

Parameter	Data Type	Field Validations	Description
gstins	Array	NA	Optional. Array of GSTINs for which the file is uploaded.
templateId	String	NA	Mandatory. Template ID of the file uploaded. For a sales document, the system template ID is "618a5623836651c01c1498ad". For a purchase document, the system template ID is "60e5613ff71f4a7aeca4336b". For custom upload templates, use the custom upload template ID.

File Information Object

Parameter	Data Type	Field Validations	Discriptions
s3FileUrl	String	NA	Mandatory. Presigned URL where the file was uploaded.
userFileName	String	NA	Mandatory. Filename used when generating the Pre-signed URL.

Sample Request

Request Body

{
    "userInputArgs": {
        "gstins": [],
        "templateId": "618a5623836651c01c1498ad"
    },
    "fileInfo": {
        "s3FileUrl": "https://storage.clear.in/v1/ap-south-1/ingestionv2-staging/307a6331-df8b-4bdd-a05a-d18812da0340/GSTSALES/2023/JANUARY/608996448b37488db5ef8a0db5c4f534/OriginalFileName/608996448b37488db5ef8a0db5c4f534__1674056071858.SalesInvoicesAndCreditOrDebitNotes?X-Amz-Security-Token=IQoJb3JpZ2luX2VjEPj%2F%2F%2F%2F%2F%2F%2F%2F%2F%2FwEaCmFwLXNvdXRoLTEiSDBGAiEA1Zo2sN7uBeqwBqsQaLQJobMwTxhFFDWpBaCEi2KPFw8CIQCGcHAeDwJxfhbNQeAsWCPOygSiHtBKgEFNPHRgwCogHyr%2FBAhhEAUaDDIxOTM0MTkwNzk4MyIMIYaj1Gcfnc2IEjP2KtwEaK3WhAgAgRQQrEDfGrPE9NPtxKNCcJRz0Q%2FZsP6froj5mWzbDT67MkA867Xzq8Z8oul6zaH2R4qTjlCz0qi2N9ebg7Rqw2jcDlgjdgRa5fVQOGShFPQM%2FB%2Bk0woVvdihwTLbzcZPU%2BNfxviBr40pGVraGG4mpwRTN9ZQfVMJPc2iT3iG3tCA4dRkFoHv8VAlC3mEBVDE%2FbNVSz4flB9T8E8arXhmtcP9HLuJWpFxXwtl%2BFkZM3POtWhJFIjSEUruVWNo6aIq1wuP49PIgwWEF6g5jiG%2Fc484qYflzVUgWWsqjTSOpVJFFhAggLoWNsKgWEyk9n38Gzp%2Fw%2FoNc%2BJKC1b7uXNJGf22jcLa4hNpBKcYVXr7DUhGssXIL5o%2BogVdvfJbrCXApWyb5IO%2BxhgJoVcpUq88gsNZdUKWAoGzINeZaWO8fXowYQrq1JE4k3XVavoBGb6f2sd1A%2F2xBypR96vqvqRiYTazEw6GZCl4jY0ODmfP%2F6RUcs%2Bok6A64juXfm3O1WCAq3j%2FdSeLH6wCcD0VAAN%2B%2FeYd5KT6Era3ThVjS5p9SkAs3vKzQ%2BCPCXbuhYiun7NvlkG0iRLKLT37oAY7Iwh1cWc0dC%2F2EYjmNAHaIm4zOaoZg05UweFrBbESKj1LcCznIcGe539wmWVL2bTTFYnl0%2BWxmfBLdCrgUNKjmQnoTJkdkRVAL93DnWAmvhQDqU3cqRo1dPy4sVfwvegcaAseGvLzloHT4h2TmnEjj2qJvkEdkwrU7RYfa5O3p1znF2swSaTpwF0%2FEVWh%2B3ZkzBnHxGEJmllq9DCHo6CeBjqZARZ%2BWnyAzRtRrX6b5rQ6fwSFBSEhGyT37gCxKc10gbokCdvifp7tylNxmezHMCv5Y1CY39Tng7LWWaLXTMN4a9qDaHNYc3rhWQxjkZcoz4%2BgUVnEwN5n%2FNabHHGg1PdOdIXGXZqzdY1U2O9E%2B76OfrxQ5rF5g2iMg7u%2BqVb6lpNFeBywAY4fgQ0k08LJcomUKUHl1NcDMRlnKw%3D%3D&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20230118T153431Z&X-Amz-SignedHeaders=content-type%3Bhost&X-Amz-Expires=35999&X-Amz-Credential=ASIATGEOL5AH7CXDG5RM%2F20230118%2Fap-south-1%2Fs3%2Faws4_request&X-Amz-Signature=77c29e7e2a0b419a4355175ff7eaa598d600285f5015004d270f18780ee24b69",
        "userFileName": "SalesInvoicesAndCreditOrDebitNotes.xlsx"
    }
}

Response Status Codes

HTTP Status Code	Description
201	Triggered ingestion successfully.
400	Bad request.
401	Unauthorized
500	Internal Server Error

Response Schema

Parameter	Data Type	Field Validations	Description
activityId	String	NA	Async activity ID created by Clear.
externalId	String	NA	If the user passes this in the request, it will be returned in the response.
status	String	Enum: ACTIVITY_CREATED, ACTIVITY_QUEUED, ACTIVITY_COMPLETED, ACTIVITY_DISCARDED, SYSTEM_FEEDBACK, UNPLANNED_ERROR	Status of the triggered ingestion activity. ACTIVITY_CREATED - Ingestion triggered, ACTIVITY_QUEUED - Ingestion in progress, ACTIVITY_COMPLETED - Ingestion completed or aborted or error, ACTIVITY_DISCARDED - Ingestion deleted from UI. SYSTEM_FEEDBACK - Any handled error on the file, eg: file corrupted, mandatory header missing, duplicate header, etc. UNPLANNED_ERROR - Any unhandled error. For non activity related errors, this will be null.
errors	Array	NA	Array of Error Objects. If there are no errors, then this will be an empty array.

Error Object

Parameter	Data Type	Field Validations	Description
errorCode	String	NA	Error code. If there is no error code, then this will be null.
errorMessage	String	NA	Error message. If there is no error message, then this will be null.
errorField	String	NA	Error field. If there is no error field, then this will be null.
errorValues	Array	NA	Array of strings. Error values. If there are no error values, then this will be null.
errorResolution	String	NA	Error resolution. If there is no error resolution, then this will be null.

Sample Response (Success)

HTTP Status Code - 201 Created

{
    "activityId": "50d67b1e685c498b9accd0c13f550e85",
    "externalId": null,
    "status": "ACTIVITY_CREATED",
    "errors": []
}

Sample Response (Error)

HTTP Status Code - 401 Unauthorized

{
    "activityId": null,
    "externalId": null,
    "status": null,
    "errors": [
        {
            "errorCode": "AUTHORIZATION_FAILED",
            "errorMessage": "Invalid Auth Token",
            "errorField": null,
            "errorValues": null,
            "errorResolution": null
        }
    ]
}

API Validations

Currently there are no known validations.

API Constraints

Currently there are no known constraints.