Document API

Converting HTML into PDF and XLS documents is fast and painless with DocRaptor. Just send a POST call to with the four required parameters. Browse the below documentation to get started, or check out a code example in your language.


You'll authenticate with your API key, which can be found on your account dashboard. You can use your API key in one of two ways: either as the value of the query parameter "user_credentials", or as the username for basic HTTP authentication. You can see examples of both of these methods in our code examples.

Making a Document

It's simple! Just POST to with the below parameters. We have excellent examples and libraries in most languages.

General Options

The parameters are presented as form serialized keys, but a JSON format is also supported.

user_credentials Required unless using basic HTTP authentication
Your API key. See authentication for more information. All documents created with the YOUR_API_KEY_HERE token will be made in test mode.
doc[document_type] Required
  • pdf
  • xls
  • xlsx
The type of document DocRaptor should create from the provided content.
doc[document_content] Required unless document_url is used
  • <table><tr><td>Example!</td></tr></table>
The HTML or XML that DocRaptor should use to create the document. Excel files should be XML while PDFs can be converted from HTML.
doc[document_url] Required unless document_content is used
The URL that DocRaptor should request the content from to create the document.
doc[name] Required
  • July Invoice for User #1234
Any string that you find meaningful to describe the document. It is used for identification in the documents log.
doc[test] Optional
  • false
  • true

Creates the document in test mode. All plans have unlimited test documents that do not count against monthly limits. This way you can play with styles until you get a good looking document without wasting any of your allotted documents.

When test mode is on, generated PDFs will be watermarked and Excel documents will be cut off after 20 rows.

doc[referrer] Optional
  • doc[document_url]

Explicitly defining the referrer is useful if you have to make JavaScript calls that depend on the referrer. For example, Adobe's Typekit functionality requires this to be set explicitly when using document_content.

Basic PDF Options

We convert HTML into PDFs using the industry-leading Prince PDF engine. Many of our API options are specific to Prince and only apply to PDF documents. Our usage of the Prince engine means we have multiple JavaScript parsing engines to select from.

doc[prince_options][media] Optional, PDF-Only
  • print
  • screen
We apply "print" media rules by default as most DocRaptor documents are destined for the printer. Using "print", when you really want "screen" (which is what browsers use), is the most common issue users experience. If your document looks really incorrect, try changing this first.
doc[prince_options][version] Optional, PDF-Only
  • 7.1
  • 8.1
  • 9.0
  • 10
If no parameter is supplied, your documents will use Prince 10 by default. You can change your default Prince version via the “Edit Profile” link on your user dashboard. For users not on the newest version, we recommend upgrading after you test your documents on that version.
doc[prince_options][baseurl] Optional, PDF-Only
The base URL is used for all relative URLs in a document. Without a base URL, urls such as "../images/photo.jpg" will fail to load. This can also be accomplished by using the HTML Base tag.

JavaScript PDF Options

DocRaptor offers two options for JavaScript parsing and both are disabled by default (it makes your document processing a lot faster). Most users will only want to use one JavaScript engine as enabling both engines simultaneously will cause all JavaScript code to be evaluated twice.

doc[javascript] Optional, PDF-Only
  • false
  • true

If enabled, we will use DocRaptor's custom JavaScript engine to run any JavaScript in your HTML before sending it to Prince for conversion.

DocRaptor's JavaScript engine is separate from Prince's JavaScript engine. Our engine has been specifically designed to provide support for popular JavaScript tools and libraries, such as Typekit and Highcharts. We generaly recommend using our engine, not the Prince engine

If there are any JavaScript errors, the document creation process will fail, and the errors will be returned so you can see what went wrong.

doc[prince_options][javascript] Optional, PDF-Only
  • false
  • true

If enabled, we will use Prince's built-in JavaScript engine. Note that this is a separate engine from DocRaptor's JavaScript engine. We generally recommend using DocRaptor's engine, but Prince's engine is necessary in certain cases, such as drawing in a canvas element with JavaScript or when accessing Prince's custom PDF JavaScript object.

Feel free to contact us if you have any questions about running JavaScript in your document.

Advanced PDF Options

99% of users don't need these options. Almost all PDF styling (headers, footers, page size, etc.) is controlled via simple CSS styles. But if you are looking for an uncommon file options such as password protection and DPI settings, take a look at these:

Show Advanced Options

Hide Advanced Options

doc[prince_options][no_xinclude] Optional, PDF-Only
  • false
  • true
Disable XInclude processing.
doc[prince_options][no_network] Optional, PDF-Only
  • false
  • true
Disable network access (prevents HTTP downloads).
doc[prince_options][http_user] Optional, PDF-Only
Specify the username for HTTP authentication.
doc[prince_options][http_password] Optional, PDF-Only
Specify the password for HTTP authentication.
doc[prince_options][http_proxy] Optional, PDF-Only
Specify the HTTP proxy server.
doc[prince_options][http_timeout] Optional, PDF-Only
  • 1
  • 2
  • ...
  • 10
  • ...
  • 59
  • 60
Specify how long to wait, in seconds, when requesting an external resource. This parameter accepts a value ranging from 1 to 60. By default, DocRaptor will attempt to fetch any external resource for up to 10 seconds. You can set a longer timeout to force DocRaptor to wait for a large file, for example, or shorten it to skip resources that are unavailable.
doc[prince_options][insecure] Optional, PDF-Only
  • false
  • true
Disable SSL verification (not recommended).
doc[prince_options][no_author_style] Optional, PDF-Only
  • false
  • true
Ignore author style sheets.
doc[prince_options][no_default_style] Optional, PDF-Only
  • false
  • true
Ignore default style sheets.
doc[prince_options][no_embed_fonts] Optional, PDF-Only
  • false
  • true
Disable font embedding in PDF output.
doc[prince_options][no_subset_fonts] Optional, PDF-Only
  • false
  • true
Disable font subsetting in PDF output.
doc[prince_options][no_compress] Optional, PDF-Only
  • false
  • true
Disable compression of PDF output.
doc[prince_options][encrypt] Optional, PDF-Only
  • false
  • true
Encrypt PDF output.
doc[prince_options][key_bits] Optional, PDF-Only
  • 40
  • 128
Set encryption key size.
doc[prince_options][user_password] Optional, PDF-Only
Set PDF user password.
doc[prince_options][owner_password] Optional, PDF-Only
Set PDF owner password.
doc[prince_options][disallow_print] Optional, PDF-Only
  • false
  • true
Disallow printing of PDF output.
doc[prince_options][disallow_copy] Optional, PDF-Only
  • false
  • true
Disallow copying from PDF output.
doc[prince_options][disallow_annotate] Optional, PDF-Only
  • false
  • true
Disallow annotation of PDF output.
doc[prince_options][disallow_modify] Optional, PDF-Only
  • false
  • true
Disallow modification of PDF output.
doc[prince_options][input] Optional, PDF-Only
  • html
  • xml
  • auto
Specify the input type of the document to be used by Prince during processing.
doc[prince_options][css_dpi] Optional, PDF-Only
  • 96
  • 72
  • 200
  • etc
By default, Prince sets the page DPI for generated PDFs to 96. However, when using Prince 9.0 or higher, you can override this setting to use the DPI you prefer.
doc[prince_options][profile] Optional, PDF-Only
  • PDF/A-1b
  • PDF/X-3:2003
  • PDF/X-4
If you need PDF profile support (Prince 9+ only!), you can set this option. See Prince's documentation for details.

Asynchronous Options

doc[async] Optional
  • false
  • true

DocRaptor attempts to create documents using synchronous creation by default. We set a time limit of 60 seconds for synchronous creation. When a synchronous request completes, DocRaptor will return your generated document.

If you have very large or complex documents, you may wish to switch to asynchronous job creation. Setting this parameter to true will extend the time spent on your job to 600 seconds, queue your document for background creation and DocRaptor will return JSON with a "status_id" key set. e.g.


Making an authenticated request against{status_id} will give you the status of your document job. The returned JSON from that call should look something like:

{"status": "completed", "download_url": "", "message": "Completed at Mon Jun 06 18:33:17 +0000 2011", "number_of_pages": 2}

When the job is complete, DocRaptor will call the specified callback_url if one was provided, via a POST request.

Querying the status URL after the doc has been successfully created will provide a download_url in the returned JSON. The value associated with that key is a 2-time use URL from which you can download your doc. This download URL will expire 1 hour after successful asynchronous job creation.

If DocRaptor encounters an error generating your document, the status value will be "failed". A key "validation_errors" will be set with a value corresponding to the reason for the failure. An example of this is:

{"status":"failed", "validation_errors":"Name can't be blank\nName is too long (maximum is 200 characters)"}

If your document has been queued but processing has not yet begun, it will have a status of "queued". If your document is currently being processed, it will have a status of "working".

You can check out our asynchronous cURL request example to see how making an asynchronous document works.

Note: If there is an error creating your document, the callback_url will never be called. The status page will explain the error.

doc[callback_url] Optional

If this parameter is provided and the async parameter is set to true, DocRaptor will send a POST request to this URL after successfully completing an asynchronous job. The POST will contain the parameter "download_url" with the value being a URL where your document can be downloaded.

Note: If there is an error creating your document, the callback_url will never be called. The status page will explain the error.

Miscellaneous Options

doc[strict] Optional, PDF-Only
  • none
  • html

When set to "html", if input does not pass our HTML validation, the document will fail and we'll report any HTML errors.

For Excel files, we always validate input as XML. Unlike PDFs, XLS files are not free-form, and elements must map to XLS cells clearly and exactly.

doc[help] Optional
  • false
  • true

Enabling help mode will trigger an email to you and to support, letting us know you'd like assistance in troubleshooting the document styling.

When a document is in help mode, we'll store your document contents for review until it's resolved. You can have up to five active help requests at any given time.

doc[tag] Optional
  • marketing
An arbitrary tag string for the document. Useful if you have multiple applications using DocRaptor under the same DocRaptor account and you want to differentiate in the logs between each app.

HTTP Status Codes

200 - OK
Your request was made successfully, and DocRaptor has returned a document. We will also return a 200 code when an asynchronous document has successfully generated.
400 - Bad Request
This error code means your request can not be completed as expected. DocRaptor will return this code if the download key is not valid, if the requested document has not completed, if there is an error in your generated document, or if there are errors in your HTTP POST request.
401 - Unauthorized
This status code means authorization is required, but has either not been provided or is incorrect. DocRaptor will return this status code if the API key provided is incorrect.
403 - Forbidden
A 403 status code means the request was made correctly, but the server is refusing to respond. We will return this status code if you do not have permission to view the status of that document, or if you are making too many simultaneous document generation requests.
422 - Unprocessable Entity
This error means your input document has syntax errors and DocRaptor can not process it as expected.

Response Headers

For PDF documents, the X-DocRaptor-Num-Pages response header will contain the number of pages contained in the document.


We do not impose hard limits on input size, output size, numbers of pages, or document complexity. The only limits are time to complete, simultaneous requests, and documents created per billing period (this is defined by your DocRaptor plan). By default, you are limited to 30 simultaenous requests (we often increase this for larger customers).

Simple documents may only take a few seconds to generate, and a more complicated document with many external resources to fetch or scripts to run may take several minutes to create.

DocRaptor has two time limits enforced:

Synchronous Documents (default): 1 minute
Asynchronous Documents 10 minutes

If your document goes over this time limit, it will be killed, and an error will be returned.

Test Documents

All DocRaptor plans have unlimited test documents so you can make sure the document looks exactly the way you want. When you set the 'test' parameter to 'true', your documents will not count against your plan limit. Test PDFs will be watermarked and test Excel documents will be cut off after 20 rows.

Support & Debugging

We are here to guide you while integrating, running, and debugging any issue you might have. You can always reach us via email at You can also chat with us live from our website, or send us a message by selecting "Help!" when logged into your dashboard.

If you need a hand with a specific document, you can open a Help Request right from your dashboard. This will share the document input, output, and log so we can get right to fixing your issue. Just log into your account, select "Doc Log" in the top left corner, then "Request Help" for the document you're having trouble with. Our support team will be with you as soon as we've received your request.

Excel API Options

The general technique for producing an XLS file is to send some us some HTML in the form of a table per worksheet, with the tables' rows and cells corresponding to the same in excel. Below is a picture of a simple example transformation which also demonstrates the use of named worksheets (via the name attribute).

You can style cells, rows, and the entire table using style attributes, and those attributes cascade. Below is a picture of a simple background-color example transformation.

Read through our coding examples for more large examples.

Excel XLS Version Support

We currently produce Excel '97 compatible XLS files. As such, features added to excel later than that are not currently supported.

Special Table & Cell Attributes

Several element attributes have special meaning in DocRaptor. Below is a picture of those in action.


Setting the name attribute on a table element will name the sheet produced by the table.


Setting the password attribute on a table element will password protect the sheet produced by the table with the given password. By default this means that all cells in the sheet will be read-only, unless the password is entered. You can control what cells will be read-only using the -xls-locked style.


Setting the colspan on a table cell will create a merged cell


Setting the rowspan on a table cell will create a merged cell from cells below the current cell.

Multiple Worksheets

Creating multiple worksheets is easy. Just send more than one table in your request, wrapped inside a "tables" tag.

Specific Styles

What follows is a list of styles we support as part of a style attribute's value and the options they take. Excel-specific styles have been prefixed with ‘-xls-’. The options should more or less correspond to the options found via “Format Cell” in Excel.


The content type for the cell in Excel.

Default: auto

  • auto - will try and determine the excel cell type automatically based off the cell contents
  • number
  • formula
  • datetime
  • boolean
  • blank


The horizontal alignment for cell content.

Default: general

  • general
  • left
  • right
  • center
  • justify
  • fill


The vertical alignment for cell content.

Default: bottom

  • bottom
  • top
  • center
  • justify


Amount of indentation of the cell content. Integer value from 0 to 14.

Default: 0


Cell content wrapping. If set to wrap, then Excel will wrap data in cells with this format so that it fits within the cell boundaries.

Default: nowrap

  • nowrap
  • wrap


Sets the text orientation for this cell.

Default: horizontal

  • horizontal (0)
  • vertical (90)
  • stacked
  • 0
  • 45
  • 90
  • 270
  • 315
  • 360

Arbitrary amounts are not allowed. The option closest to what you pass us will be chosen.
360 is equivalent to 0.


Sets the background pattern.

Default: none (solid if background-color is set)

  • none
  • 6.25%
  • 12.5%
  • 25%
  • 50%
  • 75%
  • solid
  • horizontal stripe
  • vertical stripe
  • reverse diagonal stripe
  • diagonal stripe
  • diagonal crosshatch
  • thick diagonal crosshatch
  • thin horizontal stripe
  • thin vertical stripe
  • thin reverse diagonal stripe
  • thin diagonal stripe
  • thin horizontal crosshatch
  • thin diagonal crosshatch


Sets the background color for the cell. Can take any named web color or hex value.

Default: transparent (grey if -xls-background-pattern is set)

These colors will be translated to the closest of the ~64 valid colors for Excel. Certain colors (such as black) will cause Excel to ignore the background pattern you set.

    border-top-color, border-bottom-color, border-left-color, border-right-color

    Sets the border color for the cell. Can take any named web color or hex value.

    Default: transparent (if a border color is set, the default will be black)

    These colors will be translated to the closest of the ~64 valid colors for Excel.

      border-top-style, border-bottom-style, border-left-style, border-right-style

      Sets the border style (lines that appear around a cell)

      Default: none (if color is set, the default is thin).

      • none
      • thin
      • medium
      • dashed
      • dotted
      • thick
      • double
      • hair
      • medium dashed
      • dash dot
      • medium dash dot
      • dash dot dot
      • medium dash dot dot
      • slanted dash dot


      Sets the font family.

      Default: Arial


        Sets the font size in points.

        Default: 10pt


          Sets if the font should be italic or not.

          Default: normal

          • normal
          • italic


          Sets the weight of the font.

          Default: normal

          • normal (400)
          • bold (700)
          • bolder (900)
          • lighter (200)
          • 100
          • 200
          • 300
          • 400
          • 500
          • 600
          • 700
          • 800
          • 900


          Sets the text decoration.

          Default: none

          • none
          • line-through
          • underline


          Sets the text color for the cell. Can take any named web color or hex value.

          Default: black

          These colors will be translated to the closest of the ~64 valid colors for Excel.


          Sets the number/date format for the cell. There are many possible options for this. A few of the important ones are below, with more documentation to come in the future. As a warning, if you use a number format on a text or date cell, the results may be unpredictable.

          Formatting Numbers and Text

          Default: default

          • default
          • text
          • integer
          • float
          • percent float
          • percent integer
          • accounting float
          • accounting integer
          • accounting red float
          • accounting red integer
          • exponential
          • fraction_one_digit
          • fraction_two_digits
          • thousands_float
          • thousands_integer

          Formatting Currency

          • currency_dollar
          • currency_euro_prefix
          • currency_euro_suffix
          • currency_japanese_yen
          • currency_pound

          Formatting Dates and Times

          • date_format1 (m/d/yy)
          • date_format2 (d-mmm-yy)
          • date_format3 (d-mmm)
          • date_format4 (mmm-yy)
          • date_format5 (h:mm AM/PM)
          • date_format6 (h:mm:ss AM/PM)
          • date_format7 (h:mm)
          • date_format8 (h:mm:ss)
          • date_format9 (m/d/yy h:mm)
          • date_format10 (d/m/yy)
          • date_format11 (d/m/yy h:mm:ss) (xlsx-only)
          • date_format12 (dd.MM.yyyy) (xlsx-only)


          Sets the height of a row. Only valid on tr elements.

          Default: auto


          Sets the width of a column. The last width specified for a column wins (i.e., if you specify the width for a column in both row 1 and row 2, the width specified in row 2 is used).

          Default: auto


          Sets if this cell is locked. Only has meaning if a password has been set for the sheet that will contain this cell.

          Default: true

          • true
          • false


          When reading values for cells, what character delimits large numbers (i.e. 1 million written as ‘1,000,000’ is delimited by the comma character). If you are using this, you probably want to set ‘-xls-decimal-delimiter’, too.

          Default: ,


          When reading values for cells, what character delimits the begin of the decimal portion of numbers (i.e. 11/10 written as 1.1 is delimited by the period character). If you are using this, you probably want to set ‘-xls-thousands-delimiter’, too.

          Default: .

          Code Examples

          In this section, you'll find examples for making HTTP POST requests to our servers using C#, cURL, Java, jQuery, .NET, Node.js, PHP, Python, Ruby, and Rails.

          You can read through our documentation here, or check out our repositories located at GitHub. If you have an example you'd like to share let us know and we'll share it with the world.

          C# Examples

          We provide a simple CLI program example (as opposed to a full blown GUI solution) as well as a WPF example. You can find the entire solution for the WPF example at GitHub.

          CLI Example

          WPF Example

          cURL Example

          Here you'll find examples for making documents with a cURL request.

          cURL Synchronous Examples

          cURL Asynchronous Example

          Java CLI Example

          jQuery Examples

          Here you'll find several examples for creating PDF and Excel files with jQuery. We provide documentation for creating documents from forms and URLs, as well as using a jQuery plugin written by one of our users.

          Note: if you don't want to expose your API key in your client-side JavaScript, check out Referrer-based Document Generation. Also, DocRaptor fully supports the CORS specification, allowing cross-site HTTP requests.

          jQuery Form Based

          jQuery URL Based

          jQuery plugin

          David Baldwin made a nice DocRaptor jQuery plugin. Examples and usage details can be found on that page.


          One of our users wrote a .NET wrapper for asynchronous document creation:

          Node.js Examples

          Here you'll see several example implementations using Node.js. Our first example implementation has no dependencies, and we also provide examples using the HTTP client libraries, request and restler.

          Node.js Implementation

          Node.js Implementation Using Request

          Node.js Implementation Using Restler

          PHP Examples

          If you're using DocRaptor with PHP, you've got several options!

          PHP Wrapper Example

          You can use the official PHP API wrapper , which requires PHP 5.4 or newer as well as the PHP cURL extension.

          PHP Client Example

          You can also use a client written in PHP 5 by one of our users. This example works with PHP 5.3 or newer, and also requires the PHP cURL extension.

          Example using pecl_http

          Finally, you can use this example, which requires pecl_http to be installed on your server.

          Python Examples

          Thanks to John Keyes, there is a Python wrapper that closely matches the functionality of the official Ruby gem. Below are a couple of examples of that wrapper in action.

          Python Example

          Python Async Example

          Ruby Examples

          We provide Ruby examples using the official DocRaptor gem, as well as using the HTTParty gem.

          DocRaptor Gem Example

          DocRaptor Gem using Async Functionality

          HTTParty Example

          Rails Example

          We've provided a couple of excerpts from a complete Ruby on Rails example that you can get at GitHub.

          Note: You can define a PDF layout to be used for all of your PDFs by creating an application.pdf.haml (or .erb) file. This technique can also be used to create an XLS layout.

          Note: Rails runs development mode through WEBrick by default. WEBrick is single-threaded, so if your app is hitting its other endpoints in order to generate PDFs, you'll want to use something that supports concurrent requests in development like unicorn, passenger, or thin. You could also run multiple WEBrick instances on different ports.

          API Key Setup

          Add this to config/environment.rb to define your API key:

          Controller Example

          Some sample code from a controller:

          HAML Example

          Sample HAML code to generate an Excel file:

          Referrer-Based Documents

          DocRaptor makes it easy to convert any webpage you have control over into a document using a simple anchor tag. On your account management page, you can add domains you would like to link to DocRaptor, and requests to DocRaptor to create docs that have that domain as part of their HTTP_REFERER HTTP header will be generated using your account without the need for an API key. Click "domains” after logging in to manage your domains!


          Once you've set up your domains, you can make a GET request against either:


          Example Code

          Live Example

          Documentation PDF

          Document Listing API

          You can also get a list of previously created documents through the API. This is just information like the name, the date, and if it was a test document. Since we don't actually store the created document, we can't return that. Info about the documents is returned as XML or JSON in a paginated list, ordered by date of creation (most recent first).


          You can make a GET request against either:

          • (or .xml)
          • (or .xml)


          The following are the parameters that DocRaptor expects when you request the document listing.


          Specifies the page (in terms of pagination) of documents to return

          Name: page

          Default: 1

          Per Page

          Specifies the number of documents per page (in terms of pagination) to return

          Name: per_page

          Default: 100

          Document Log Listing API

          You can also get a list of all previously attempted document creations. The returned data here includes information about document creation success and failure, any errors that were encountered, and information about generation time. The information is returned as XML or JSON in a paginated list, ordered by date of creation (most recent first).


          You can make a GET request against either:

          • (or .xml)
          • (or .xml)


          The following are the parameters that DocRaptor expects when you request the doc log listing.


          Specifies the page (in terms of pagination) of documents to return

          Name: page

          Default: 1

          Per Page

          Specifies the number of documents per page (in terms of pagination) to return

          Name: per_page

          Default: 100

          Search Start

          Specifies the start date of the search range for returning doc log entries.

          Name: search[start]

          Default: 1 month ago

          Search End

          Specifies the end date of the search range for returning doc log entries.

          Name: search[end]

          Default: The current date