- Getting Started
- Installation
- Key Concepts
- Integrations
- Account & Billing
- Security & Privacy
- PDF Generation
- Reference
- Tutorials
- Troubleshooting
- Excel Generation
- Reference
- Troubleshooting
API Parameters
General Options
type
Required
- Options:
-
pdf
-
xls
-
xlsx
The kind of document DocRaptor should create from the provided content.
This field was previously called document_type and is still available for applications that depend on it.
document_content
Required unless document_url is used
- Example:
-
<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.
document_url
Required unless document_content is used
- Example:
-
https://www.docraptor.com/documentation
The URL that DocRaptor should request the content from to create the document.
name
Optional
- Example:
-
July Invoice for User #1234
Any string that you find meaningful to describe the document. It is used for identification in the documents log.
test
Optional
- Options:
-
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
is set to true
there are a few things to note:
- Generated PDFs will be watermarked.
- Excel documents will be cut off after 20 rows.
- Hosted documents will be limited to 5 downloads.
- Hosted documents will expire after 1 day.
referrer
Optional
- Default:
-
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.
pipeline
Optional
- Options:
-
6
-
7
-
8
-
9
-
9.2
-
10
-
10.1
The DocRaptor pipeline allows you to choose the combination of Prince and JavaScript engines you want to use.
If not set, your documents will use Pipeline version 10.1 by default. You can change your default Pipeline version via the Settings link on your user dashboard. For users not on the newest version, we recommend upgrading after using this API parameter to test your documents on that version.
The following describes the mapping of Pipeline version to Prince and JavaScript engine versions:
Pipeline | Prince | JavaScript | Release Notes |
---|---|---|---|
10.1 | 15.1 | 2 | Release Notes |
10 | 15 | 2 | Release Notes |
9.2 | 14.3 | 2 | Release Notes |
9 | 14.1 | 2 | Release Notes |
8 | 13.5 | 2 | Release Notes |
7 | 12.5 | 2 | Release Notes |
6 | 11.4 | 2 | Release Notes |
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.
prince_options[media]
Optional, PDF-Only
- Options:
-
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.
prince_options[version]
Deprecated, Optional, PDF-Only
- Options:
-
7.1
-
8.1
-
9.0
-
10
This API parameter is deprecated and pipeline should be used instead.
prince_options[baseurl]
Optional, PDF-Only
The base URL is used for all relative URLs in a document. Without a base URL, relative urls such as "../images/photo.jpg" will fail to load. This can also be accomplished by using the HTML Base tag.
Note that relative URLs starting with the /
will use the naked domain instead of the full baseurl for their base.
Here's how that works:
baseurl | rel. url | full url |
---|---|---|
a.com |
/b/c/d.jpg |
a.com/b/c/d.jpg |
a.com/b |
c/d.jpg |
a.com/b/c/d.jpg |
a.com/b |
/c/d.jpg |
a.com/c/d.jpg |
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.
javascript
Optional, PDF-Only
- Options:
-
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
By default, we stop running JavaScript when your page is finished rendering. If you have any delayed or asynchronous JavaScript on your page, simply define a function called docraptorJavaScriptFinished()
. It should return true
if all of your JavaScript has finished executing, and false
otherwise. Any other return value is considered an error.
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.
ignore_console_messages
Optional, PDF-Only
- Options:
-
false
-
true
By default, JavaScript console messages, such as console.log('hello')
, halt PDF generation and cause an error message to be returned. If this parameter is enabled, we will instead ignore and log JavaScript console messages, as most web browsers do.
In Pipelines 1-6, the default value for this option is false, meaning console messages WILL halt document generation.
In Pipelines 7 and greater, the default value for this option is true, meaning console messages WILL NOT halt document generation by default.
prince_options[javascript]
Optional, PDF-Only
- Options:
-
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.
prince_options[max_passes]
Optional, PDF-Only, Pipeline 9+
When using Prince's JavaScript, specifies a
limit on the number of times that the document may be laid out by JavaScript. By default,
there is no limit. The first pass always occurs. The second and subsequent passes will occur
if a JavaScript function is registered with Prince.registerPostLayoutFunc(func)
.
This multi-pass approach to document scripting can sometimes lead to unexpected processing loops and longer document processing times. This option helps by limiting the number of passes JavaScript takes over a 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:
ignore_resource_errors
Optional, PDF-Only
- Options:
-
true
-
false
By default, errors downloading resources (CSS and images) are ignored when generating the PDF. When this is disabled, the following resource issues will cause document creation to fail: 400s, 500s, DNS resolution errors, unknown mime types, connection timeouts, SSL issues, rejected connections, and use of protocol-independent URIs without proper HTTP baseurl.
prince_options[no_xinclude]
Optional, PDF-Only
- Options:
-
false
-
true
Disable XInclude processing.
prince_options[no_network]
Optional, PDF-Only
- Options:
-
false
-
true
Disable network access (prevents HTTP downloads).
prince_options[no_parallel_downloads]
Optional, PDF-Only
- Options:
-
false
-
true
Disables parallel fetching of assets during PDF creation. Useful if your asset host has strict rate limiting.
prince_options[http_user]
Optional, PDF-Only
Specify the username for HTTP authentication.
prince_options[http_password]
Optional, PDF-Only
Specify the password for HTTP authentication.
prince_options[http_proxy]
Optional, PDF-Only
Specify the HTTP proxy server.
prince_options[http_timeout]
Optional, PDF-Only
- Options:
-
1
-
2
- ...
-
10
- ...
-
59
-
60
Specify how long to wait, in seconds, when requesting an external resource. 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.
prince_options[insecure]
Optional, PDF-Only
- Options:
-
false
-
true
Disable SSL verification (not recommended).
prince_options[no_author_style]
Optional, PDF-Only
- Options:
-
false
-
true
Ignore author style sheets.
prince_options[no_default_style]
Optional, PDF-Only
- Options:
-
false
-
true
Ignore default style sheets.
prince_options[no_embed_fonts]
Optional, PDF-Only
- Options:
-
false
-
true
Disable font embedding in PDF output.
prince_options[no_subset_fonts]
Optional, PDF-Only
- Options:
-
false
-
true
Disable font subsetting in PDF output.
prince_options[no_compress]
Optional, PDF-Only
- Options:
-
false
-
true
Disable compression of PDF output.
prince_options[encrypt]
Optional, PDF-Only
- Options:
-
false
-
true
Encrypt PDF output.
prince_options[key_bits]
Optional, PDF-Only
- Options:
-
40
-
128
Set encryption key size.
prince_options[user_password]
Optional, PDF-Only
Set PDF user password.
prince_options[owner_password]
Optional, PDF-Only
Set PDF owner password.
prince_options[disallow_print]
Optional, PDF-Only
- Options:
-
false
-
true
Disallow printing of PDF output.
prince_options[disallow_copy]
Optional, PDF-Only
- Options:
-
false
-
true
Disallow copying from PDF output.
prince_options[allow_copy_for_accessibility]
Optional, PDF-Only, Pipeline 9+
- Options:
-
false
-
true
Allow copying content for accessibility purposes even when copying is disallowed by
disallow_copy
.
Pipelines prior to Pipeline 9 allowed copying content for accessibility when using
disallow_copy
.
prince_options[disallow_annotate]
Optional, PDF-Only
- Options:
-
false
-
true
Disallow annotation of PDF output.
prince_options[disallow_modify]
Optional, PDF-Only
- Options:
-
false
-
true
Disallow modification of PDF output.
prince_options[allow_assembly]
Optional, PDF-Only, Pipeline 9+
- Options:
-
false
-
true
Allow document assembly even when other modifications are disallowed by
disallow_modify
.
Pipelines prior to Pipeline 9 allowed document assembly when using
disallow_modify
.
prince_options[input]
Optional, PDF-Only
- Options:
-
html
-
xml
-
auto
Specify the input type of the document to be used by Prince during processing.
prince_options[css_dpi]
Optional, PDF-Only
- Options:
-
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.
prince_options[profile]
Optional, PDF-Only
- Options: see table below
If you need PDF profile support (Pipeline 3+ only), you can set this option. See Prince's documentation for details.
Option | Pipelines |
---|---|
PDF/A-1a | 7+ |
PDF/A-1b | 3+ |
PDF/A-2a | 9+ |
PDF/A-2b | 9+ |
PDF/A-3a | 7+ |
PDF/A-3b | 6+ |
PDF/UA-1 | 7+ |
PDF/X-1a:2001 | 6+ |
PDF/X-1a:2003 | 6+ |
PDF/X-3:2002 | 6+ |
PDF/X-3:2003 | 4+ |
PDF/X-4 | 4+ |
PDF/A-1a+PDF/UA-1 | 7+ |
PDF/A-2a+PDF/UA-1 | 9+ |
PDF/A-3a+PDF/UA-1 | 7+ |
prince_options[pdf_title]
Optional, PDF-Only
The title of your PDF, part of the document's metadata. Many PDF viewers use the title as the name of your document. This setting is primarily used for XML-based PDFs as HTML documents automatically use the text of the HTML <title>
element.
Asynchronous Options
async
Optional
- Options:
-
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 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.
{
"status_id": "123454321"
}
Making an authenticated request against https://docraptor.com/status/{status_id}
will give you the status of your document job. The returned JSON from that call should look something like:
{
"download_url": "https://docraptor.com/download/12345asdf",
"message": "Completed at Mon Jun 06 18:33:17 +0000 2011",
"number_of_pages": 2,
"status": "completed"
}
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 URL from which you can download your doc. This download URL can be used to download your document up to 5 times, and will expire after your account's data retention period. For accounts with the "as short as possible" data retention setting, documents can only be downloaded once.
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
.
Our client libraries include links to asynchronous examples on GitHub.
Note: If there is an error creating your document, the callback_url
will never be called. The status page will explain the error.
callback_url
Optional
When set and the async
option 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, and a download_id
, which will correspond to the status_id
returned by the document creation call.
If the callback URL does not return a 2XX HTTP status code within 10 seconds, we will retry the callback up to three times.
Note: If there is an error creating your document, the callback_url
will never be called. The status page will explain the error.
Hosted Options
hosted
Optional
- Options:
-
false
-
true
Creates a hosted document when set to
true
. Hosted documents are a paid add-on.
Asynchronous documents work as usual, except that the download URL in the final status response will be an unbranded domain. Synchronous hosted document requests respond with a JSON object rather than a binary blob. The JSON will look like this:
{
"download_id": "123-456-abc",
"download_url": "http://<<unbranded domain>>/download/123-456-abc",
"number_of_pages": 1
}
The download URL is publicly-accessible and doesn't require authentication.
By default, hosted documents do not having limits on downloads or hosting time, though you may pass additional parameters to the document generation call to set your own limits (see below).
hosted_download_limit
Optional, only available when hosted is true
- Options:
-
10
-
20
- ...
-
100
- ...
-
500
-
1000
When set and the hosted
option is set to true
, the
hosted_download_limit
option allows you to restrict the number of times the
hosted document can be downloaded. This attribute can be set to any number. Once the
number of downloads has been reached, the document will be made unavailable for download
and permanently removed from DocRaptor.
If no limit is specified, hosted documents will be available for an unlimited number of downloads. You may manually expire a hosted document at any time.
Test documents are limited to 5 downloads regardless of the value you provide for this option.
Keep in mind, hosted documents are a paid add-on and each download of a hosted document is
billed at a rate set by your plan. Limiting the number of downloads by setting
hosted_download_limit
can help control costs.
hosted_expires_at
Optional, only available when hosted is true
- Examples:
-
2024-12-10T 5:50:29
-
2024-12-10T05:50:29Z
-
2024-12-10T05:50:29+00:00
When set and the hosted
option is set to true
, the
hosted_expires_at
option will allow hosted documents to be available for
download until a specific date and time. The value for this attribute must be a properly
formatted ISO 8601 date time, specifically down to the second, with the optional addition of
a timezone offset. This option will be stored in the UTC timezone.
Once the hosted_expires_at
time has been reached, the document will be made
unavailable for download and permanently removed from DocRaptor.
If no expiration is specified, the document will be available for download indefinitely. You may manually expire a hosted document at any time.
Test documents documents will expire after 1 day regardless of the value you provide for this option.
Keep in mind, hosted documents are a paid add-on and each download of a hosted document is
billed at a rate set by your plan. Limiting the time a document is available by setting
hosted_expires_at
can help control costs.
Miscellaneous Options
strict
Optional, PDF-Only
- Options:
-
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.
help
Optional
- Options:
-
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.
tag
Optional
- Example:
-
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.