API reference

The base URL is https://xlsconverter.com/v1. The API is part of the API and Enterprise plans. Requests and responses use JSON, except uploads, which are multipart form data.

Authentication

Create a key in the app under API and send it in the Authorization header. Keys are stored hashed and shown once.

Authorization: Bearer xlsc_your_key

Create a conversion

POST /v1/conversions with the fields file (the spreadsheet), target (output format) and any option below. Files up to 5 MB are converted in the same request and return 201. Larger files, or requests with async=1, return 202 and finish in the background with a webhook.

curl -X POST \
  https://xlsconverter.com/v1/conversions \
  -H "Authorization: Bearer $XLSC_KEY" \
  -F "[email protected]" \
  -F "target=csv" \
  -F "options[sheet]=Prices" \
  -F "options[delimiter]=," \
  -F "options[encoding]=utf-8-bom" \
  -F "mode=async"

{
  "id": "6f1c0d8e-2b7a-4d35-9c1e-8a42f7b3d915",
  "status": "queued",
  "source_format": "xlsx",
  "target": "csv",
  "file_name": "supplier-prices.xlsx",
  "size_bytes": 2483912,
  "options": {
    "sheet": "Prices",
    "delimiter": ",",
    "encoding": "utf-8-bom"
  },
  "created_at": "2026-10-10T09:14:22Z",
  "expires_at": null,
  "links": {
    "self": "/v1/conversions/6f1c0d8e-2b7a-4d35-9c1e-8a42f7b3d915",
    "download": "/v1/conversions/6f1c0d8e-2b7a-4d35-9c1e-8a42f7b3d915/download"
  }
}

Get a conversion

GET /v1/conversions/{id} returns the status (queued, running, finished, failed, expired), row count and a download URL.

Download the result

GET /v1/conversions/{id}/download streams the converted file. Results are deleted one hour after the job finishes, after that the endpoint returns 410.

Batches

POST /v1/batches with files[] and target queues every file and returns one conversion per file. Each file counts as one conversion.

Formats and options

Field	Values
`target`	csv, tsv, json, xml, sql, xlsx, xls, ods, pdf, html, md, txt, gsheet
`sheet`	`first` (default), `all`, or a sheet name
`delimiter`	comma, `semicolon`, `tab`, `pipe`
`encoding`	`utf8`, `utf8bom`, `latin1`
`json_shape`	`objects` or `rows`
`sql_dialect`, `sql_table`	`mysql`, `postgresql`, `sqlite` and a table name
`xml_root`, `xml_row`	element names
`orientation`	`landscape` or `portrait` for PDF
`trim`, `dedupe`, `drop_empty_columns`, `merge_sheets`	`1` to enable
`password`	workbook password, used in memory only

GET /v1/formats lists input and output formats without authentication.

Errors

Status	Meaning
401	Missing or unknown API key
402	The plan does not include the API
410	The result was deleted after the retention window
413	The file is larger than the plan allows
422	Unsupported format, unreadable file or wrong password
429	Quota of the billing period used up, or more than 600 requests per minute

Webhooks

Add endpoints in the app. Events conversion.finished and conversion.failed are sent as POST with the header X-XlsConverter-Signature: t=<unix>,v1=<hex>, where v1 is HMAC SHA-256 of t.raw_body with the endpoint secret. Failed deliveries are retried after 1 minute, 5 minutes, 30 minutes and 2 hours.

POST /hooks/xlsconverter HTTP/1.1
Content-Type: application/json
X-XlsConverter-Signature: t=1791710071,v1=5d41402abc4b...

{
  "event": "conversion.finished",
  "delivery_id": "dlv_3Hn7pQ1vXa",
  "created_at": "2026-10-10T09:14:31Z",
  "data": {
    "id": "6f1c0d8e-2b7a-4d35-9c1e-8a42f7b3d915",
    "status": "finished",
    "source_format": "xlsx",
    "target": "csv",
    "rows": 18342,
    "output_size_bytes": 1906455,
    "finished_at": "2026-10-10T09:14:30Z",
    "expires_at": "2026-10-10T10:14:30Z",
    "download_url": "https://xlsconverter.com/v1/conversions/6f1c0d8e-2b7a-4d35-9c1e-8a42f7b3d915/download"
  }
}