Get Ingestion Activity Status

Check the status of a previously submitted ingestion workflow.

Request Method

GET

Request URL

{{base_url}}/one-integration/workflow/status

Request Headers

Parameter	Data Type	Field Validations	Description
x-clear-auth-token	String	MinLength:1	Mandatory. Authentication token
x-integration-id	String	MinLength:1	Mandatory. Integration identifier

Request Path Params

There are no request path params.

Request Query Params

Parameter	Data Type	Field Validations	Description
taskId	String	MinLength:1	Mandatory. Task ID returned from the ingestion API

Request Body

There will be no request body for this API.

Response Status Codes

HTTP Status Code	Description
200	Request processed successfully and response returned.
400	The request is invalid or missing required parameters.
403	User not authorized.
500	Something went wrong on the server.

Response Schema

Parameter	Data Type	Field Validations	Description
status	Integer	Always 200 on success	HTTP status code of the response (e.g., 200 for success).
success	Boolean	Always true on success	Indicates whether the request was successful (true or false).
message	String	Contains taskId in message	Human-readable message describing the result.
result	Object/Null	Null if task not found	Contains the detailed result data. If status is 200, the result will be present. For non-200 this will be null.
error	Object/Null	Null on success	Error object containing code, message, and optional validationErrors array. Only populated when non-200 status. If status is 200, then this will null even if the Workflow processing failures.
metadata	Object/Null	Always null for this API	not applicable for this endpoint.

Result Object

Parameter	Data Type	Field Callouts	Description
workflowStatus	String	ENUM: CREATED, PROCESSING, SUCCESS, FAILED	High-level status of the workflow execution. End states are : SUCCESS, FAILED CREATED: Workflow has been created and queued. PROCESSING: Processing of workflow is under execution. SUCCESS: Workflow status is SUCCESS if all stages are SUCCESS or PARTIAL_SUCCESS. FAILED: Processing failed with errors.
taskId	String	Matches TaskId from create API	Unique identifier of the async task
activityStatusList	List	One entry per stage/template combination	List of Activity Status objects showing status for each processing stage. See Activity Status Object below.
message	String	NA
urlsToNotify	List	For callback integrations	List of webhook URLs that were notified upon completion (empty if no callbacks configured).
preSignedUrls	List	For output file downloads	List of presigned URLs for downloading generated output files (empty if no outputs).
generatedURLs	List	For report downloads	List of URLs for generated reports or processed files (empty if none).

Activity Status Object

Parameter	Data Type	Field Callouts	Description
stage	String	ENUM: TRANSFORMATION, INGESTION, SYSTEM	The stage of processing (e.g., INGESTION, TRANSFORMATION,SYSTEM). INGESTION can be 0 or n (number of ingestionTemplate) SYSTEM can be 0 or 1. TRANSFORMATION can be 0 or 1.
ingestionTemplate	String	ingestionTemplate	Template name used for processing (e.g., PURCHASE). If stage is non INGESTION, then this will be null.
status	String	ENUM: SUCCESS, FAILURE, PARTIAL_SUCCESS	Status can be SUCCESS or FAILURE or PARTIAL_SUCCESS, in case of INGESTION stage. If some or all records in that template have gone into Validation failure, it will be PARTIAL_SUCCESS. Status can be either SUCCESS or FAILURE, In case of TRANSFORMATION stage. And it will be only FAILURE, in the case of SYSTEM stage.
errorReportPreSign	String / Null	URL expires in 1 hour	Presigned URL for error report (if any errors occurred), null if not applicable. This will be applicable only for INGESTION and TRANSFORMATION stages. For SYSTEM it will be null.
errorMessage	String / Null	Optional	Error message if the status failure, null if success or partial_success.
activityId	String	NA	Optional. Unique identifier for this ingestion activity. This can be ignored.

Sample Request and Response

Sample Success

Request cURL

curl -X GET "https://api-sandbox.clear.in/one-integration/workflow/status?taskId=6988855cffad3510146f7535" \
  -H "x-clear-auth-token: your-access-token" \
  -H "x-integration-id: your-integration-id"

Response Body (Task in Processing State)

{
  "status": 200,
  "success": true,
  "message": "Status fetched successfully 6988a3bc2e0e5e3c6c9aa6da",
  "result": {
    "taskId": null,
    "activityStatusList": null,
    "workflowStatus": "PROCESSING",
    "message": null,
    "urlsToNotify": [],
    "preSignedUrls": [],
    "generatedURLs": []
  },
  "error": null,
  "metadata": null
}

Response Body (Task in Success)

{
  "status": 200,
  "success": true,
  "message": "Status fetched successfully 6988a3bc2e0e5e3c6c9aa6da",
  "result": {
    "taskId": "6988a3bc2e0e5e3c6c9aa6da",
    "activityStatusList": [
      {
        "stage": "INGESTION",
        "ingestionTemplate": "PURCHASE",
        "status": "SUCCESS",
        "errorReportPreSign": null,
        "errorMessage": null,
        "activityId": "b9a5dac0d01241089994b2444f102542"
      }
    ],
    "workflowStatus": "SUCCESS",
    "message": null,
    "urlsToNotify": [],
    "preSignedUrls": [],
    "generatedURLs": []
  },
  "error": null,
  "metadata": null
}

Response Body (Activity Failed)

{
  "status": 200,
  "success": true,
  "message": "Status fetched successfully 6988c9f8b359874b346bbe9c",
  "result": {
    "taskId": "6988c9f8b359874b346bbe9c",
    "activityStatusList": [
      {
        "stage": "INGESTION",
        "ingestionTemplate": "PURCHASE",
        "status": "FAILURE",
        "errorReportPreSign": null,
        "errorMessage": "This is a duplicate file. Data import for this file is already in progress. Please refer import history section for more details.",
        "activityId": "0d03fcd78acb4f8394e19d8f07abf59b"
      },
      {
        "stage": "INGESTION",
        "ingestionTemplate": "PURCHASE",
        "status": "SUCCESS",
        "errorReportPreSign": null,
        "errorMessage": null,
        "activityId": "c6f0f01dfc34413fa70a7d3b830499c5"
      }
    ],
    "workflowStatus": "FAILED",
    "message": "Contact ClearTax support",
    "urlsToNotify": [],
    "preSignedUrls": [],
    "generatedURLs": []
  },
  "error": null,
  "metadata": null
}

Sample Error

Request

curl -X GET "https://api-sandbox.clear.in/one-integration/workflow/status?taskId=invalid-task-id" \
  -H "x-clear-auth-token: your-access-token" \
  -H "x-integration-id: your-integration-id"

Response

{
  "status": 404,
  "success": false,
  "message": "No task found with taskId: 6988a3bc2e0e5e3c6c9aa6d",
  "result": null,
  "error": {
    "code": "404",
    "message": "No Such Element Found",
    "validationErrors": null
  },
  "metadata": null
}

API Validations

Currently there are no known validations.

API Constraints

There are no constraints at API level.