API Documentation

Available Conversion Services

The API allows you to access the following Conversion Services:

  • HTML Page to PDF (file upload)
  • HTML Page to PDF (page by URL)
  • HTML Table to CSV (file upload)
  • HTML Table to CSV (page by URL)
  • Make Website Snapshot
  • Excel (XLS) to PDF
  • Excel (XLS) to HTML
  • Excel (XLS) to CSV
  • OpenOffice Calc (ODS) to CSV
  • CSV to Excel (XLS)
  • XML to CSV
  • XML to Excel (XLS)
  • Image to PDF
  • CSV to XML
  • PDF to Text
API URL

API is available at the following URL:

https://conversiontools.io/api/

Check the list of available API commands.

For example, to create a new conversion task:

POST https://conversiontools.io/api/tasks
API Response

API responses are encoded in JSON format:

{ code: <return-code>, message: "<message-text>" }

In case of success, <return-code> will be equal to 0 and <message-text> will contain "OK", example:

{ code: 0, message: "OK" }

In case of error, <return-code> will be a non-zero value and <message-text> will contain more information about the error:

{ code: 1, message: "Error message" }
API Commands

File conversion process consists of the following 4 steps:

  1. Upload file to the server (optional step)
  2. Run the conversion task
  3. Check task status
  4. Download the result file
Step 1. Upload file to the server

In case when the Conversion Service doesn't require to perform file upload (URL is provided), jump to step 2.

For file upload use a regular HTTP POST file upload request (e.g. via a form) with the enctype="multipart/form-data" attribute.

Request:

POST /api/files

Input parameter:

file The file's name.

Response:

{ code: 0, message: "OK", file_id: "55599405d565a6f4d5e86ac3" }

Where code and message are described in API Response, while file_id is an ID that will be used in the following step.

Step 2. Running conversion task

Request:

POST /api/tasks

Input parameters:

type Conversion service type, see conversion tasks names for a full list of possible values.
file_id (optional) For services which require a file to be uploaded, this is the file_id returned in the previous step.
url (optional) For services which require URL, this is a place to put it.
options[] Each conversion has its own set of options, which can be found below (click on the type name to expand details).
convert.html2pdf, convert.url2pdf
Options Possible values
options[orientation] Landscape
Portrait
options[pagesize] A4
B5
Letter
options[colormode] colored
grayscale
options[background] yes
no
options[images] yes
no
options[javascript] yes
no
convert.html2csv, convert.url2csv
Options Possible values
options[delimiter] comma
semicolon
vertical_bar
tabulation
convert.url2img
Options Possible values
options[format] jpg
png
options[images] yes
no
options[javascript] yes
no
convert.xls2pdf
Options Possible values
options[orientation] Landscape
Portrait
convert.xls2html

This conversion has no options.

convert.xls2csv, convert.xml2csv, convert.ods2csv
Options Possible values
options[delimiter] comma
semicolon
vertical_bar
tabulation
convert.xml2xls

This conversion has no options.

convert.img2pdf
Options Possible values
options[orientation] Landscape
Portrait
convert.csv2xls
Options Possible values
options[delimiter] comma
semicolon
vertical_bar
tabulation
convert.csv2xml
Options Possible values
options[delimiter] comma
semicolon
vertical_bar
tabulation
options[header] yes
no
convert.pdf2txt

This conversion has no options.

Response:

{ code: 0, message: "OK", task_id: "55599405d5bbc6f4d5e86ac4" }

Where code and message are described in API Response, while task_id is a UUID that will be used in the following step.

Step 3. Checking task status

You should perform this check in a loop, while waiting between tries for some time (e.g. 10 seconds).

Request:

GET /api/tasks/:task_id

Input parameter:

:task_id This is the task_id returned in the previous step.

Response:

{
  code: 0,
  message: "OK",
  status: "<status>",
  file_id: "55599405d565a6f4d5e86ac3"
}

code and message are described in API Response.

status is one of the following:

  • PENDING - task is queued and waiting to run
  • RUNNING - task is running
  • SUCCESS - finished successfully
  • ERROR - finished with error

If you get SUCCESS or ERROR you should break out of the checking loop. On SUCCESS you will find the result's file ID in file_id (it will be used in the next step).

Step 4. Downloading result file

Request:

GET /api/files/:file_id

Input parameter:

:file_id This is the file_id returned in the previous step.

Response:

The response will contain a Content-Disposition: attachment; HTTP header, which should trigger the file download process (if you're using a browser).

Conversion tasks names
Conversion Service Type Conversion Service Description
convert.html2pdf HTML Page to PDF (file upload)
convert.url2pdf HTML Page to PDF (page by URL)
convert.html2csv HTML Table to CSV (file upload)
convert.url2csv HTML Table to CSV (page by URL)
convert.url2img Make Website Snapshot
convert.xls2pdf Excel (XLS) to PDF
convert.xls2html Excel (XLS) to HTML
convert.xls2csv Excel (XLS) to CSV
convert.ods2csv OpenOffice Calc (ODS) to CSV
convert.csv2xls CSV to Excel (XLS)
convert.xml2csv XML to CSV
convert.xml2xls XML to Excel (XLS)
convert.img2pdf Image to PDF
convert.csv2xml CSV to XML
convert.pdf2txt PDF to Text