Doc Converter Pro Rest Web API

Doc Converter Pro Web Rest API Documentation

How to call our API to convert documents from within your own application

Before you begin you need to have an account with our Doc Converter Pro Online Web App. If you not, please register for an account now. You can test the service for free but for production you will need to sign up for one of our paid plans.

Currently the Doc Converter Pro Web Rest API exposes the following API calls:

1 - API Authorization Call

https://api.docconverter.pro/token - This API call will return an access token valid for 14 days, the method requires 3 parameters:

We strongly recommend storing the token and expiration date in some cache or database and reusing it for each conversion call. Refresh the token just before it expires. Please check the code examples on how to get and use the bearer token.

2 - Convert Document API Call

https://api.docconverter.pro/api/converter/convertdoc - This API call will convert files sent via POST and will return URL/JSON/RawData or post back to a given URL the converted zip or output file.

The input parameters are:

  1. send a file in a FormData (JavaScript) or as MultipartFormDataContent, please see the sample page or other samples for implementation details
  2. template - optionally specify a template name parameter, for instance: 'Convert to HTML5' . This template is used by default if a parameter is not specified. The template name has to be exactly as on your Doc Converter Pro Online templates list. You can create your own custom templates and use it.
  3. returnJson - option to return JSON with a list of converted output file URLs (attention: do not set returnHtml or returnData options if you want to use returnJson)
  4. returnHtml - option to return either a zip file (set it to false) with all the conversion files in it or a single output file (set it to true). By default it's set to 'false' - return a zip file. To return only a HTML file set this option to 'true'.
    Note 1: if you set it to true then only the html file is returned, other files like images or CSS files are not sent. Only the zip file contains all the converted files.
    Note 2: if you split your document into pages or use split by tag feature in the conversion template then API will return a zip file anyway.
  5. returnData - option to return raw octet-stream data, default is 'false' and it returns an URL to the converted file on the Doc Converter Pro Web API server
  6. backUrl - if specified, the API method will convert the input file and will POST it back to that specified URL. Please note that you need a web server to process POST requests, please check out ASP.NET C# sample app that receives files sent via POST from that API method or this PHP sample code.

3 - Merge Documents API Call

https://api.docconverter.pro/api/merge/mergedocuments - This API call will merge input files and it will return URL/Raw file data or post it back to a given URL the merged file.

The input parameters are:

  1. send at least two files in a FormData (JavaScript) or as MultipartFormDataContent, please see the sample page or other samples for implementation details
  2. outputformat - optional merged output format type: DOCX (default), PDF, RTF, TXT
  3. outputfilename - optional output file name without extension
  4. pdfcompliance - optional PDF compliance (only if PDF output format is set): PDF17 (default), PDFA1A, PDFA1B
  5. pdfimagestype - optional PDF image type (only if PDF output format is set): AUTO (default), JPEG
  6. pdfjpgquality - optional PDF JPEG image quality (only if PDF output format and JPEG image type is set): 10~100 values, default is 90.
  7. returnData - option to return raw octet-stream data, default is 'false' and it returns URL to the merged file on the Doc Converter Pro Web API server
  8. backUrl - if specified, API method will merge input files and will POST merged output file to that specified URL. Please note that you need a web server to process POST requests, please check out ASP.NET C# sample app that receives files sent via POST from that API method or this PHP sample code.

4 - Get currently used conversions and max conversions API Call

https://api.docconverter.pro/api/convert/conversionsinfo - This API call returns JSON data with two values Conversions (currently used conversion count) and MaxConversions (maximum conversions count). MaxConversions minus Conversions will give a number of conversions left.

API Throttling

DCP Web API throttles requests per IP. You can convert a maximum of 2 documents per second, 40 documents per minute, 1000 per hour and 20000 per day. The best is to wait until the conversion of the given document is done then send another API conversion request. When converting lots of small documents we recommend measuring how many documents you convert per second/minute etc, otherwise you will get an API quota exceeded error.

API Conversion Bad Request Error Note

In order to prevent exceeded server CPU usage DCP Web API will throw an error if the given input document caused a conversion error or it was already converted with the same template and it took more than 30 seconds to convert it within the last 1h.

Check out the API test web page (Javascript sample)...

We have created a sample page that demonstrates how the API conversion works in Javascript.

Doc Converter Pro Web API Test Page...

How to use the sample page:

  1. enter your login credentials, the same login as your Doc Converter Pro Online account and click the Get Bearer Token button. If you don't have a Doc Converter Pro Online account yet please Register for free.
  2. select the input document file that you want to convert
  3. optionally enter a template name
  4. optionally choose if you want to return a zip file with all output conversion files or just get the output file back
  5. optionally choose if you want to return a JSON list of output file URLs, raw data or URL string to that data file located on our server, using the raw data option with the return html option is useful if you want to use only converted html right away
  6. also, you can enable sending file back to a given URL via POST, please specify a URL that will process a POST request
  7. click the Start Converting button and wait for a response...

Example JavaScript code ...

Please check out the Javascript sample code or view the HTML and PostJsCode.js file source code of the Web API Test Page to see how you can use this API method in Javascript.

Example JavaScript/Jquery sample code (old version of current Javascript code described above) ...

Please check out the Javascript sample code that demonstrates how to get API token and convert or merge files.

Example PHP code ...

Please check out WebAPIPhpSample.zip sample PHP/HTML code that demonstrates how to get API token and the convert uploaded file. Extract the zip to a PHP web server. Edit the convert.php file and enter your Doc Converter Pro Online email and password on line 28. Set write permissions on upload/ folder if needed. Go to index.php in a browser, then select a document to convert and click Start Converting button.

Example .NET Winforms C# app ...

Please check out the WebAPITestApp.zip sample .NET Winforms C# app that does the same as the PostConvertReturn.html sample page. Based on that sample app C# code you can write code for ASP .NET MVC web applications as well.

Example Java code ...

Please check out the WebAPIJavaSample.zip sample Java code that demonstrates how to get API token and convert uploaded file. Extract the zip and edit the WordCleanerWebApi.java file and enter your Doc Converter Pro Online email and password in the GetAccessToken() method. Enter your doc file name and path and run.

Example Ruby code ...

Please check out the WebAPIRubySample.zip sample Ruby code that demonstrates how to get API token and convert sample doc file. Extract the zip and edit the dcp_web_api_sample.rb file and enter your Doc Converter Pro Online email and password on line 6 that gets API token. Make sure to install multipart-post gem: gem install multipart-post and then run this sample with ruby dcp_web_api_sample.rb

Example Python code ...

Please check out the WebAPIPythonSample.zip sample Python code that demonstrates how to get API token and convert uploaded file to HTML5. Extract the zip and edit the docconverter_pro_api_sample.py file and enter your Doc Converter Pro Online email and password at 223 and 224 lines.

The Web API uses the same template files that you got on your Doc Converter Pro Online account; therefore, you can use the Doc Converter Pro Online version to prepare your template and perform any testing.

Questions? Contact us anytime...