CSV to JSON API Documentation¶

Overview¶

The CSV to JSON API converts CSV data into structured JSON format.
It supports both synchronous (direct body input) and asynchronous (remote file URL or uploaded file) modes.
The API automatically detects delimiters, handles optional headers, and preserves all field values as strings to avoid data loss.

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

Endpoint (POST)¶

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

Headers¶

Header	Type	Required	Description
`x-api-key`	string	Yes	Your API key for authentication.
`x-source-type`	string	Optional	Input source type. One of: `body`, `url`, `file`. Default is `body`.
`x-has-header`	string	Optional	`"1"` or `"true"` (default) to treat first row as header; `"0"` or `"false"` to treat first row as data.
`x-delimiter`	string	Optional	Custom CSV delimiter (e.g., `,`, `;`, `\t`). If not provided, auto-detected.
`x-tab-space`	integer	Optional	Number of spaces for JSON indentation (default: 2).

Accepted File Extensions¶

Mode	Allowed Extensions
URL / File	`.csv`, `.txt`, `.log`

Input Example (Body Mode)¶

Request Body (text/plain or application/json):

name,age,city
Alice,30,New York
Bob,25,London

Input Example (URL Mode)¶

Request Body (application/json):

{
  "url": "https://example.com/data/sample.csv"
}

Input Example (File Mode)¶

Request Body (application/json):

{
  "file": "user_uploads/upl_1234567890abcdef/sample.csv"
}

Example Request¶

Synchronous (Body Input)¶

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

Headers:

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

Body:

id,name,score
1,John,85
2,Jane,92

Asynchronous (Remote File URL)¶

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

Headers:

x-api-key: YOUR_API_KEY
x-source-type: url

Body:

{
  "url": "https://example.com/files/data.csv"
}

Asynchronous (Input File)¶

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

Headers:

x-api-key: YOUR_API_KEY
x-source-type: file

Body:

{
  "file": "user_uploads/upl_abcdef123456/data.csv"
}

Example Response¶

Successful (Body Mode)¶

Status Code: 200 OK

{
  "status": "success",
  "request_id": "b2f7e9a1-1234-4bcd-9aef-56789abcdef0",
  "file": "https://downloads.apidatatools.com/apidatatools_convert_abc123.json",
  "preview": "[\n  {\n    \"id\": \"1\",\n    \"name\": \"John\",\n    \"score\": \"85\"\n  },\n  {\n    \"id\": \"2\",\n    \"name\": \"Jane\",\n    \"score\": \"92\"\n  }\n]"
}

Async Job Accepted (URL or File Mode)¶

Status Code: 202 Accepted

{
  "status": "accepted",
  "job_id": "job_1234567890abcdef",
  "status_url": "https://api.apidatatools.com/jobs/job_1234567890abcdef",
  "request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Error Handling¶

Error Code	HTTP Status	Description	Example
`INVALID_CSV`	400	CSV content is empty or invalid.	`{"status":"error","error":"INVALID_CSV","details":{"message":"Empty CSV input."}}`
`CSV_TO_JSON_CONVERSION_FAILED`	400	Failed to convert CSV to JSON records.	`{"status":"error","error":"CSV_TO_JSON_CONVERSION_FAILED","details":{"message":"Conversion failed"}}`
`JSON_SERIALIZATION_FAILED`	400	Failed to serialize CSV to JSON.	`{"status":"error","error":"JSON_SERIALIZATION_FAILED","details":{"message":"Serialization error"}}`
`INVALID_URL`	400	Invalid or missing URL in async mode.	`{"status":"error","error":"INVALID_URL","details":{"message":"Missing or invalid 'url'."}}`
`URL_UNREACHABLE`	400	Could not reach the provided URL.	`{"status":"error","error":"URL_UNREACHABLE","details":{"message":"Could not reach URL"}}`
`URL_NOT_OK`	400	URL returned non-200 HTTP 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`	400	Missing or invalid file path.	`{"status":"error","error":"INVALID_FILE","details":{"message":"Missing or invalid 'file'."}}`
`INVALID_FILE_EXTENSION`	400	Unsupported file extension.	`{"status":"error","error":"INVALID_FILE_EXTENSION","details":{"message":"Extension '.exe' is not allowed"}}`
`PAYLOAD_TOO_LARGE`	413	Request body exceeds allowed size.	`{"status":"error","error":"PAYLOAD_TOO_LARGE","details":{"message":"Request body exceeds 5120KB limit for your plan."}}`
`INTERNAL_ERROR`	500	Unexpected server 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¶

Queued / Processing¶

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

Success¶

{
  "job_id": "job_1234567890abcdef",
  "status": "success",
  "created_at": 1712345678,
  "updated_at": 1712345690,
  "result": {
    "request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "status": "success",
    "file": "https://downloads.apidatatools.com/apidatatools_convert_abc123.json",
    "preview": "[{\"id\":\"1\",\"name\":\"John\",\"score\":\"85\"}]"
  }
}

Failed¶

{
  "job_id": "job_1234567890abcdef",
  "status": "failed",
  "created_at": 1712345678,
  "updated_at": 1712345680,
  "error": {
    "code": "INVALID_CSV",
    "message": "Failed to parse CSV.",
    "details": {
      "message": "Error tokenizing data"
    }
  }
}

Notes for Developers¶

The API supports three input modes:
body (synchronous, immediate response)
url (asynchronous, remote file)
file (asynchronous, uploaded file from user storage)
For asynchronous jobs, use the returned status_url to check progress or retrieve results.
The output file is stored temporarily and accessible via a secure download URL.
All responses include a unique request_id for traceability.
Empty or malformed CSV input will trigger an INVALID_CSV error.
The preview field in responses is truncated to approximately 100 KB.