a REST web service API to convert Microsoft Word documents to PDF

What is PDF Alchemy?

PDF Alchemy is a REST web service API to convert Microsoft Word documents into PDF format.

PDF Alchemy is purely online - nothing to download or install!

PDF Alchemy is designed for programmers.

PDF Alchemy is totally free for converting up to 100 documents per month.

PDF Alchemy converts .doc .docx .rtf .txt files into PDF format.

PDF Alchemy is accessible via HTTP or HTTPS.

PDF Alchemy can be accessed from anywhere on the Internet using any computer language that can communicate via HTTP.

PDF Alchemy is hosted within Amazon EC2. Amazon EC2 users get optimum performance from PDF Alchemy. (Amazon EC2 is not required for usage of PDF Alchemy.)

PDF Alchemy is designed to handle conversions of any number of documents.

PDF Alchemy is intended to be integrated into applications that need to convert documents to PDF.

PDF Alchemy has done the work for you, and includes free working code for you to integrate into your application. Code is available in PHP, Java, C#, VB .NET, ActionScript, Perl, Python and Ruby.

News

13 Mar 2009 - PDF Alchemy is launched into open public beta!

Join the beta test of PDF Alchemy!

We are currently in open public beta test and anyone may join.

If you would like to become a beta tester, create an account, we will then send your API access keys, and you can get started with the code samples below!

Whilst we are in beta mode you can convert up to 250 documents per month for free. You can request more conversions by emailing us at the address below.

Pricing

PDF Alchemy is totally free for converting up to 100 documents per month.

Pricing for volume usage will be announced soon .........

Overview of how it works

PDF Alchemy is designed to convert any number of documents into PDF format. There is no technical limit on the number of documents that can be uploaded (your subscription plan defines how many documents you can convert in a month).

Here's how it works:

You need API access keys to use the PDF Alchemy API. After you create an account we will send your keys to you.
Upload as many documents as you wish to PDF Alchemy. Your uploaded documents are then queued for conversion within our systems. The amount of time taken to convert depends on the workload of our conversion servers.
As we convert the documents, they become available for you to download. Documents become available in the order in which our back end systems convert them, NOT the order in which they were uploaded. Calling the download API gives you the next available document.
Once you have downloaded a document, you must then delete it from PDF Alchemy. If you don't delete it, then you will find that it appears again in your download queue.

That's all there is to it! Very easy.

To get started create an account.

Benefits for Amazon EC2 users

PDF Alchemy runs within Amazon EC2 This means that users of Amazon EC2 will get optimal performance and low latency when communicating with PDF Alchemy.

Please note that using PDF Alchemy does not require Amazon EC2. You can access PDF Alchemy from anywhere on the Internet.

Sample code

The following code may be freely included in any application that uses PDF Alchemy.

The UPLOAD sample code uploads a document or folder to PDF Alchemy for conversion.

The DOWNLOAD sample code downloads all available converted documents from PDF Alchemy.

The STATUS sample code gets an estimate of number of documents converted and number of documents remaining to be converted.

PHP

Prerequisites: The following PHP examples require the pecl_http extension.

These PHP examples are intended to be used via the PHP command line. For example, to upload file1.doc and file2.docx, you could execute:

php -f pdf_alchemy_upload.php file1.doc file2.docx

Bash

Prerequisites: The following Bash examples require OpenSSL 0.9.8e or later.

Perl

Prerequisites: All of the following Perl examples require the Digest::HMAC_SHA1 and LWP::UserAgent modules. In addition, the UPLOAD example also requires the File::Basename, File::Slurp and URI::Escape modules.

C#

Prerequisites: The following UPLOAD and DOWNLOAD examples reference the System.Web .NET component. See How to: Add References in Visual Studio (C#).

Java

Prerequisites: The following Java examples require the Apache CXF library for Base64 encoding only. Since there are many Base64 encoders available, CXF can be replace quite easily by an encoder of your choice.

UPLOAD PDF_Alchemy_Upload.java

DOWNLOAD PDF_Alchemy_Download.java

STATUS PDF_Alchemy_Status.java

Visual Basic .NET

Prerequisites: The following UPLOAD and DOWNLOAD examples reference the System.Web .NET component. See How to: Add References in Visual Studio (Visual Basic).

UPLOAD pdf_alchemy_upload.vb

DOWNLOAD pdf_alchemy_download.vb

STATUS pdf_alchemy_status.vb

Python

Prerequisites: The following examples require Python 2.4 or later.

UPLOAD pdf_alchemy_upload.py

DOWNLOAD pdf_alchemy_download.py

STATUS pdf_alchemy_status.py

Ruby

Prerequisites: The following examples were written for Ruby 1.8.5.

UPLOAD pdf_alchemy_upload.rb

DOWNLOAD pdf_alchemy_download.rb

STATUS pdf_alchemy_status.rb

Coming soon: code for Adobe AIR.

Support

We're happy to help you!

Email any problems or questions to support@pdfalchemy.com

Contact us

We'd love to hear from you.

Email us at theguys@pdfalchemy.com

Documentation - REST API reference

Summary of API calls

http(s)://www.pdfalchemy.com/upload/accesskeyid/inqueue/[filename]

description: uploads a document for conversion.

params: secretaccesskey, filename, file, metatag1 metatag2.

returns documentid

method PUT|POST

http(s)://www.pdfalchemy.com/accesskeyid/outqueue/next

description: downloads the next converted document.
params: secretaccesskey, delete.
returns: converted document, documentid, metatag1, metatag2.
method: GET

http(s)://www.pdfalchemy.com/accesskeyid/outqueue/documentid
description: removes a converted document.
returns: documentid
method: DELETE

http(s)://www.pdfalchemy.com/accesskeyid/outqueue/all
description: removes all converted documents.
returns: number of documents deleted.
method: DELETE

http(s)://www.pdfalchemy.com/accesskeyid/status

description: retrieves queue status.
returns: estimated inqueue items and estimated outqueue items.
method: GET

Intended method of using PDF Alchemy API

This is the process that a document goes through to be converted into PDF:

1: The REST UPLOAD API is called, submitting a document for conversion to PDF format. A document ID is returned.

2: The PDF Alchemy servers convert the document and queues it for download.

3: The REST DOWNLOAD API is called, returning the next available converted PDF document. The document ID is included in the HTTP response headers.

4: The REST DELETE API is called to delete the specified document ID from the download queue. If the document is not DELETE'd from the download queue then it reappears in the queue after a delay of 90 seconds. Documents are permanently deleted by the system 24 hours after conversion.

The REST STATUS API returns an estimate of the number of documents awaiting conversion and download.

Notes:

documents appear in the DOWNLOAD queue in the order in which they are converted, NOT necessarily the order in which they were uploaded.
the REST UPLOAD API may include metadata HTTP headers. The metadata headers are then included in the response from the REST DOWNLOAD API. The purpose of the metadata is to allow the application developer to include identifying information.
HTTP or HTTPS may be used to upload and download documents.

Authentication

Note: the work is done for you. Grab the sample code on this page to see how to authenticate and generate a signature for your API calls.

You need to create an account to use PDF Alchemy.
Every call to the PDF Alchemy API must carry authentication information, which consists of your Access Key ID and a signature.
The Access Key ID identifies your account with every API call.
The Secret Access Key is used to generate a signature that must also be included with every API call.
After you create an account, you will be sent your Access Key ID and your Secret Access Key.

Signature Generation

For each API call, you must generate a signature by computing an HMAC-SHA1 code for a normalized request string. The normalized request string consists of the following items, separated by carriage-return (\n) characters.

the HTTP method being used - for example "GET" or "PUT".
your Access Key ID.
the date / timestamp.
the HTTP request URI - for example "/AccessKeyID/outqueue/next" for the download request.

So, for example, if your Access Key ID is "12345", then the normalized request string for your next download REST API call would look like:

"GET\n12345\nFri, 13 Mar 2009 02:19:48 GMT\n/12345/outqueue/next"

And so the request signature would be the HMAC-SHA1 code of that normalized request string, using your Secret Access Key as the HMAC has key.

You can see a number of examples of HMAC-SHA1 signature generation in the various samples code on this page.

Common Parameters for all API calls

All API requests must include a valid date / time stamp, and the request signature.

The date / time stamp format must conform to the standard defined in RFC 2822, for example "Fri, 13 Mar 2009 02:19:48 GMT". It is recommended that this time stamp be submitted via the standard HTTP "Date" header. But if that is not possible, then it may also be submitted as a custom "X-PDF-Alchemy-Date" HTTP header, or as a "Timestamp" query parameter.

The HMAC-SAH1 signature must be submitted either as a custom "X-PDF-Alchemy-Signature" HTTP header (recommended), or a "Signature" query parameter.

API call - Upload

The upload API call uploads one document for conversion.

Files are uploaded to PDF Alchemy by either:

HTTP PUT to http(s)://www.pdfalchemy.com/AccessKeyId/inqueue/filename or
HTTP POST to http(s)://www.pdfalchemy.com/AccessKeyId/inqueue

Where AccessKeyId is your PDF Alchemy Access Key ID. You may (optionally) include up to two custom meta tags with the upload. To do so, set the desired meta data as custom HTTP headers prefixed with "X-PDF-Alchemy-Meta-". Only the first two meta tags will be processed - any others will be silently ignored by the PDF Alchemy servers.

On success, the service will respond with an XML document stating the accepted document's ID.

On failure, the service will respond with an XML document specifying an error code, and error message.

API call - Download

The download API call downloads the next available converted PDF document from your download queue.

The next available file can be download via:

HTTP GET http(s)://www.pdfalchemy.com/AccessKeyId/outqueue/next

Where AccessKeyId is your PDF Alchemy Access Key ID.

On success, the service will response with a valid PDF document. The response headers will include the downloaded document's ID in the custom "X-PDF-Alchemy-ID" HTTP header, along with any custom meta headers accepted when the original document was uploaded.

On failure, the service will respond with an XML document specifying an error code, and error message.

This download service also accepts an optional "delete" query parameter, that when set to "true" causes the service to automatically remove the document from your download queue once the download has completely successfully. For example:

GET https://www.pdfalchemy.com/AccessKeyId/outqueue/next?delete=true

On failure, the service will respond with an XML document specifying an error code, and error message.

API call - Delete

The delete API call deletes a document from your download queue.

Documents within your download queue should be removed via:

HTTP DELETE http(s)://www.pdfalchemy.com/AccessKeyId/outqueue/documentId

Where AccessKeyId is your PDF Alchemy Access Key ID, and documentId is the document ID that was included in the HTTP response headers when the document was downloaded. Note, you cannot delete a document unless it has been downloaded previously.

On success, the service will respond with an XML document stating the document's ID.

On failure, the service will respond with an XML document specifying an error code, and error message.

Although it is not recommended, you may also use the special document ID "all" to have the service delete all documents currently awaiting download. For example:

HTTP DELETE http(s)://www.pdfalchemy.com/AccessKeyId/outqueue/all

If you do NOT delete a document after it is downloaded, then it will re-appear in your download queue after approximately 90 seconds.

API call - Status

The status API call provides information on the number of documents that are awaiting and completed conversion.

HTTP DELETE http(s)://www.pdfalchemy.com/AccessKeyId/outqueue/documentId

Where AccessKeyId is your PDF Alchemy Access Key ID.

On success, the service will respond with an XML document stating the approximate number of documents you have awaiting conversion, as well as the approximately number of documents you have awaiting download.

On failure, the service will respond with an XML document specifying an error code, and error message.

site last edited 24 Mar 2009