This add-on is operated by FileTurn

Convert Files with an API

Last updated August 02, 2021

FileTurn is an add-on that provides file conversions via an easy-to-use API. Conversions are available between PDF and each of Word, Excel, and PowerPoint, along with additional PDF-specific operations.

Provisioning the add-on

FileTurn can be attached to a Heroku application via the CLI:

$ heroku addons:create fileturn:free
Creating fileturn:free on ⬢ appone... free
Resource has been created and is available!

After you provision FileTurn, a FILETURN_TOKEN config var is added to your app’s configuration. It contains the secret token for accessing the default FileTurn application created for you. This can be confirmed using the heroku config:get command:

$ heroku config:get FILETURN_TOKEN

After installing FileTurn, the application should be configured to fully integrate with the addon.

Conversion Formats

See the FileTurn documentation for a list of conversion formats.

Dashboard

The FileTurn dashboard allows you to view your remaining monthly conversions, manage your webhook URL, and optionally link an Amazon S3 bucket for storage.

You can access the dashboard via the CLI:

$ heroku addons:open fileturn
Opening fileturn for sharp-mountain-4005

or by visiting the Heroku Dashboard and selecting the application in question. Select FileTurn from the Add-ons menu.

Using the FileTurn REST API

After you provision FileTurn and have your FILETURN_TOKEN, you are ready to make the first API request:

$ curl -X "POST" https://fileturn.net/api/conversions.json \
  -d api_token=[FILETURN_TOKEN] \
  -d type=WordToPdf \
  -d url=iiswc.org/iiswc2013/sample.doc

For details on API calls, see the FileTurn REST API Documentation.

Using the FileTurn Ruby Gem

Add the FileTurn gem to your Gemfile:

gem 'fileturn'

After adding the gem, bundle install and commit your changes to Gemfile and Gemfile.lock. The gem will be initialized with your FILETURN_TOKEN.

After the Ruby gem is initialized, you can start using FileTurn commands. See the FileTurn Ruby Gem documentation for details.

Webhooks

Because document processing is asynchronous, you need to be notified when the document is processed. FileTurn sends an HTTP POST request to your server with the result when processing is finished.

Example Successful Webhook Response

{
  "id": "da6a33f0-ccb5-4891-8918-e8cd40508083",
  "type": "WordToPdf",
  "status": "completed",
  "source_files": [
    "http://www.academichomes.com/downloads/ExampleLeaseAgreement1.doc"
  ],
  "temporary_download_urls": [
    "http://fileturn-dev.s3.amazonaws.com/da116fd8-4d16-4539-8cf1-3775d56affff/ExampleLeaseAgreement1.pdf?AWSAccessKeyId=AKIAJWJK4KZF2KQBC3GA&Expires=1530647088&Signature=sUR%2BTBaXsriN4qx2DTs0bfMPPeM%3D"
  ],
  "processing_time_in_seconds": 14,
  "error_type": null,
  "error_details": null
}

See the Webhook Documentation for details.

Removing the add-on

FileTurn can be removed via the CLI:

$ heroku addons:destroy fileturn
-----> Removing fileturn from appone.. done, v20 (free)

Support

All FileTurn support and runtime issues should be submitted via the Heroku Support channels.