Excel to CSV API Documentation¶

Overview¶

The Excel to CSV API converts Excel files (.xls or .xlsx) into CSV format.
It supports multiple sheets, custom delimiters, and header configuration.
If multiple sheets are present, the output CSV includes section markers for each sheet.

This API supports:

Synchronous processing (direct file upload via body)
Asynchronous processing (remote file URL or uploaded file reference)

Base URL:
https://api.apidatatools.com/excel-to-csv-api

Endpoint (POST)¶

POST https://api.apidatatools.com/excel-to-csv-api

Headers¶

Header	Description	Example
`Content-Type`	Must be `application/octet-stream` for binary Excel uploads	`application/octet-stream`
`x-source-type`	Defines input mode: `body`, `url`, or `file`	`body`
`x-has-header`	Indicates if Excel has column headers (`1`, `true`, `yes`) or not (`0`, `false`, `no`)	`true`
`x-delimiter`	CSV delimiter character	`,`
`x-sheet-name`	Optional sheet name to extract	`Sheet1`
`x-sheet-index`	Optional sheet index (integer)	`0`
`x-api-key`	Your API key for authentication	`abcd1234xyz`

Accepted File Extensions¶

.xls, .xlsx

Input Example (Body Mode)¶

Binary Excel file uploaded directly in the request body.

Headers:

Content-Type: application/octet-stream
x-source-type: body
x-has-header: true
x-delimiter: ,
x-api-key: YOUR_API_KEY

Body:
Binary content of an Excel file.

Input Example (URL Mode)¶

Used for asynchronous processing of a remote Excel file.

Headers:

Content-Type: application/json
x-source-type: url
x-has-header: true
x-delimiter: ,
x-api-key: YOUR_API_KEY

Body:

{
  "url": "https://example.com/data.xlsx"
}

Input Example (File Mode)¶

Used for asynchronous processing of a previously uploaded Excel file stored on S3.

Headers:

Content-Type: application/json
x-source-type: file
x-has-header: true
x-delimiter: ,
x-api-key: YOUR_API_KEY

Body:

{
  "file": "user123/uploads/data.xlsx"
}

Example Request¶

Synchronous (Body Input)¶

POST https://api.apidatatools.com/excel-to-csv-api
Content-Type: application/octet-stream
x-source-type: body
x-has-header: true
x-delimiter: ,
x-api-key: YOUR_API_KEY

<binary Excel file data>

Asynchronous (Remote File URL)¶

POST https://api.apidatatools.com/excel-to-csv-api
Content-Type: application/json
x-source-type: url
x-has-header: true
x-delimiter: ,
x-api-key: YOUR_API_KEY

{
  "url": "https://example.com/data.xlsx"
}

Asynchronous (Input File)¶

POST https://api.apidatatools.com/excel-to-csv-api
Content-Type: application/json
x-source-type: file
x-has-header: true
x-delimiter: ,
x-api-key: YOUR_API_KEY

{
  "file": "user123/uploads/data.xlsx"
}

Example Response¶

Successful (Body Mode)¶

{
  "request_id": "b7f3c2e1-9a4b-4c2f-8b7e-1a2b3c4d5e6f",
  "status": "success",
  "file": "https://downloads.apidatatools.com/apidatatools_convert_abc123.csv",
  "preview": "column_1,column_2,column_3\nvalue1,value2,value3\n..."
}

Async Job Accepted¶

{
  "status": "accepted",
  "job_id": "job-1234567890",
  "status_url": "https://api.apidatatools.com/jobs/job-1234567890",
  "request_id": "b7f3c2e1-9a4b-4c2f-8b7e-1a2b3c4d5e6f"
}

Error Handling¶

Error Code	Description	Example Response
`INVALID_EXCEL_CONTENT_TYPE`	Input is not valid Excel bytes	`{"status":"error","error":"INVALID_EXCEL_CONTENT_TYPE","details":{"message":"Excel content must be raw bytes."}}`
`EXCEL_READ_FAILED`	Failed to read Excel file	`{"status":"error","error":"EXCEL_READ_FAILED","details":{"message":"Failed to read Excel file."}}`
`INVALID_BODY_ENCODING`	Failed to decode Base64 body	`{"status":"error","error":"INVALID_BODY_ENCODING","details":{"message":"Failed to base64-decode binary body."}}`
`EMPTY_BODY`	Request body is empty	`{"status":"error","error":"EMPTY_BODY","details":{"message":"Request body is empty."}}`
`FILE_TOO_LARGE`	File exceeds plan limit	`{"status":"error","error":"FILE_TOO_LARGE","details":{"message":"File exceeds plan limit."}}`
`INVALID_URL`	Invalid or missing URL	`{"status":"error","error":"INVALID_URL","details":{"message":"Missing or invalid 'url'."}}`
`URL_UNREACHABLE`	Could not reach remote file	`{"status":"error","error":"URL_UNREACHABLE","details":{"message":"Could not reach URL."}}`
`URL_NOT_OK`	Remote file returned non-200 status	`{"status":"error","error":"URL_NOT_OK","details":{"message":"URL returned HTTP 404, expected 200."}}`
`INVALID_FILE_EXTENSION`	Unsupported file extension	`{"status":"error","error":"INVALID_FILE_EXTENSION","details":{"message":"Invalid or unsupported file extension."}}`
`INVALID_SOURCE_TYPE`	Invalid source type header	`{"status":"error","error":"INVALID_SOURCE_TYPE","details":{"message":"Must be 'url' or 'file'."}}`
`INTERNAL_ERROR`	Unexpected server error	`{"status":"error","error":"INTERNAL_ERROR","details":{"message":"Failed to process your request"}}`

Async Job Status¶

To check the status of an asynchronous job, use:

GET https://api.apidatatools.com/jobs/{job_id}

Example Status Response for Async¶

Queued¶

{
  "job_id": "job-1234567890",
  "status": "queued",
  "created_at": 1712345678,
  "updated_at": 1712345678,
  "message": "Your job is being processed.",
  "retry_after": 2
}

Success¶

{
  "job_id": "job-1234567890",
  "status": "success",
  "created_at": 1712345678,
  "updated_at": 1712345789,
  "result": {
    "request_id": "b7f3c2e1-9a4b-4c2f-8b7e-1a2b3c4d5e6f",
    "status": "success",
    "file": "https://downloads.apidatatools.com/apidatatools_convert_abc123.csv",
    "preview": "column_1,column_2,column_3\nvalue1,value2,value3\n..."
  }
}

Failed¶

{
  "job_id": "job-1234567890",
  "status": "failed",
  "created_at": 1712345678,
  "updated_at": 1712345789,
  "error": {
    "code": "EXCEL_READ_FAILED",
    "message": "Failed to read Excel file.",
    "details": {"message": "Invalid sheet index"}
  }
}

Notes for Developers¶

The API automatically detects multiple sheets and merges them with section headers.
Use x-sheet-name or x-sheet-index to extract a specific sheet.
x-has-header controls whether column names are taken from Excel or auto-generated.
x-delimiter customizes CSV output (default is comma).
For large files or remote sources, prefer asynchronous mode (x-source-type: url or file).
Every response includes a unique request_id for tracking.
Async jobs can be monitored via the /jobs/{job_id} endpoint.
Output files are stored temporarily and accessible via the returned download URL.