This is the documentation for the legacy Pdfcrowd API v1. We strongly recommend the new improved Pdfcrowd API v2 for new integrations.
An API call is made by sending an HTTP request to the API endpoint with parameters passed as POST data. The API endpoints support both http and https schemes.
The following parameters are used for authentication and must be present in every API call.
Parameter | Description |
---|---|
username | Your username at Pdfcrowd |
key | API key. Can be found on your account page. Note that the key is regenerated when you change your password. |
A PDF document can be created in one of the following ways. The created PDF is returned in the response body.
Convert a web page | |
---|---|
Method | POST |
API Endpoint | http://pdfcrowd.com/api/pdf/convert/uri/ |
Content Type | application/x-www-form-urlencoded |
Post Data |
Mandatory
|
Convert a local HTML file | |
---|---|
Method | POST |
API Endpoint | http://pdfcrowd.com/api/pdf/convert/html/ |
Content Type | multipart/form-data |
Post Data |
Mandatory
|
Convert raw HTML code | |
---|---|
Method | POST |
Content Type | application/x-www-form-urlencoded |
API Endpoint | http://pdfcrowd.com/api/pdf/convert/html/ |
Post Data |
Mandatory
|
The following optional parameters control properties of the generated PDF file.
Page Setup
Parameter | Description |
---|---|
width | PDF page width in units. |
height | PDF page height in units. -1 for a single page PDF. |
margin_top | Top PDF page margin in units. |
margin_right | Rigth PDF page margin in units. |
margin_bottom | Bottom PDF page margin in units. |
margin_left | Left PDF page margin in units. |
hmargin | Deprecated. Use margin_left and margin_right instead. |
vmargin | Deprecated. Use margin_top and margin_bottom instead. |
Some parameters can be specified in inches (in), millimeters (mm), centimeters (cm), or points (pt). If no units are specified, points are assumed.
Examples: 210mm
, 8.5in
Header and Footer
Parameter | Description |
---|---|
footer_html | Places the specified HTML code
inside the page
footer. The following variables are expanded:
|
footer_url | Loads HTML code from the specified URL and places it inside the page footer. See footer_html for the list of variables that are expanded. |
header_html | Places the specified HTML code inside the page header. See footer_html for the list of variables that are expanded. |
header_url | Loads HTML code from the specified URL and places it inside the page header. See footer_html for the list of variables that are expanded. |
header_footer_page_exclude_list | A comma
seperated list of physical page numbers on which the header a
footer are not printed. Negative numbers count backwards from
the last page: -1 is the last page, -2 is the last but one
page, and so on. Example: "1,-1" will not print the header and footer on the first and the last page. |
page_numbering_offset | An offset between
physical and logical page numbers. The default value is 0. Example: if set to "1" then the page numbering will start with 1 on the second page. |
HTML options
PDF Options
Parameter | Description |
---|---|
encrypted | Encrypts the PDF. This prevents search engines from indexing the document. |
author | Sets the PDF author field. |
user_pwd | Protects the PDF with an user password. When a PDF has an user password, it must be supplied in order to view the document and to perform operations allowed by the access permissions. At most 32 characters. |
owner_pwd | Protects the PDF with an owner password. Supplying an owner password grants unlimited access to the PDF including changing the passwords and access permissions. At most 32 characters. |
no_print | Do not allow to print the generated PDF. |
no_modify | Do not allow to modify the PDF. |
no_copy | Do not allow to extract text and graphics from the PDF. |
page_layout |
Specifies the initial page layout when the PDF is opened in a viewer:
|
initial_pdf_zoom_type |
Specifies the initial page zoom type when the PDF is opened in a viewer:
|
initial_pdf_zoom | Specifies the initial page zoom when the PDF is opened in a viewer. Defaults to 100%. |
page_mode | Specifies the appearance of the PDF when opened:
|
max_pages | Prints at most the specified number of pages. |
pdf_name | The file name of the created PDF (max 180 chars). If not specified then the name is auto-generated. |
pdf_scaling_factor | The scaling factor used to convert between HTML and PDF. The default value is 1.333 (4/3) which makes the PDF content up to 1/3 larger than HTML. |
page_background_color | The page background color in RRGGBB hexadecimal format. |
transparent_background | Do not print the body background. Requires the following CSS rule to be declared:body {background-color:rgba(255,255,255,0.0);}
|
Watermark
Parameter | Description |
---|---|
watermark_url | A public absolute URL of the watermark image (must start either with http:// or https://). The supported formats are PNG and JPEG. |
watermark_offset_x | The horizontal watermark offset in units. The default value is 0. |
watermark_offset_y | The vertical watermark offset in units. The default value is 0. |
watermark_rotation | The watermark rotation in degrees. |
watermark_in_background | When set then the watermark is be placed in the background. By default, the watermark is placed in the foreground. |
Miscellaneous
The following command converts www.google.com
to PDF:
$ curl -F "username=$username" -F "key=$apikey" \ > -F 'src=http://www.google.com' \ > http://pdfcrowd.com/api/pdf/convert/uri/ > google_com.pdf
The following command converts the output of some html_producer
application to PDF and protects it with an user password:
$ html_producer | curl -F "username=$username" -F "key=$apikey" \ > -F 'src=<-' \ > -F 'user_pwd=secret' \ > http://pdfcrowd.com/api/pdf/convert/html/ > google_com.pdf
The following command converts a local file index.html
to PDF
and disables printing:
$ curl -F "username=$username" -F "key=$apikey" \ > -F 'src=@index.html' \ > -F 'no_print=1' \ > http://pdfcrowd.com/api/pdf/convert/html/ > google_com.pdf
Note, that the examples above ignore errors. If the API call
fails google_com.pdf
will contain an error message instead of
PDF. For convenience, Pdfcrowd provides a shell wrapper
around curl
that checks for errors and generally makes the
interaction with the API from the command line friendlier.
Number of remaining credits | |
---|---|
Method | POST |
API Endpoint | http://pdfcrowd.com/api/user/<username>/tokens/ |
Content Type | application/x-www-form-urlencoded |
Post Data | Mandatory |
The response contains the result in plain text.
$ curl -F "username=$username" -F "key=$apikey" \ > "http://pdfcrowd.com/api/user/$username/tokens/" $ 12399
The API returns the standard HTTP response status codes. These are the most important ones:
Code | Description |
---|---|
200 OK | The API call succeeded. |
400 Bad Request | The user sent an invalid request. The body of the response contains an explanation in plain text. |
413 Request Entity Too Large | See Limitations below. |
502 Bad Gateway | See Limitations below. |
503 Service Unavailable | See Limitations below. |
510 | A non-standard status code indicating that the server couldn't process the request. The body of the response contains an explanation in plain text. |
Pdfcrowd provides a
shell
script which wraps curl
and provides more convenient access
to the API from shell.
The script reads options from ~/.pdfcrowd
and then from the
command line. You can store your default options to ~/.pdfcrowd
,
one option per line:
$ cat > ~/.pdfcrowd <<! > -username $username > -key $apikey > -width 210mm > -height 297mm > !
Now, you can run:
$ pdfcrowd.sh http://www.google.com > google_com.pdf $ pdfcrowd.sh /path/to/local/file > html.pdf $ html_producer | pdfcrowd.sh - > file.pdf $ echo "remaining credits: $(pdfcrowd.sh @)"
On success, exit status 0 is returned and the result is written
to stdout
. Otherwise, non-zero exit status is returned and the
error message is written to stderr
. Run the script
with -help
to get the list of available options.
We understand that your data may be sensitive and confidential and that it is absolutely unacceptable to disclose it or keep unnecessary copies.
We want to be transparent about how we process your data, so here we describe an API conversion request lifecycle:
The following limits are applied to ensure fair distribution of capacity.
If you find the limits too restrictive we can provision a private server optimized for your specific needs with the limits lifted. If you would like to discuss this option please contact us.
The API returns an HTTP 503 Service unavailable status code in the following cases:
Ideally, you should serialize your API calls. However, we understand that you can't always ensure this in some environments, such as for instance with Google App Engine Task Queue. In such cases it is perfectly acceptable to check for this error and possibly send the failed request again.
If a request takes more than 40 seconds to complete it is cancelled and either of these messages may be returned:
A typical cause of this error is too many images on an HTML page which take too long to download. Another cause might be a long running JavaScript.
If the size of the uploaded data exceeds 20MB then an HTTP 413 Request entity too large error is returned. You can zip your HTML to avoid this error.
If the size of the downloaded data exceeds 100MB then the an HTTP 502 error code is returned.
We return an HTTP 502 error code also when: