CSV to XML API Documentation¶

Overview¶

The CSV to XML API converts CSV data into a well-structured XML document.
It supports optional headers and customizable XML formatting through request headers.
The API can be used in three modes:

Body Mode (Synchronous) — Send CSV content directly in the request body.
URL Mode (Asynchronous) — Provide a remote file URL for processing.
File Mode (Asynchronous) — Provide an uploaded file reference for processing.

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

Endpoint (POST)¶

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

Headers¶

Header	Type	Required	Description	Default
`x-api-key`	string	Yes	Your API key for authentication	—
`x-source-type`	string	No	Input source type: `body`, `url`, or `file`	`body`
`x-has-header`	string	No	`"0"`, `"false"`, or `"no"` to treat CSV as having no header	`"true"`
`x-delimiter`	string	No	Custom CSV delimiter (e.g., `,`, `;`, `\|`)	`,`
`x-root-name`	string	No	Root XML element name	`"root"`
`x-row-name`	string	No	Row XML element name	`"row"`
`x-tab-space`	integer	No	Number of spaces for indentation	`2`

Accepted File Extensions¶

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

Input Example (Body Mode)¶

Headers

x-source-type: body
x-has-header: true
x-root-name: employees
x-row-name: employee

Body

name,age,department
Alice,30,Engineering
Bob,25,Marketing

Input Example (URL Mode)¶

Headers

x-source-type: url

Body

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

Input Example (File Mode)¶

Headers

x-source-type: file

Body

{
  "file": "user123/uploads/upl_abc123/employees.csv"
}

Example Request¶

Synchronous (Body Input)¶

curl -X POST "https://api.apidatatools.com/csv-to-xml-api" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-source-type: body" \
  -H "x-root-name: employees" \
  -H "x-row-name: employee" \
  -d 'name,age,department
Alice,30,Engineering
Bob,25,Marketing'

Asynchronous (Remote File URL)¶

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

Asynchronous (Input File)¶

curl -X POST "https://api.apidatatools.com/csv-to-xml-api" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-source-type: file" \
  -d '{"file": "user123/uploads/upl_abc123/employees.csv"}'

Example Response¶

Successful (Body Mode)¶

Status: 200 OK

{
  "request_id": "b2f1a3c4-5678-9abc-def0-1234567890ab",
  "status": "success",
  "file": "https://downloads.apidatatools.com/apidatatools_convert_abcdef123456.xml",
  "preview": "<?xml version=\"1.0\" encoding=\"utf-8\"?>\n<employees>\n  <employee>\n    <name>Alice</name>\n    <age>30</age>\n    <department>Engineering</department>\n  </employee>\n  <employee>\n    <name>Bob</name>\n    <age>25</age>\n    <department>Marketing</department>\n  </employee>\n</employees>"
}

Async Job Accepted (URL or File Mode)¶

Status: 202 Accepted

{
  "status": "accepted",
  "job_id": "job_123e4567-e89b-12d3-a456-426614174000",
  "status_url": "https://api.apidatatools.com/jobs/job_123e4567-e89b-12d3-a456-426614174000",
  "request_id": "b2f1a3c4-5678-9abc-def0-1234567890ab"
}

Error Handling¶

Error Code	HTTP Status	Description	Example
`INVALID_CSV`	400	CSV input is empty or cannot be parsed	`{"status":"error","error":"INVALID_CSV","details":{"message":"Empty CSV input."}}`
`CSV_TO_XML_CONVERSION_FAILED`	400	Failed to convert CSV rows to XML	`{"status":"error","error":"CSV_TO_XML_CONVERSION_FAILED","details":{"message":"Failed to convert CSV rows to dict for XML."}}`
`CSV_TO_XML_SERIALIZATION_FAILED`	400	Failed to serialize XML output	`{"status":"error","error":"CSV_TO_XML_SERIALIZATION_FAILED","details":{"message":"Failed to serialize CSV to XML."}}`
`INVALID_URL`	400	Invalid or missing URL in async mode	`{"status":"error","error":"INVALID_URL","details":{"message":"Missing or invalid 'url'."}}`
`URL_UNREACHABLE`	400	Provided URL could not be reached	`{"status":"error","error":"URL_UNREACHABLE","details":{"message":"Could not reach URL"}}`
`URL_NOT_OK`	400	Remote URL returned non-200 status	`{"status":"error","error":"URL_NOT_OK","details":{"message":"URL returned HTTP 404, expected 200."}}`
`INVALID_FILE`	400	Missing or invalid file path in file mode	`{"status":"error","error":"INVALID_FILE","details":{"message":"Missing or invalid 'file'."}}`
`INVALID_FILE_EXTENSION`	400	File extension not allowed	`{"status":"error","error":"INVALID_FILE_EXTENSION","details":{"message":"Invalid or unsupported file extension"}}`
`FILE_UNAVAILABLE`	400	File not found or inaccessible	`{"status":"error","error":"FILE_UNAVAILABLE","details":{"message":"Could not access file"}}`
`FILE_TOO_LARGE`	413	File exceeds plan limit	`{"status":"error","error":"FILE_TOO_LARGE","details":{"message":"File exceeds plan limit."}}`
`PAYLOAD_TOO_LARGE`	413	Request body exceeds allowed size	`{"status":"error","error":"PAYLOAD_TOO_LARGE","details":{"message":"Request body exceeds limit"}}`
`UNKNOWN_FUNCTION`	404	Invalid endpoint	`{"status":"error","error":"UNKNOWN_FUNCTION","details":{"message":"Unsupported API endpoint."}}`
`INTERNAL_ERROR`	500	Unexpected internal 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 returned in the 202 Accepted response.

Endpoint:

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

Example Status Response for Async¶

Queued

{
  "job_id": "job_123e4567-e89b-12d3-a456-426614174000",
  "status": "queued",
  "created_at": 1712345678,
  "updated_at": 1712345678,
  "message": "Your job is being processed.",
  "retry_after": 2
}

Success

{
  "job_id": "job_123e4567-e89b-12d3-a456-426614174000",
  "status": "success",
  "created_at": 1712345678,
  "updated_at": 1712345690,
  "result": {
    "request_id": "b2f1a3c4-5678-9abc-def0-1234567890ab",
    "status": "success",
    "file": "https://downloads.apidatatools.com/apidatatools_convert_abcdef123456.xml",
    "preview": "<?xml version=\"1.0\" encoding=\"utf-8\"?>\n<root>...</root>"
  }
}

Failed

{
  "job_id": "job_123e4567-e89b-12d3-a456-426614174000",
  "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 CSV input via body, URL, or uploaded file.
For asynchronous jobs, always use the status_url to poll job completion.
The XML output is automatically uploaded to a secure storage location and returned as a downloadable link.
The preview field contains a truncated XML snippet (up to 100 KB).
Ensure correct x-source-type header:
body → synchronous
url or file → asynchronous
For CSVs without headers, set x-has-header: 0 to auto-generate column names (column_1, column_2, ...).
Invalid XML tag characters in column names are automatically sanitized.
The API enforces plan-based limits for body size and file size.
All responses include a unique request_id for traceability.