Get Pre-signed URL

Generates a presigned URL for uploading files to S3.

Request Method

GET

Request URL

{{base_url}}/one-integration/action/pre-sign

Request Headers

Parameter	Data Type	Field Validations	Description
x-clear-auth-token	String	NA	Mandatory. Authentication token
x-integration-id	String	36 length UUID (provided by Cleartax)	Mandatory. Integration identifier

Request Path Params

There will be no path parameters body for this API.

Request Query Params

Parameter	Data Type	Field Validations	Description
filename	String	NA	Mandatory. Name of the file to upload with its file extension. Allowed extensions: csv, xlsx, xls, zip File extension should match the file content type or mime type.

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.
401	Authentication failed
403	Forbidden
400	The request is invalid or missing required parameters
406	Returned when the request parameters are invalid or cannot be processed in the expected format.
500	Something went wrong on the server.

Response Schema

Parameter	Data Type	Field Callouts	Description
status	Integer	Always returned	HTTP status code of the response (e.g., 200 for success).
success	Boolean	Always returned	Indicates whether the request was successful (true or false). If this is true, then the result object will have a file upload URL.
message	String	Always returned	Human-readable message describing the result (e.g., "generated pre-sign url successfully").
result	Object	Null on error	Contains the presigned URL details. See Result Object below.
error	Object/ Null	Null on success	Error details if the request fails, null if there is no error.
metadata	Object/ Null	Always null for this API	This will always be null.

Result Object

Parameter	Data Type	Field Callouts	Description
status	String	HTTP status text (e.g., "OK", "BAD_REQUEST")	Status of the operation (e.g., "OK").
uploadUrl	String	URL expires in 1 hour (3600 seconds)	The generated presigned URL. This will be used in below APIs later: Upload File to Storage (Step 2) Create Ingestion Activity (Step 3)

Error Object

Parameter	Data Type	Field 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 'GET' \
'https://api-sandbox.clear.in/one-integration/action/pre-sign?filename=purchase.csv' \
  -H 'accept: */*' \
  -H 'x-clear-auth-token: your-access-token' \
  -H 'x-integration-id: your-integration-id'

Response Body

{
  "status": 200,
  "success": true,
  "message": "generated pre-sign url successfully",
  "result": {
    "status": "OK",
    "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/fb9ce29e-72ce-4661-8d34-c1e065502cb1/data_extraction/85899214-187b-4ca5-9d53-f89a83f955ba/abc.csv?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20260208T121803Z&X-Amz-SignedHeaders=content-type%3Bhost&X-Amz-Expires=3599&X-Amz-Credential=AKIATGEOL5AH262NFI54%2F20260208%2Fap-south-1%2Fs3%2Faws4_request&X-Amz-Signature=539d9fe32eb5cc7abf8afeb5916cd8f8261629a9207d21d58cb826b47d6773fc"
  },
  "error": null,
  "metadata": null
}

Sample Error - HTTP Status Code 406

Request cURL

curl -X 'GET' \
  'https://api-sandbox.clear.in/one-integration/action/pre-sign?filename=abc' \
  -H 'accept: */*' \
  -H 'x-clear-auth-token: your-access-token' \
  -H 'x-integration-id: your-integration-id'

Response Body

{
  "status": 406,
  "success": false,
  "message": "ERROR",
  "result": null,
  "error": {
    "code": "406",
    "message": "Invalid file extension. Allowed extensions: csv, xlsx, xls, zip",
    "validationErrors": null
  },
  "metadata": null
}

Sample Error - HTTP Status Code 401

Request cURL

curl -X 'GET' \
  'https://api-sandbox.clear.in/one-integration/action/pre-sign?filename=sales.csv' \
  -H 'accept: */*' \
  -H 'x-clear-auth-token: invalid-access-token' \
  -H 'x-integration-id: your-integration-id'

Response Body

UNAUTHORIZED

API Validations

Filename cannot be empty.

API Constraints

Once a pre-signed URL is generated, it will be valid for only 1 hour.