Trigger File Ingestion

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

Request Method

POST

Request URL

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

Request Headers

Parameter	Data Type	Field Validations	Description
x-cleartax-auth-token	String	NA	Mandatory. User auth token.
tan	String	NA	Mandatory. TAN of deductor
Content-Type	String	NA	Mandatory. application/json

Request Path Params

Parameter	Data Type	Field Validations	Description
templateType	String	Enum: tds	Type of document. This will always be “tds”.

Request Query Params

There are no query paramaters for this API.

Request Body

Parameter	Data Type	Field Validations	Description
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
templateId	String	NA	Mandatory. Template ID of the file uploaded. For 24Q - 62df9202813e5b2d2d2a2ff5 For 26Q - 62de5622813e5b2d2d2a2f90 For 27Q - 62df93ca813e5b2d2d2a2ff7 For 27EQ - 62df928a813e5b2d2d2a2ff6 For custom upload templates, use the custom upload template ID.
metadata	Object	NA	Mandatory. Contains 3 fields, formtype, financialYear, quarter
tenant	String	Enum: For 24Q - TDSV224Q For 26Q - TDSV226Q For 27Q - TDSV227Q For 27EQ-TDSV227EQ	Mandatory.

Metadata Object

Parameter	Data Type	Field Validations	Description
formType	String	Enum: Form24Q Form26Q Form27Q Form27EQ	Mandatory. Type of the form.
financialYear	String	NA	Mandatory. Financial Year
quarter	String	NA	Mandatory. Quarter

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": {
        "templateId": "62de5622813e5b2d2d2a2f90",
        "metadata": {
            "formType": "Form26Q",
            "quarter": "Q4",
            "financialYear": "2022"
        },
        "tenant": "TDSV226Q"
    },
    "fileInfo": {
        "s3FileUrl": "https://storage.clear.in/v1/ap-south-1/ingestionv2-staging/307a6331-df8b-4bdd-a05a-d18812da0340/TDS/2023/SEPTEMBER/4c503955ff324394a720b2b05a46e4dc/OriginalFileName/4c503955ff324394a720b2b05a46e4dc__1694627112023.TDS-TEST?X-Amz-Security-Token=IQoJb3JpZ2luX2VjEEoaCmFwLXNvdXRoLTEiSDBGAiEA%2FirnhtBmeWgDj8J8vdIX%2BAdbnSQ2DbaRzUCOGAdw%2BdkCIQCwA6eArDVE7A%2BjDk1ALQ%2Bj%2B8B4z%2Fpu9P9p5EKvOQG5mSqCBQgzEAUaDDIxOTM0MTkwNzk4MyIMmylTFDGnf5DiUg1KKt8EKKnlsrOy0jvbiYtXxTh5D%2F%2FqLbIpUaBbZdJSlJSS3kUc6hM3LvDy3XczAYSqagi00OC0Fax7u4YQQ0NxQ8UDc9Y%2Bh0wIuAGNkNHzhNtxQhfqqDKEZIFUuY2pPHcRqHghB3XPG3o06%2B0u2jAIbOSJJHEno4ZtnPp3ICn7wGBjATLBGUNTukL1%2BqFAn7Vi04TK2uyfNbNo24uW8lFNxeYmPyU4aMS3pbqEGYZtFbASk%2B2PYWbmN21vU29oZSDBpg4b3VGAd1aTDdd2JU558Vq2RJt1fWWn5HsV1KAwoRDRByGjMedntZBwyyY4MM1OiBTj%2BKb4%2FI5FL8gn5IcvCsNRkSNLDg%2Br%2Bb8iuBNLKAyp6YEDa7NS2%2B%2FC8aq3PhbAqBQjkzeAhJZWDGuYmjJKbn%2Bkwl1R%2B8Keyt4WqU83qUmKf1zNSxw7HpRdLKKg3XYhs1s7b4ca%2B5Nngc6uo%2Bqv5d5fNWkeeoDrAxiIQ3Ukhb%2FWongyQ6m3O5N5x2YPmO0Z5CL%2BCwx46aD2%2B5nha2DAQXXaLJCR4%2B9WDbeE80Elp4vNueEmQcUKbr1ZKd0bMfAGlhEpNxOd9twXerjKlL5zwk7uyFO2V2FKbg4rHwUeZvfb%2FfTUwZ8lZ9JSR0PBRozCbUkP9kOVnzZAMcBYZqhBe5c6mrD2%2FdVzQkK3vnphy42sW1z%2BSrZ%2FXZUWRStHASAnRHEFVikyWF5U5ue3tbM4Yo3sgwoXkKZyaVYP3PYQ5ymvvso2Im6BPL6sbaDaE5ReZM8ERVU45SHcunB%2BAbwHlhEYAUioTZEb7Guo%2FKTHTVLCSzCo6oeoBjqZAZm9cXMxdHI5EY8AotdCRL%2FMXCpiX9CXpXRLjE4C%2BMtirRzA8EV%2FE0kDJrGA0ncsvHelZ4WgPpNPIP3JMRNGh3yTvKrYcsi%2B9sLTsuIPSMAoHDW71snzhI0IOHBaKcy5EwS1GP7%2FMhqhCm2Ax%2Fdxa2jme%2FmnVO2JgxK%2FSiCVKXPjtwrZ1OdzYyyaA7IcExGZT6szIEiZoHeuCA%3D%3D&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20230913T174512Z&X-Amz-SignedHeaders=content-type%3Bhost&X-Amz-Expires=35999&X-Amz-Credential=ASIATGEOL5AHSMLMZPEM%2F20230913%2Fap-south-1%2Fs3%2Faws4_request&X-Amz-Signature=bdf6fa61008bb41e8b939920f3293f69cb710a92528ce7183d0d4a117bfc072b",
        "userFileName": "TDS-TEST.csv"
    }
}

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.
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.

Sample Response (Success)

HTTP Status Code - 201 Created

{
    "activityId": "9dac682840244551958bc1c2f90d7710",
    "status": "ACTIVITY_CREATED",
    "errors": []
}

Sample Response (Error)

HTTP Status Code - 401 Unauthorized

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

API Validations

Currently there are no known validations.

API Constraints

Currently there are no known constraints.