Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

iLovePDF Api - Ruby Library

Build Status GitHub version License: MIT

A library in ruby for iLovePDF Api

You can sign up for a iLovePDF account at

Develop and automate PDF processing tasks like:

  • Compress PDF
  • Merge PDF
  • Split PDF
  • Convert Office to PDF
  • PDF to JPG
  • Images to PDF
  • Add Page Numbers
  • Rotate PDF
  • Unlock PDF
  • Protect PDF
  • Stamp a Watermark
  • Repair PDF
  • PDF to PDF/A
  • Validate PDF/A
  • Extract
  • Sign PDF

Each one with several settings to get your desired results.


Ruby 2.6 or greater


Add this line to your application's Gemfile:

gem 'ilovepdf'

And then execute:

$ bundle

Or install it yourself as:

$ gem install ilovepdf


Getting started

The quickest way to get started is to first get a set of API keys here and run the following code snippet:

public_key  = 'YOUR_PUBLIC_KEY'
private_key = 'YOUR_PRIVATE_KEY'
ilovepdf =, private_key)
# Create a task with the tool you want to use:
task = ilovepdf.new_task :compress
# Add the files you want to upload...
file1 = task.add_file 'my_disk/my_example1.pdf'
file2 = task.add_file 'my_disk/my_example2.pdf'
file3 = task.add_file_from_url 'http://URL_TO_PDF'
# Once you are done uploading your files:

That's it!

For a more in-depth usage, refer to the sample codes in this repository.

Signature Tool

The usage of this tool is different than the other tools, the following example shows how to create a signature using the iLovePDF API:

my_task =, priv_key)
# File object keeps information about its server_filename and the properties you can set
file  = my_task.add_file '/path/to/file/sample.pdf'

signer =,'name','')

signature_element =
signature_element.set_position(x: 20, y: -20)
signature_element.pages = "1"
signature_element.size = 40

signer << signature_element
body = my_task.send_to_sign.body

For a more in-depth usage, refer to all of the signature examples on the sample codes in this repository.



All PDF tools have the following methods that contact with the iLovePDF API:

Method Description Notes
add_file(file) Uploads a file to iLovepdf servers Returns boolean
add_file_from_url(url) Uploads a file to iLovepdf servers using a URL Returns boolean
delete_file(file) Deletes a file from ilovepdf Returns boolean
download(filepath) Downloads the processed file Returns boolean; No need to specify a filepath
status Retrieves the current status of the task being processed Returns Ilovepdf::Response
execute Sends a request to Ilovepdf to begin processing the PDFs Returns Ilovepdf::Response
delete! Deletes the task Returns Ilovepdf::Response


imagepdf_task =, secret_key)
http_response = imagepdf_task.execute
puts http_response.body
  puts "Your file was downloaded successfully!"

Methods common to all tools

Method Description Notes
enable_file_encryption(boolean, key) The key will be used to decrypt the files before processing and re-encrypt them after processing If no key provided, a random key is assigned (default: false)
assign_meta_value(key, value) More info
ignore_errors More info (default: true)
ignore_password More info (default: true)
try_pdf_repair When a PDF to process fails we try to repair it automatically (default: true)
packaged_filename This allows you to specify the filename of the compressed file in case there is more than 1 file to be downloaded
output_filename The final name of the processed file

Methods to query after performing the execute API method:

  • result: It has stored the last Ilovepdf::Response

Methods to query after performing the download API method:

  • download_info: Returns a struct with the following info
    • :output_filename
    • :output_file
    • :output_filetype

Tool attributes

All tools have specific attributes you can access and modify. If you need want to know which params are available for a specific tool via the code, you can by looking at the API_PARAMS of that particular tool. For example for the Image to PDF tool:

puts Ilovepdf::Tool::Imagepdf::API_PARAMS
# => [:orientation, :margin, :pagesize]

To instantiate a Compress tool task directly do:

compress_task =, secret_key)

Handling errors

Whenever there is an API Error in one of the endpoints, you can try to capture it the following way:

  compress_task =, secret_key)
  compress_task.execute # Oops, this raises an error! I forgot to upload a file!
rescue Ilovepdf::ApiError => e
  # Let's check what went wrong with the API call:
  puts e.http_response.body

For a more complete example of error handling check samples/try_catch_errors.rb

Please see for up-to-date documentation.


The gem is available as open source under the terms of the MIT License.