XML to CSV API Documentation¶

Overview¶

The XML to CSV API converts well-formed XML data into a flattened CSV format.
It validates the XML structure, parses it safely, and outputs a downloadable CSV file.
This API supports synchronous conversion (direct body input) and asynchronous processing (remote file URL or uploaded file).

Endpoint (POST)¶

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

Headers¶

Header	Description	Required	Example
`Content-Type`	Must be `application/xml` or `text/plain` depending on input type	Yes	`application/xml`
`x-source-type`	Defines input mode: `body`, `url`, or `file`	Optional (default: `body`)	`x-source-type: url`
`x-api-key`	Your API key for authentication	Yes	`abcd1234xyz`

Accepted File Extensions¶

This tool accepts the following file extensions for URL or file mode:

.xml, .txt, .log

Input Example (Body Mode)¶

<employees>
  <employee>
    <id>1</id>
    <name>John Doe</name>
    <department>Engineering</department>
  </employee>
  <employee>
    <id>2</id>
    <name>Jane Smith</name>
    <department>Marketing</department>
  </employee>
</employees>

Input Example (URL Mode)¶

{
  "url": "https://example.com/data/employees.xml"
}

Input Example (File Mode)¶

{
  "file": "user_uploads/abc123/employees.xml"
}

Example Request¶

Synchronous (Body Input)¶

curl -X POST "https://api.apidatatools.com/xml-to-csv-api" \
  -H "Content-Type: application/xml" \
  -H "x-source-type: body" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '<employees>
  <employee>
    <id>1</id>
    <name>John Doe</name>
    <department>Engineering</department>
  </employee>
  <employee>
    <id>2</id>
    <name>Jane Smith</name>
    <department>Marketing</department>
  </employee>
</employees>'

Asynchronous (Remote File URL)¶

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

Asynchronous (Input File)¶

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

Example Response¶

Successful (Body Mode)¶

{
  "request_id": "req-12345",
  "status": "success",
  "file": "https://downloads.apidatatools.com/apidatatools_convert_abcdef123456.csv",
  "preview": "id,name,department\n1,John Doe,Engineering\n2,Jane Smith,Marketing\n"
}

Async Job Accepted¶

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

Error Handling¶

Error Code	HTTP Status	Description	Example
`INVALID_XML`	400	XML is malformed or cannot be parsed	`{"status":"error","error":"INVALID_XML","details":{"message":"XML parsing failed.","line":5,"column":12}}`
`CSV_CONVERSION_FAILED`	400	XML could not be converted to CSV	`{"status":"error","error":"CSV_CONVERSION_FAILED","details":{"message":"Failed to convert XML to CSV."}}`
`EMPTY_BODY`	400	Request body is empty	`{"status":"error","error":"EMPTY_BODY","details":{"message":"Request body is empty."}}`
`INVALID_BODY_ENCODING`	400	Body could not be decoded from Base64	`{"status":"error","error":"INVALID_BODY_ENCODING","details":{"message":"Failed to base64-decode request body."}}`
`FILE_TOO_LARGE`	413	File exceeds plan limit	`{"status":"error","error":"FILE_TOO_LARGE","details":{"message":"Remote file exceeds plan 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 file cannot be reached	`{"status":"error","error":"URL_UNREACHABLE","details":{"message":"Could not reach URL."}}`
`URL_NOT_OK`	400	Remote file returned non-200 HTTP code	`{"status":"error","error":"URL_NOT_OK","details":{"message":"URL returned HTTP 404, expected 200."}}`
`INVALID_FILE_EXTENSION`	400	File extension not supported	`{"status":"error","error":"INVALID_FILE_EXTENSION","details":{"message":"Extension '.pdf' is not allowed for 'xml-to-csv-api'."}}`
`FILE_UNAVAILABLE`	400	File not found in storage	`{"status":"error","error":"FILE_UNAVAILABLE","details":{"message":"Could not access file."}}`
`INTERNAL_ERROR`	500	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 the status_url provided in the accepted response.

Endpoint¶

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

Example Status Response for Async¶

Queued¶

{
  "job_id": "job-67890",
  "status": "queued",
  "message": "Your job is being processed.",
  "retry_after": 2
}

Success¶

{
  "job_id": "job-67890",
  "status": "success",
  "created_at": 1712345678,
  "updated_at": 1712345690,
  "result": {
    "request_id": "req-12345",
    "status": "success",
    "file": "https://downloads.apidatatools.com/apidatatools_convert_abcdef123456.csv",
    "preview": "id,name,department\n1,John Doe,Engineering\n2,Jane Smith,Marketing\n"
  }
}

Failed¶

{
  "job_id": "job-67890",
  "status": "failed",
  "error": {
    "code": "INVALID_XML",
    "message": "XML parsing failed.",
    "details": {
      "line": 5,
      "column": 12
    }
  }
}

Notes for Developers¶

For large files or remote URLs, use asynchronous mode (x-source-type: url or x-source-type: file) to avoid timeouts.
The request_id is included in every response for tracking and debugging.
The preview field contains the first 100KB of the generated CSV for quick inspection.
The output file is stored securely and expires based on your plan’s retention policy.
Always verify the status_url for async jobs before downloading results.
Ensure that your input XML is well-formed and uses consistent tag structures for predictable CSV flattening.