Excel to JSON API Documentation¶

Overview¶

The Excel to JSON API converts Excel files (.xls or .xlsx) into structured JSON format.
It supports synchronous conversion via direct file upload (body mode) and asynchronous conversion via remote file URL or previously uploaded file (url/file mode).
Each sheet in the Excel file is represented as a JSON object containing an array of rows.

Endpoint (POST)¶

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

Headers¶

Header	Type	Required	Description
`x-source-type`	string	yes	Defines input source type. Must be one of: `body`, `url`, or `file`.
`x-has-header`	string	optional	`"0"`, `"false"`, or `"no"` means no header row. Otherwise, first row is treated as header.
`x-tab-space`	integer	optional	JSON indentation level. Default is `4`.
`x-sheet-name`	string	optional	Specific sheet name to convert.
`x-sheet-index`	integer	optional	0-based sheet index if name not provided.
`x-api-key`	string	yes	`abcd1234xyz`

Accepted File Extensions¶

.xls, .xlsx

Input Example (Body Mode)¶

Binary Excel file content is sent directly in the request body (Base64 encoded if required).

Headers:

x-source-type: body
x-has-header: true
x-tab-space: 2
x-api-key: YOUR_API_KEY

Body:
Binary Excel file data

Input Example (URL Mode)¶

Headers:

x-source-type: url
x-has-header: true
x-api-key: YOUR_API_KEY

Body:

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

Input Example (File Mode)¶

Headers:

x-source-type: file
x-has-header: true
x-api-key: YOUR_API_KEY

Body:

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

Example Request¶

Synchronous (Body Input)¶

POST https://api.apidatatools.com/excel-to-json-api
Content-Type: application/octet-stream
x-source-type: body
x-has-header: true
x-api-key: YOUR_API_KEY
x-tab-space: 4

Body:
Binary Excel file data.

Asynchronous (Remote File URL)¶

POST https://api.apidatatools.com/excel-to-json-api
Content-Type: application/json
x-source-type: url
x-api-key: YOUR_API_KEY

Body:

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

Asynchronous (Input File)¶

POST https://api.apidatatools.com/excel-to-json-api
Content-Type: application/json
x-source-type: file
x-api-key: YOUR_API_KEY

Body:

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

Example Response¶

Successful (Body Mode)¶

{
  "request_id": "req-12345",
  "status": "success",
  "file": "https://downloads.apidatatools.com/apidatatools_convert_abc123.json",
  "preview": "{ \"Sheet1\": [ {\"Name\": \"John\", \"Age\": 30}, ... ] }"
}

Async Job Accepted¶

{
  "status": "accepted",
  "job_id": "job-7890",
  "status_url": "https://api.apidatatools.com/jobs/job-7890",
  "request_id": "req-12345"
}

Error Handling¶

Error Code	HTTP Status	Description	Example
`INVALID_EXCEL_CONTENT`	400	Excel content missing.	`{"status":"error","error":"INVALID_EXCEL_CONTENT","details":{"message":"Excel content is missing."}}`
`INVALID_EXCEL_CONTENT_TYPE`	400	Content must be raw bytes.	`{"status":"error","error":"INVALID_EXCEL_CONTENT_TYPE","details":{"message":"Excel content must be raw bytes downloaded from URL."}}`
`DEPENDENCY_MISSING`	500	Missing pandas dependency.	`{"status":"error","error":"DEPENDENCY_MISSING","details":{"message":"pandas is required for Excel processing."}}`
`EXCEL_READ_FAILED`	400	Failed to read Excel file.	`{"status":"error","error":"EXCEL_READ_FAILED","details":{"message":"Failed to read Excel file."}}`
`EXCEL_TO_JSON_CONVERSION_FAILED`	400	Conversion failed.	`{"status":"error","error":"EXCEL_TO_JSON_CONVERSION_FAILED","details":{"message":"Failed to convert Excel sheets to JSON records."}}`
`JSON_SERIALIZATION_FAILED`	400	JSON serialization failed.	`{"status":"error","error":"JSON_SERIALIZATION_FAILED","details":{"message":"Failed to serialize Excel to JSON."}}`
`INVALID_URL`	400	Invalid or missing URL.	`{"status":"error","error":"INVALID_URL","details":{"message":"URL must be valid http/https."}}`
`URL_UNREACHABLE`	400	URL cannot be reached.	`{"status":"error","error":"URL_UNREACHABLE","details":{"message":"Could not reach URL."}}`
`URL_NOT_OK`	400	URL returned non-200 status.	`{"status":"error","error":"URL_NOT_OK","details":{"message":"URL returned HTTP 404, expected 200."}}`
`FILE_TOO_LARGE`	413	File exceeds plan limit.	`{"status":"error","error":"FILE_TOO_LARGE","details":{"message":"Remote file exceeds plan limit."}}`
`INVALID_FILE_EXTENSION`	400	Unsupported file extension.	`{"status":"error","error":"INVALID_FILE_EXTENSION","details":{"message":"Invalid or unsupported file extension."}}`
`INVALID_SOURCE_TYPE`	400	Must be `url` or `file`.	`{"status":"error","error":"INVALID_SOURCE_TYPE","details":{"message":"Must be 'url' or 'file'."}}`
`INTERNAL_ERROR`	500	Unexpected internal error.	`{"status":"error","error":"INTERNAL_ERROR","details":{"message":"Failed to process your request"}}`

Async Job Status¶

Endpoint:

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

Example Status Response for Async

{
  "job_id": "job-7890",
  "status": "success",
  "created_at": 1712345678,
  "updated_at": 1712345689,
  "result": {
    "request_id": "req-12345",
    "status": "success",
    "file": "https://downloads.apidatatools.com/apidatatools_convert_abc123.json",
    "preview": "{ \"Sheet1\": [ {\"Name\": \"John\", \"Age\": 30}, ... ] }"
  }
}

Other Possible Statuses:

"queued" – Job is waiting to be processed.
"processing" – Job is currently being executed.
"failed" – Job failed; includes error details.
"success" – Job completed successfully.

Notes for Developers¶

This API supports all three modes: body, url, and file.
For asynchronous operations (url or file), a job_id is returned immediately with a status_url to poll job status.
The output file is stored temporarily and accessible via a secure download link.
The JSON output preserves sheet names and row structure for easy downstream processing.