API Documentation


Getting Started

We provide access to the Conversion Tools services via the HTTP-based REST API using the token authentication. API request and response are formatted in JSON.

Previous API version documentation is still available at the link and is deprecated. Access to it will be closed on 30.09.2018.


Authentication

When account is created we generate the API Token for accessing the Conversion Tools REST API.

API Token can be found at your Profile.

API Token should be passed to HTTP request in the Authorization HTTP header with the Bearer authentication scheme as follows:

Authorization: Bearer <API Token>

The following sample request checking the access to the Conversion Tools REST API:


curl -sSX GET https://api.conversiontools.io/v1/ \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <API Token>"


API URL

Conversion Tools REST API is available at:

https://api.conversiontools.io/v1 /

API Requests

API Request should contain the following components:

  • The HTTP method, one of GET or POST
  • Authorization HTTP header with API Token
  • Content-Type HTTP header with type application/json
  • A JSON request body which depends on the API command, see list of API commands below

The folllowing sample API request creates new conversion task:


curl -sSX POST https://api.conversiontools.io/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <API Token>" \
  -d '{
  "type": "convert.website_to_image",
  "options": {
    "url": "http://google.com",
    "image_format": "jpg"
  }
}'


API Response

General format of the API response has error field and some optional <data>:

{
  "error": "<error text>",
  <data>
}

In case of success, <error text> will be empty (null), for example:

{
  "error": null,
  "task_id": "4147c475ffe94ec8a11aff9a6a8f437a"
}

In case of error, <error text> will contain the error description, for example:

{
  "error": "Bad request"
}

API Commands

File conversion process consists of the following 4 steps:

  1. Upload file to the server (optional step when URL is provided)
  2. Run conversion task
  3. Get conversion task status
  4. Download the result file

Step 1. Upload file to the Conversion Tools Server

In case when you providing the file by Internet URL - start with a Step 2.

For file upload use a HTTP POST file upload request with the Content-Type: multipart/form-data header.

See sample request below.


Request:

POST https://api.conversiontools.io/v1 /files

Headers:

Authorization: Bearer <API Token>
Content-Type: multipart/form-data

Input parameters:

file (required) A file reference

Response:

Success response will contain file_id field, which contains the identifier of the uploaded file:

{
  "error": null,
  "file_id": "be87de1a680c4451a49a72df3fecd3fd"
}

This file_id value should be used in the following step (Run conversion task).


Sample request using curl:


curl -sSX POST https://api.conversiontools.io/v1/files \
  -H "Authorization: Bearer <API Token>" \
  -F "file=@/home/user/Desktop/test.xml"

Please note: -F parameter of curl automatically adding header Content-Type: multipart/form-data to the request.


Step 2. Run conversion task

Request:

POST https://api.conversiontools.io/v1 /tasks

Headers:

Authorization: Bearer <API Token>
Content-Type: application/json

Input parameters:

type (required) Conversion type, for example convert.website_to_pdf. See list of available conversion types.
options (required) Set of options, different for every conversion task, see the tables below.

options parameters generic for every conversion task:

file_id (required, when converting the file uploaded to the server) For conversions which require a file to be uploaded, this is the file_id returned by POST /files request (from Step 1).
url (required, when converting the file from the Internet by link) For conversions which accepts file by URL, this is a place to put it.

options parameters specific per conversion task:

Please click on the conversion type to see the list of available options.

convert.website_to_pdf - Convert HTML Page to PDF
Parameter Required Possible values
file_id (required, when converting the uploaded file) file_id of the file to convert
url (required, when converting the file from url) Internet URL of the file to convert
orientation (optional) Landscape
Portrait
pagesize (optional) A4
B5
Letter
colormode (optional) colored
grayscale
background (optional) yes
no
images (optional) yes
no
javascript (optional) yes
no

For optional parameters the default value highlighted in bold text.

convert.ms_office_to_pdf - Convert MS Office (DOC, PPT) to PDF
Parameter Required Possible values
file_id (required) file_id of the file to convert

For optional parameters the default value highlighted in bold text.

convert.image_to_pdf - Convert Image to PDF
Parameter Required Possible values
file_id (required) file_id of the file to convert
orientation (optional) Landscape
Portrait

For optional parameters the default value highlighted in bold text.

convert.website_to_image - Make Website Snapshot
Parameter Required Possible values
url (required) Internet URL of the file to convert
image_format (optional) jpg
png
images (optional) yes
no
javascript (optional) yes
no

For optional parameters the default value highlighted in bold text.

convert.html_table_to_csv - Convert HTML Table to CSV
Parameter Required Possible values
file_id (required, when converting the uploaded file) file_id of the file to convert
url (required, when converting the file from url) Internet URL of the file to convert
delimiter (optional) comma
semicolon
vertical_bar
tabulation

For optional parameters the default value highlighted in bold text.

convert.excel_to_pdf - Convert Excel to PDF
Parameter Required Possible values
file_id (required) file_id of the file to convert
orientation (optional) Landscape
Portrait

For optional parameters the default value highlighted in bold text.

convert.excel_to_html - Convert Excel to HTML
Parameter Required Possible values
file_id (required) file_id of the file to convert

For optional parameters the default value highlighted in bold text.

convert.excel_to_csv - Convert Excel to CSV
Parameter Required Possible values
file_id (required) file_id of the file to convert
delimiter (optional) comma
semicolon
vertical_bar
tabulation

For optional parameters the default value highlighted in bold text.

convert.ods_to_csv - Convert OpenOffice Calc (ODS) to CSV
Parameter Required Possible values
file_id (required) file_id of the file to convert
delimiter (optional) comma
semicolon
vertical_bar
tabulation

For optional parameters the default value highlighted in bold text.

convert.csv_to_excel - Convert CSV to Excel
Parameter Required Possible values
file_id (required) file_id of the file to convert
delimiter (optional) comma
semicolon
vertical_bar
tabulation

For optional parameters the default value highlighted in bold text.

convert.csv_to_xml - Convert CSV to XML
Parameter Required Possible values
file_id (required) file_id of the file to convert
delimiter (optional) comma
semicolon
vertical_bar
tabulation
header (optional) Use first line of the CSV file as a columns header:
yes
no

For optional parameters the default value highlighted in bold text.

convert.xml_to_csv - Convert XML to CSV
Parameter Required Possible values
file_id (required) file_id of the file to convert
delimiter (optional) comma
semicolon
vertical_bar
tabulation

For optional parameters the default value highlighted in bold text.

convert.xml_to_excel - Convert XML to Excel
Parameter Required Possible values
file_id (required) file_id of the file to convert
delimiter (optional) comma
semicolon
vertical_bar
tabulation

For optional parameters the default value highlighted in bold text.

convert.pdf_to_text - Convert PDF to TEXT
Parameter Required Possible values
file_id (required) file_id of the file to convert

For optional parameters the default value highlighted in bold text.


The folllowing sample API request creates new conversion task:


curl -sSX POST https://api.conversiontools.io/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <API Token>" \
  -d '{
  "type": "convert.website_to_image",
  "options": {
    "url": "http://google.com",
    "image_format": "jpg"
  }
}'


Response:

{
  "error": "<error text>",
  "task_id": "<task_id>"
}

In case of error, <error text> will be any not null text value, it will contain the description of error.

{
  "error": "Bad type",
}

In case of success, it will return <task_id>. You should use Get conversion task status request to find out when conversion task will be finished.

{
  "error": null,
  "task_id": "4147c475ffe94ec8a11aff9a6a8f437a"
}

Step 3. Get conversion task status

You should perform this check in a loop, until task will be finished (see status field).

Important! Please send this request not more often than every 5-10 seconds.

Request:

GET https://api.conversiontools.io/v1 /tasks/<task_id>

Headers:

Authorization: Bearer <API Token>
Content-Type: application/json

URL parameters:

task_id (required) This is the task_id returned in the previous step.

The folllowing sample API request check the conversion task status:


curl -sSX GET https://api.conversiontools.io/v1/tasks/d9b5369bfc6541d88581d4ff80954917 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <API Token>"


Response:

{
  "error": "<error text>",
  "status": "<status>",
  "file_id": "<file_id>"
}

In case of error, <error text> will be any not null text value, it will contain the description of error.

status is one of the following:

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

When status is PENDING or RUNNING, response will have an empty file_id field, for example:

{
  "error": null,
  "status": "RUNNING",
  "file_id": null
}

When status is SUCCESS, response will have file_id of the result file, for example:

{
  "error": null,
  "status": "SUCCESS",
  "file_id": "ce87de1a680c4451a49a72df3fecd3fe"
}

When status is ERROR, response will have error field with description of the error:

{
  "error": "Wrong file format",
  "status": "ERROR",
  "file_id": null
}

When status returned as SUCCESS or ERROR - this means that the conversion process is finished and you can download the result file using file_id (request is described in the next step) or analyse the error.


Step 4. Download result file

Request:

GET https://api.conversiontools.io/v1 /files/<file_id>

Headers:

Authorization: Bearer <API Token>
Content-Type: application/json

URL parameters:

<file_id> (required) This is the file_id of the file you need to download, for example, file_id returned in the previous step get task status.

Response:

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


Available Conversion Types
Conversion Type Description
convert.website_to_pdf Convert HTML Page to PDF
convert.ms_office_to_pdf Convert MS Office (DOC, PPT) to PDF
convert.image_to_pdf Convert Image to PDF
convert.website_to_image Make Website Snapshot
convert.html_table_to_csv Convert HTML Table to CSV
convert.excel_to_pdf Convert Excel to PDF
convert.excel_to_html Convert Excel to HTML
convert.excel_to_csv Convert Excel to CSV
convert.ods_to_csv Convert OpenOffice Calc (ODS) to CSV
convert.csv_to_excel Convert CSV to Excel
convert.csv_to_xml Convert CSV to XML
convert.xml_to_csv Convert XML to CSV
convert.xml_to_excel Convert XML to Excel
convert.pdf_to_text Convert PDF to TEXT

Need help?

If you have any questions regarding the use of the Conversion Tools REST API - feel free to contact us.