JSON to CSV API Documentation¶

Overview¶

The JSON to CSV API converts structured or nested JSON data into a flattened CSV format.
It supports synchronous processing for direct JSON input and asynchronous processing for remote file URLs or uploaded files.
The output is a downloadable CSV file hosted temporarily on the API’s storage.

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

Endpoint (POST)¶

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

Headers¶

Header	Type	Required	Description
`Content-Type`	`application/json`	Yes	Must be `application/json` for body input.
`x-source-type`	`string`	Optional	Defines the input mode: `body`, `url`, or `file`. Defaults to `body`.
`x-api-key`	Your API key for authentication	Yes	`abcd1234xyz`

Accepted File Extensions¶

Mode	Supported Extensions
URL / File	`.json`, `.txt`, `.log`

Input Example (Body Mode)¶

{
  "user": {
    "name": "Alice",
    "age": 30,
    "skills": ["Python", "SQL"]
  },
  "active": true
}

Input Example (URL Mode)¶

{
  "url": "https://example.com/sample.json"
}

Input Example (File Mode)¶

{
  "file": "user_uploads/abc123/sample.json"
}

Example Request¶

Synchronous (Body Input)¶

curl -X POST "https://api.apidatatools.com/json-to-csv-api" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-source-type: body" \
  -d '{"user":{"name":"Alice","age":30,"skills":["Python","SQL"]},"active":true}'

Asynchronous (Remote File URL)¶

curl -X POST "https://api.apidatatools.com/json-to-csv-api" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-source-type: url" \
  -d '{"url":"https://example.com/sample.json"}'

Asynchronous (Input File)¶

curl -X POST "https://api.apidatatools.com/json-to-csv-api" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-source-type: file" \
  -d '{"file":"user_uploads/abc123/sample.json"}'

Example Response¶

Successful (Body Mode)¶

{
  "status": "success",
  "request_id": "d5f2a8b1-9c2f-4a1a-9b7a-1e8b9f2a8c1d",
  "file": "https://downloads.apidatatools.com/apidatatools_convert_abc123.csv",
  "preview": "user_name,user_age,user_skills_0,user_skills_1,active\nAlice,30,Python,SQL,true\n"
}

Async Job Accepted¶

{
  "status": "accepted",
  "job_id": "b7a9e2f1-3c4d-4b5e-9a6f-8b7c9d1e2f3a",
  "status_url": "https://api.apidatatools.com/jobs/b7a9e2f1-3c4d-4b5e-9a6f-8b7c9d1e2f3a",
  "request_id": "f1a2b3c4-d5e6-7890-abcd-ef1234567890"
}

Error Handling¶

Error Code	HTTP Status	Description	Example
`INVALID_JSON`	400	Input JSON is invalid or malformed.	`{"status":"error","error":"INVALID_JSON","details":{"message":"JSON validation failed."}}`
`CSV_CONVERSION_FAILED`	400	Failed to convert JSON to CSV.	`{"status":"error","error":"CSV_CONVERSION_FAILED","details":{"message":"Failed to convert JSON to CSV."}}`
`INVALID_BODY_ENCODING`	400	Body could not be base64-decoded.	`{"status":"error","error":"INVALID_BODY_ENCODING","details":{"message":"Failed to base64-decode request body."}}`
`EMPTY_BODY`	400	Request body is empty.	`{"status":"error","error":"EMPTY_BODY","details":{"message":"Request body is empty."}}`
`PAYLOAD_TOO_LARGE`	413	Request body exceeds plan limit.	`{"status":"error","error":"PAYLOAD_TOO_LARGE","details":{"message":"Request body exceeds limit."}}`
`INVALID_URL`	400	URL is missing or invalid.	`{"status":"error","error":"INVALID_URL","details":{"message":"URL must be valid http/https."}}`
`URL_UNREACHABLE`	400	Remote URL cannot be reached.	`{"status":"error","error":"URL_UNREACHABLE","details":{"message":"Could not reach URL."}}`
`URL_NOT_OK`	400	Remote URL returned non-200 response.	`{"status":"error","error":"URL_NOT_OK","details":{"message":"URL returned HTTP 404, expected 200."}}`
`FILE_TOO_LARGE`	413	File exceeds allowed size.	`{"status":"error","error":"FILE_TOO_LARGE","details":{"message":"File exceeds plan limit."}}`
`INVALID_FILE`	400	File path missing or invalid.	`{"status":"error","error":"INVALID_FILE","details":{"message":"Missing or invalid 'file'."}}`
`INVALID_FILE_EXTENSION`	400	File extension not supported.	`{"status":"error","error":"INVALID_FILE_EXTENSION","details":{"message":"Invalid or unsupported file extension."}}`
`FILE_UNAVAILABLE`	400	File not accessible in storage.	`{"status":"error","error":"FILE_UNAVAILABLE","details":{"message":"Could not access 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¶

Queued / Processing¶

{
  "job_id": "b7a9e2f1-3c4d-4b5e-9a6f-8b7c9d1e2f3a",
  "status": "queued",
  "created_at": 1712345678,
  "updated_at": 1712345678,
  "message": "Your job is being processed.",
  "retry_after": 2
}

Success¶

{
  "job_id": "b7a9e2f1-3c4d-4b5e-9a6f-8b7c9d1e2f3a",
  "status": "success",
  "created_at": 1712345678,
  "updated_at": 1712345690,
  "result": {
    "request_id": "f1a2b3c4-d5e6-7890-abcd-ef1234567890",
    "status": "success",
    "file": "https://downloads.apidatatools.com/apidatatools_convert_xyz.csv",
    "preview": "id,name,age\n1,Alice,30\n"
  }
}

Failed¶

{
  "job_id": "b7a9e2f1-3c4d-4b5e-9a6f-8b7c9d1e2f3a",
  "status": "failed",
  "created_at": 1712345678,
  "updated_at": 1712345680,
  "error": {
    "code": "INVALID_JSON",
    "message": "JSON validation failed.",
    "details": {
      "message": "Expecting property name enclosed in double quotes",
      "line": 1,
      "column": 15
    }
  }
}

Notes for Developers¶

The API supports three input modes:
Body Mode: Direct JSON text in the request body.
URL Mode: Remote JSON file accessible via HTTP/HTTPS.
File Mode: Pre-uploaded file reference from your account storage.
For asynchronous jobs, a job_id and status_url are returned.
Use the status_url to poll job progress.
The output CSV file is temporarily hosted and accessible via the returned file URL.
Each response includes a unique request_id for traceability.
The API automatically flattens nested JSON structures and arrays into CSV columns.