Overview

Upload catalog files to CleverTap managed storage using a secure, scalable mechanism. The process involves generating pre-signed URLs, uploading the file (single or multipart), and completing the upload when required.

This flow is designed for efficient bulk ingestion of catalog data, such as CSV or XML files. You must reference an existing catalog by its ID or name.

Follow these steps to upload a catalog file:

1. Generate upload URLs using the Get Signed URL API
2. Upload the file using the returned pre-signed URLs
3. Complete the upload using the Complete Multipart API

Method

GET

Base URL

https://in1.api.clevertap.com

Region

Refer Region for more details.

Headers

These headers must be included with every API request to ensure authentication and authorization.

Generate Upload URLs using the Get Signed URL API

Generate pre-signed upload URLs for your catalog file.

Endpoint

GET /v2/catalogs/signedurl

Upload Type

Choose from the upload methods based on the size of the file you want to upload:

GET /v2/catalogs/signedurl?catalogId=123&fileName=products.csv&contentType=text/csv&multiPart=false&[email protected]

{
  "requestId": "550e8400-e29b-41d4-a716-446655440000",
  "catalogId": 123,
  "fileName": "products.csv",
  "multipartUpload": false,
  "uploadId": null,
  "presignedUrls": [
    "https://s3.amazonaws.com/..."
  ],
  "expiresAt": "2023-11-10T18:30:00Z",
  "instructions": "Upload the file using PUT request to the provided URL",
  "createdAt": "2023-11-10T17:30:00Z"
}

Upload File using the Returned Pre-signed URLs

Use the returned pre-signed URLs to upload the file directly to storage.

• Use HTTP PUT requests on each pre-signed URL

• Do not add authentication headers to these requests

• For multipart uploads:

  • Upload each part separately
  • Capture the ETag from each upload response
  • Store partNumber and corresponding ETag

📘

File Upload Guidelines

• Single file uploads are recommended for files under 100 MB
• Multipart uploads should be used for files larger than 100 MB
• Each presigned URL expires after 60 minutes by default
• The generated URLs must be used to upload the file using PUT requests

Complete Multipart Upload using the Complete Multipart API

Complete a multipart upload by submitting the ETags for all uploaded parts. This endpoint finalizes the upload and initiates processing of the file.

Steps for Multipart Upload

Follow these steps to upload a file using the multipart upload process:

1. Call GET /v2/catalogs/signedurl with multiPart=true and totalParts=N to get N presigned URLs
2. Upload each file part using a PUT request to the corresponding presigned URL
3. Collect the ETag from the response header of each part upload
4. Call POST /v2/catalogs/complete-multipart with the requestId and all part ETags
5. The system will finalize the upload and begin processing the file

Endpoint

POST /v2/catalogs/complete-multipart

Query Parameters

The following is the list of query parameters:

Example Request

The following is the sample request:

{
  "requestId": "550e8400-e29b-41d4-a716-446655440001",
  "updatedBy": "[email protected]",
  "parts": [
    {
      "partNumber": 1,
      "etag": "\"33a64df551425fcc55e4d42a148795d9f25f89d4\""
    },
    {
      "partNumber": 2,
      "etag": "\"6821e4a7e3e3d5b4f3e9c8d7b6a5f4e3d2c1b0a9\""
    },
    {
      "partNumber": 3,
      "etag": "\"a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8\""
    },
    {
      "partNumber": 4,
      "etag": "\"b8a7f6e5d4c3b2a1f0e9d8c7b6a5f4e3d2c1b0a9\""
    },
    {
      "partNumber": 5,
      "etag": "\"c9d8e7f6a5b4c3d2e1f0a9b8c7d6e5f4a3b2c1d0\""
    }
  ]
}

Example Response

The following is the sample response:

{
  "requestId": "550e8400-e29b-41d4-a716-446655440001",
  "catalogId": 123,
  "fileName": "large_products.csv",
  "multipartUpload": true,
  "uploadId": "exampleUploadId123",
  "presignedUrls": [],
  "expiresAt": "2023-11-10T18:30:00Z",
  "instructions": "Upload completed successfully. File will be processed shortly.",
  "createdAt": "2023-11-10T17:30:00Z"
}

Response Parameters

The following parameters are returned when the upload completion request is accepted successfully:

📘

Guidelines for Complete Multipart Upload

• Parts must be provided in order by partNumber
• ETags are returned by S3 in the response headers after uploading each part
• The upload must be completed within the expiry time of the presigned URLs

Error Handling

This section lists the errors returned by both the Get Signed URL and Complete Multipart Upload APIs.

Get Signed URL Errors

The following error codes may be returned by this API:

Complete Multipart Upload Errors

The following error codes may be returned by this API: