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

ParameterData TypeField ValidationsDescription

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

ParameterData TypeField ValidationsDescription

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

ParameterData TypeField ValidationsDescription

userInputArgs

Object

NA

Mandatory.

User Input Arguments Object

fileInfo

Object

NA

Mandatory.

File Information Object

User Input Arguments Object

ParameterData TypeField ValidationsDescription

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

ParameterData TypeField ValidationsDescription

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

ParameterData TypeField ValidationsDiscriptions

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 CodeDescription

201

Triggered ingestion successfully.

400

Bad request.

401

Unauthorized

500

Internal Server Error

Response Schema

ParameterData TypeField ValidationsDescription

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

ParameterData TypeField ValidationsDescription

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.

Last updated