PDFify

Introduction

The PDFify API allows you to convert HTML content to high-quality PDF documents programmatically. Our API is designed to be simple, reliable, and fast.

Base URL

https://api.pdfify.com/v1

Authentication

All API requests require authentication using an API token. Include your token in the Authorization header of each request.

curl https://api.pdfify.com/v1/convert \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"html": "<h1>Hello World</h1>"}'

You can create and manage your API tokens in the API Tokens section of your dashboard.

Quick Start

Here's a simple example to get you started with converting HTML to PDF:

                curl -X POST https://api.pdfify.com/v1/convert \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "html": "<html><body><h1>Hello World</h1></body></html>",
    "options": {
      "format": "A4",
      "margin": "20mm"
    }
  }' \
  --output document.pdf
              

                const response = await fetch('https://api.pdfify.com/v1/convert', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    html: '<html><body><h1>Hello World</h1></body></html>',
    options: {
      format: 'A4',
      margin: '20mm'
    }
  })
});

const blob = await response.blob();
// Save or use the PDF blob
              

                import requests

url = 'https://api.pdfify.com/v1/convert'
headers = {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Content-Type': 'application/json'
}
data = {
    'html': '<html><body><h1>Hello World</h1></body></html>',
    'options': {
        'format': 'A4',
        'margin': '20mm'
    }
}

response = requests.post(url, headers=headers, json=data)

with open('document.pdf', 'wb') as f:
    f.write(response.content)
              

                require 'net/http'
require 'json'

uri = URI('https://api.pdfify.com/v1/convert')
request = Net::HTTP::Post.new(uri)
request['Authorization'] = 'Bearer YOUR_API_TOKEN'
request['Content-Type'] = 'application/json'
request.body = {
  html: '<html><body><h1>Hello World</h1></body></html>',
  options: {
    format: 'A4',
    margin: '20mm'
  }
}.to_json

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end

File.write('document.pdf', response.body)
              

Ruby Gem (pdfify-client)

For Ruby and Rails applications, we provide an official gem that makes PDF generation even simpler.

Installation

Add this line to your application's Gemfile:

gem 'pdfify-client'

And then execute:

bundle install

Configuration

For Rails applications, create an initializer at config/initializers/pdfify.rb:

PDFify.configure do |config|
  config.api_key = ENV['PDFIFY_API_KEY']
  # Or use Rails credentials:
  # config.api_key = Rails.application.credentials.pdfify_api_key

  # Optional configuration
  config.base_url = "https://api.pdfify.com" # default
  config.timeout = 60  # seconds, default is 60
end

Basic Usage

Converting HTML to PDF is simple:

require 'pdfify'

# Simple conversion
pdf = PDFify.convert(html: "<h1>Hello World!</h1>")

# Save to file
File.binwrite("output.pdf", pdf)

Rails Integration

Here's an example controller action that generates and downloads a PDF:

class ReportsController < ApplicationController
  def download_pdf
    # Render your template to HTML
    html = render_to_string(
      template: "reports/invoice",
      layout: "pdf"
    )

    # Convert to PDF
    pdf = PDFify.convert(html: html)

    # Send to user
    send_data pdf,
              type: "application/pdf",
              disposition: "attachment",
              filename: "invoice-#{@invoice.id}.pdf"
  end
end

Advanced Options

The gem supports various options for customizing PDF generation:

pdf = PDFify.convert(
  html: "<h1>Advanced</h1>",
  profile: "docraptor",           # DocRaptor compatibility
  css: "body { color: red; }",    # Additional CSS
  auto_compat: true,               # Auto-detect compatibility
  template_engine: "pdfshift",    # Specify engine
  test: true                       # Test mode (doesn't count against quota)
)

Error Handling

The gem provides specific error classes for different failure scenarios:

begin
  pdf = PDFify.convert(html: "<h1>Test</h1>")
  File.binwrite("output.pdf", pdf)
rescue PDFify::QuotaExceededError => e
  puts "Quota exceeded: #{e.message}"
rescue PDFify::ValidationError => e
  puts "Invalid input: #{e.message}"
rescue PDFify::AuthenticationError => e
  puts "Authentication failed: #{e.message}"
rescue PDFify::APIError => e
  puts "API error: #{e.message}"
end

Migrating from DocRaptor

Switching from DocRaptor is straightforward:

DocRaptor

DocRaptor.configure do |config|
  config.username = "YOUR_API_KEY"
end

docraptor = DocRaptor::DocApi.new
pdf = docraptor.create_doc(
  document_content: html,
  document_type: "pdf",
  test: true
)

PDFify.configure do |config|
  config.api_key = "YOUR_API_KEY"
end

pdf = PDFify.convert(
  html: html,
  profile: "docraptor",
  test: true
)

DocRaptor Compatibility: Use profile: "docraptor" for maximum compatibility with existing DocRaptor templates.

Additional Resources

GitHub Repository
Full API documentation and examples included in the gem
MIT Licensed - Free to use in commercial projects

Convert HTML to PDF

The main endpoint for converting HTML content to PDF documents.

POST /v1/convert

Request Body

Parameter	Type	Required	Description
html	string	Yes	The HTML content to convert
url	string	No	URL to fetch HTML from (alternative to html)
options	object	No	PDF generation options (see below)

Options Object

Option	Type	Default	Description
format	string	A4	Paper format (A4, Letter, Legal, etc.)
margin	string	10mm	Page margins (CSS units)
landscape	boolean	false	Use landscape orientation
print_background	boolean	true	Include background graphics
header_template	string	null	HTML template for header
footer_template	string	null	HTML template for footer

Responses

Success Response

On success, the API returns the PDF file as binary data with a 200 OK status code.

Response Headers:

Content-Type: application/pdf
Content-Disposition: attachment; filename="document.pdf"

Error Response

Errors return a JSON object with details about what went wrong.

{
  "error": {
    "code": "invalid_html",
    "message": "The provided HTML is invalid or empty",
    "details": "HTML content cannot be blank"
  }
}

Error Codes

Code	Status	Description
invalid_token	401	The API token is invalid or missing
invalid_html	400	The HTML content is invalid or empty
rate_limit_exceeded	429	You've exceeded your rate limit
quota_exceeded	429	You've reached your monthly PDF quota
file_too_large	413	The input or output file is too large
internal_error	500	An internal server error occurred

Webhooks

For long-running conversions, you can configure webhooks to receive notifications when your PDF is ready.

Coming Soon: Webhook support is currently in development and will be available soon on Pro and Enterprise plans.

Rate Limits

Rate limits are enforced to ensure fair usage and system stability. Limits vary by plan:

Plan	Requests/Minute	Burst Limit
Starter	10	20
Professional	60	120
Enterprise	Custom	Custom

Best Practices

Use Semantic HTML

Well-structured HTML produces better PDFs. Use semantic tags and proper CSS for optimal results.

Optimize CSS

Include all CSS inline or in the HTML document. External stylesheets may not load correctly.

Handle Errors Gracefully

Always check response status codes and handle errors appropriately in your application.

Cache When Possible

If generating the same PDF multiple times, consider caching the result to reduce API calls.

API Documentation