Create Ingestion Activity

Processes uploaded files through transformation and/or ingestion flows based on template configuration.

Request Method

POST

Request URL

{{base_url}}/one-integration/api/v1/ingest

Request Headers

Parameter	Data Type	Field Validations	Description
x-clear-auth-token	String	NA	Mandatory. Authentication token.
Content-Type	String	NA	Mandatory. Must be application/json
x-integration-id	String	NA	Mandatory. Integration identifier

Request Path Params

There are no path parameters for this API.

Request Query Params

There are no query parameters for this API.

Request Body

Parameter	Data Type	Field Validations	Description
fileInfo	List	MinListLength:1	Mandatory. List of File Info objects.
templateType	String	MinLength:1	Mandatory. Template name of the input set. If transformation is not required as defined during onboarding, then only one of the system template names are accepted: SALES, PURCHASE, TDSV2_PR, GENERAL_LEDGER. If transformation is required as defined during onboarding, then the template which was defined during the on-boarding process should be used.
metadata	Object	NA	Optional. Metadata Object.

File Info Object

Parameter	Data Type	Field Validations	Description
uploadUrl	String	MinLength:1	Mandatory. Presign Url is required (with or without signature)
filename	String	NA	Optional. Original filename along with file extension as provided by the user. Default: Will be derived from uploadUrl
fileType	String	NA	Mandatory. Logical identifier used during transformation to distinguish files (e.g., "sales", "purchase", "order") as defined during the on-boarding process. If transformation is not required as defined during onboarding, then still file type should be passed with any string value. If transformation is required as defined during onboarding, then this field is used to identify the schema of the input file by transformation layer and its value will be decided during onboarding.

Metadata Object

Parameter	Data Type	Field Validations	Description
ingestionTemplate	Array	ENUM: PURCHASE, SALES, GENERAL_LEDGER, TDSV2_PR	Optional. Output template names to be ingested after transformation. Default: List of ingestion templates defined during Integration ID generation. If transformation is not required as defined during onboarding, then this is not required as the template type itself will be used. Even if sent, this field will be ignored and ingestion will happen based on the template type. If transformation is required as defined during onboarding, if multiple output templates were selected against a particular 'template Type', and if user wants to now ingest only a subset of those output template types, then the required output template types can be specified here. All other template types defined in onboarding will be ignored for this particular ingestion activity.

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 Callouts	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 on error	Contains the detailed result data.
metadata	Object/Null	Always Null for this API	Pagination metadata, not applicable for this endpoint.
error	Object/Null	Null on success	Error object containing code, message, and optional validationErrors array. Only populated when exceptions occur.

Result Object

Parameter	Data Type	Field Callouts	Description
taskId	String	String (24 chars)	Unique identifier for the asynchronous task created.
status	String	ENUM: CREATED, FAILED	Current status of the task. By default, the first status on creation will be CREATED. FAILED will be terminal states.

Error Object

Parameter	Data Type	Fields Callouts	Description
code	String	Always returned in case of any error	Contains the error code
message	String	Always returned in case of any error	Contains the error message
validationErrors	List	Always null	Always null

Sample Request and Response

Sample Success

Request cURL

curl -X 'POST' \
'https://api-sandbox.clear.in/one-integration/api/v1/ingest' \
-H 'accept: */*' \
-H 'x-clear-auth-token: your-access-token' \
-H 'x-integration-id: your-integration-id' \
-H 'Content-Type: application/json' \
-d '{
  "fileInfo": [
    {
      "uploadUrl": "https://storage.clear.in/v1/ap-south-1/one-integration-staging/85899214-187b-4ca5-9d53-f89a83f955ba/edadb372-d2db-4c95-b44c-057e76be78ef/2026/FEBRUARY/8/42ed2253-59d0-40ea-8a0b-1a853a0f7293/data_extraction/85899214-187b-4ca5-9d53-f89a83f955ba/purchase.csv?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20260208T123944Z&X-Amz-SignedHeaders=content-type%3Bhost&X-Amz-Expires=3599&X-Amz-Credential=AKIATGEOL5AH262NFI54%2F20260208%2Fap-south-1%2Fs3%2Faws4_request&X-Amz-Signature=20d4c01d886aef839165c6668204a3c2c0ac3f4d738297e0a4f1449021fec7b7",
      "fileType":"purchase"
    }
  ],
  "templateType": "PURCHASE"
}'

Request Body

{
  "fileInfo": [
    {
      "uploadUrl": "presignedURL(generated in step 1)",
      "fileType": "sales"
    }
  ],
  "templateType": "CUSTOMER_ORDER_TEMPLATE"
}

Response Body

{
  "status": 200,
  "success": true,
  "message": "Task Created Successfully",
  "result": {
    "taskId": "694a592bad952e42b4eca0da",
    "status": "CREATED"
  },
  "error": null,
  "metadata": null
}

Sample Failure

Request Body

{
  "fileInfo": [
    {
      "uploadUrl": "https://storage.clear.in/v1/me-jeddah-1.oraclecloud.com/integration-sandbox-oci/ftp-magnet3/b002c9a6-e62a-402a-8cfb-88242e23f19e/2025/JULY/f6350e84-f68d-466e-a126-bdd677c4736a/ddfe2185-ed1d-4db4-a9e6-c925c98cb2f6/sales.xlsx",
      "fileType": "sales"
    }
  ],
  "templateType": "CUSTOMER_ORDER_TEMPLATE",
  "metadata": {
    "ingestionTemplate": ["TDSV2_PR"]
  }
}

Response Body

{
    "headers": {},
    "body": {
        "status": "BAD_REQUEST",
        "payload": "Invalid ingestionTemplate: 'TDSV2_PR' for templateType: 'CUSTOMER_ORDER_TEMPLATE'. Allowed: [SALES]",
        "errorResponseId": "b6a8b553-527e-435d-81fb-627df31fd169",
        "statusCode": 400
    },
    "statusCode": "BAD_REQUEST",
    "statusCodeValue": 400
}

Multi-File Ingestion Example

{
   "fileInfo": [
     {
       "uploadUrl": "https://<s3-path>/order_info.csv",
       "fileType": "ORDER"
     },
     {
       "uploadUrl": "https://<s3-path>/customer_info.csv",
       "fileType": "CUSTOMER"
     }
   ],
   "templateType": "CUSTOMER_ORDER_TEMPLATE",
   "metadata": {
     "ingestionTemplate": ["SALES", "PURCHASE"]
   }
 }

API Validations

Currently there are no known validations.

API Constraints

There are no constraints at API level.