REST API reference

Introduction

The iLovePDF API is organized around the REST standard, having a predictable resource-oriented URLs through HTTP methods where obtain the information in JSON format.

We support cross-origin resource sharing, allowing you to interact securely with our API from a client-side. Although you should never expose your secret API key in the client-side code.

To start developing, register to iLovePDF Developers and you will be provided with a free account. This account comes with a free 250 files limit to process each month. However, if you need more, you can acquire more files from our Pricing page.

Before we begin, we recommend that you import our Postman Collection & Environment from the table on the right and use it as a playground. If you are logged in, the last active project credentials will automatically appear inside the environment. Remember to select the environment before calling any request from the collection.

PDF & Signature Libraries
iLovePDF PHP LibraryPHP
iLovePDF .Net Library.Net
iLovePDF Ruby LibraryRuby
iLovePDF Node.js LibraryNode.js
iLovePDF Postman api callsPostman
Image Libraries
iLoveIMG PHP LibraryPHP
iLoveIMG Postman api callsPostman

Quick Start

This Reference is for developers who wish to create their own API library or for those who don't find their preferred library in our library compatibility list. The quickest way to start using our API is to:

  • Register as a developer.
  • Get a Project ID and its related Secret Key from the API Keys section of your console.
  • Download one of our API Libraries.
  • Try out our demos in the API Library.
  • Lastly, remember to read this documentation!

If you have any comments or suggestions for this documentation or the API, please don’t hesitate to contact us.

Authentication

We are using a very simple but effective Authentication method: JWT, JSON Web Tokens. It consists of sending a Bearer Header in every request with a signed token by your Secret Key provided in your iLovePDF API Developer Account. Your Secret Key may never be exposed, but the signed token can be exposed and you must send it in every header request parameter Authorization: Bearer {signed_token}. Take into account that all signed tokens expire after 2 hours. All our API Libraries manage the authentication automatically. You only need to set your Private Key and your Public Key in the API Library.

If you are developing your own library/requests, there are two methods for getting the signed token. One method is by self signing it (recommended for server side code) and the other is by requesting it to our Authentication server (recommended for client side code).

Self-signed token

You must use your secret and public key pair to generate the signed token to send in to the Authorization: Bearer {signed_token} header of every request. You can find the JWT libraries directly on the JWT official website. Remember: The claims exp, nbf and iat must be in UTC timezone.

Request signed token from our authentication server

When you send a request to the /auth resource, you will receive the token to use in your Authorization: Bearer {signed_token} that you'll send in every request (/start, /upload, /process, /download). We strongly recommend that you activate filters by domain and IP if you need to request the token from our /auth server. This way, only the requests made from the domains you set will be accepted. Remember that the token has an expiration date and must be requested again.

Authenticate
https://api.ilovepdf.com/v1/auth
public_key
string
Project public key that you can find in admin panel.
Response

PDF & Image

Request workflow

The PDF and Image processing workflow with iLoveAPI is very simple and consists of 4 basic request instructions: Start task, Upload files, Process files and Download files. Once the API has executed these four steps, your PDF and Image files will have been processed with your desired tool and downloaded anywhere you like.

Below you will see a complete reference to these 4 requests and the parameters for each step.

Workflow diagram

Start

Retrieve the information about which server will be your assigned server and which Task ID to use. The request must contain the tool you want to access.

Get Server & Task ID
https://api.ilovepdf.com/v1/start/{tool}
tool
string
PDF tools: compress, extract, htmlpdf, imagepdf, merge, officepdf, pagenumber, pdfa, pdfjpg, pdfocr, protect, repair, rotate, split, unlock, validatepdfa, watermark.
Image tools: compressimage, cropimage, convertimage, removebackgroundimage, repairimage, resizeimage, rotateimage, upscaleimage, watermarkimage.
Response

Upload

This is the second step of the Task. Here is where you upload your files for a given task. The files will be uploaded and stored in the server until the process order is sent (Step 3 of a Task).

It accepts chunk file upload. When uploading a chunk file, if the last chunk is sent and some of the previous chunks are missing it will throw an error. Finally, files can be uploaded either from local or web sources.

Upload file
https://{server}/v1/upload
Source file is local
If the uploaded source file is local, the data must be sent using form-data request type.
task
string
Task ID where the files must be uploaded.
file
File
File to be uploaded.
chunk
integer
If it is a chunk upload this number indicates the number of chunks being uploaded. Always send the chunks in order. First chunk must be 0.
chunks
integer
If it is a chunk upload this number indicates the total number of chunks for this file.
Source file is from the cloud
task
string
Task ID where the files must be uploaded.
cloud_file
string
Public URL of the file.
Remove an already uploaded file from server
https://{server}/v1/upload/{task}/{server_filename}
Response

Process

Once the files are uploaded for the Task, this resource initiates the processing of all files. In the request, you must specify which files you want to process from the uploaded ones in Step 2 (Upload). This means that you can request to process fewer files than the uploaded ones. If some files have an error while processing, you can check their status in the table of File Status Types. If the error is WrongPassword the response will throw a 400 error. However, the Task Status would be kept as TaskWaiting so you can try to resend the request to process files using the required passwords.


When sending the request, you need to wait until the process is finished. However, if you don't want to wait, you can use the webhook parameter.

Process files
https://{server}/v1/process
task
string
Task ID to be processed.
tool
string
Accepted values for PDF tools: merge, split, compress,pdfocr, pdfjpg, imagepdf, unlock, pagenumber, watermark, officepdf, repair, rotate, protect, pdfa, validatepdfa, htmlpdf, extract.

Image tools: resizeimage, cropimage, compressimage, upscaleimage, removebackgroundimage, convertimage, watermarkimage, repairimage, rotateimage
files
array
Files to process. The order of the array will be the order that files will be processed. The files has the following attributes:
server_filename
string
Server file name.
filename
string
Original filename of the file to process.
rotate
integer
Rotation to apply before process. Accepted values: 0, 90, 180, 270.
0
password
string
Password to open the file in case of having one.
metas
array
Optional PDF metadata information which can be inserted or modified.
Title
string
The title of the document.
Author
string
The name of the person who created the document.
Subject
string
The subject of the document.
Keywords
string
Keywords associated with the document.
Creator
string
If the document was converted to PDF from another format, the name of the application that created the original document from which it was converted.
Producer
string
If the document was converted to PDF from another format, the name of the application that converted it to PDF.
CreationDate
string
The date and time the document was created, in human-readable form.
ModDate
string
The date and time the document was most recently modified, in human-readable form.
Trapped
string
A name object indicating whether the document has been modified to include trapping information. Values true, false or unknown.
ignore_errors
boolean
Force process although some of the files are damaged or throw an error. If damaged/error files are equal to total files to process, this value does not take effect. On successful response, all files with errors will be listed as warnings. Values: true, false.
true
ignore_password
boolean
Force process although some of the files require a password. If files that require a password are equal to total files to process, this value does not take effect. Values: true, false.
false
output_filename
string
{date}=current date, {n}=file number, {filename}=original filename, {tool}=the current processing action. Example: file_{n}_{date}.
packaged_filename
string
If there are more than one output files, they will be compressed into a ZIP file. Specify the filename of the compressed file. {date}=current date, {n}=file number, {filename}=original filename, {tool}=the current processing action. Example: file_{n}_{date}.
output
file_encryption_key
string
If specified, all previously uploaded files for the task will be uploaded encrypted. The key will be used to decrypt the files before processing and re-encrypt them after processing. Only key sizes of 16, 24 or 32 characters are supported.
try_pdf_repair
boolean
When a PDF file fails to be processed, we try to repair it automatically.
true
try_image_repair
boolean
When an image file fails to be processed, we try to repair it automatically.
true
custom_int
integer
Use this parameter to store integers as you wish. You can use it to filter your tasks in the GET /task resource.
custom_string
string
Use this parameter to store integers as you wish. You can use it to filter your tasks in the GET /task resource.
webhook
string
Callback URL. If you don't want to maintain the connection open until the task processing is finished, send webhook equal and a valid URL. The API will close the connection immediately and will POST all the /task resource information to the URL provided. Optionally this parameter can be equal to empty string. When is equal to empty string, the behaviour will be the same but no callback will be sent, this is useful if you don't want to wait the process to end or receive callbacks giving you the freedom of send periodic GET calls to /task/{task} to know the status of that task and if it has been completed.
For security reasons, you need to register the webhook endpoint in your dashboard.
Merge PDF extra parameters
Merge PDF has no extra parameters
Split extra parameters
split_mode
string
Accepted values:
  • ranges: define different ranges of pages, {ranges} parameter is required.
  • fixed_range: define a fixed range of pages to split the PDF., {fixed_range} parameter is required.
  • remove_pages: remove pages from a PDF, {remove_pages} parameter is required.
ranges
ranges
string

Page ranges to split the files. Every range will be saved as a different PDF file.

Example format: 1,5,10-14

fixed_range
integer

Page ranges to split the files. Every range will be saved as a different PDF file.

1
remove_pages
string

Pages to remove from a PDF. Accepted format: 1,4,8-12,16.

merge_after
boolean
Merge all ranges after being split. This param takes effect only when {mode} is range.
false
Compress extra parameters
compression_level
string
Compression level. Accepted values: extreme=Extreme compression, recommended=Recommended compression, low=Low compression.
recommended
PDF OCR extra parameters
ocr_languages
array
OCR languages to apply. Accepted values: eng, afr, amh, ara, asm, aze, aze_cyrl, bel, ben, bod, bos, bre, bul, cat, ceb, ces, chi_sim, chi_tra, chr, cos, cym, dan, deu, deu_latf, dzo, ell, enm, epo, equ, est, eus, fao, fas, fil, fin, fra, frm, fry, gla, gle, glg, grc, guj, hat, heb, hin, hrv, hun, hye, iku, ind, isl, ita, ita_old, jav, jpn, kan, kat, kat_old, kaz, khm, kir, kmr, kor, kor_vert, lao, lat, lav, lit, ltz, mal, mar, mkd, mlt, mon, mri, msa, mya, nep, nld, nor, oci, ori, pan, pol, por, pus, que, ron, rus, san, sin, slk, slv, snd, spa, spa_old, sqi, srp, srp_latn, sun, swa, swe, syr, tam, tat, tel, tgk, tgl, tha, tir, ton, tur, uig, ukr, urd, uzb, uzb_cyrl, vie, yid, yor
eng
PDF to JPG extra parameters
pdfjpg_mode
string
Accepted values: pages=Convert every PDF page to a JPG image, extract=extract all PDF's embedded images to separate JPG images.
pages
Image to PDF extra parameters
orientation
string
Accepted values: portrait, landscape.
portrait
margin
integer
Define a margin in pixels for the image in the output PDF.
0
pagesize
string
Page size of the output PDF.
  • fit: PDF page is the same size of image.
  • A4
  • letter
fit
merge_after
boolean
Serve all converted images in an unique PDF if true. If false, serve every image into a separate PDF.
true
Unlock PDF extra parameters
Unlock PDF has no extra parameters
Page numbers extra parameters
facing_pages
boolean
Define it to true if the PDF is in facing page mode.
false
first_cover
boolean
If the first page is a cover page, it will not be numbered.
false
pages
string
Pages to be numbered. Accepted formats:
  • all
  • 3-end
  • 1,3,4-9
  • -2-end
  • 3-234
all
starting_number
integer
Start page numbering with this number.
1
vertical_position
string
Define if page number will be at top or bottom. Accepted values: bottom, top.
bottom
horizontal_position
string
Allows you to position the number on the left, in the center or on the right of the page. However, if the parameter facing_pages is set to true, facing pages will have their page numbers positioned symmetrically, on the left and the right.Accepted values: left, center, right.
center
vertical_position_adjustment
integer
Adjust the number of pixels displaced from the standard vertical_position. It accepts positive and negative values.
horizontal_position_adjustment
integer
Adjust the number of pixels displaced from the standard horizontal_position. It accepts positive and negative values.
font_family
string

Accepted values: Arial, Arial Unicode MS, Verdana, Courier, Times New Roman, Comic Sans MS, WenQuanYi Zen Hei, Lohit Marathi.

Arial Unicode MS
font_size
integer
14
font_color
string
Hexadecimal color.
#000000
text
string
To define text in addition to the number, use {n} for current page number and {p} for total number of pages for the file. Example Page {n} of {p}. If null only the page number will be placed.
{n}
Watermark extra parameters
mode
string
Accepted values: text, image.
text
text
string
if mode is text
Text to be stamped. If mode is image this value does not take effect.
image
string
if mode is image
The image to stamp if mode is image. The stamped image must be uploaded in the /upload resource. This image parameter must refer to the server_filename (JPG or PNG) to stamp.
pages
string
Pages to be stamped. Accepted formats:
  • all
  • 3-end
  • 1,3,4-9
  • -2-end
  • 3-234
all
vertical_position
string
Accepted values: bottom, top, middle.
middle
horizontal_position
string
Accepted values: left, center, right.
center
vertical_position_adjustment
integer
Adjust the amount of offset pixels from the position defined in vertical_position. It accepts positive and negative values.
horizontal_position_adjustment
integer
Adjust the amount of offset pixels from the position defined in horizontal_position. It accepts positive and negative values.
mosaic
boolean
If true, this value overrides all position parameters and stamps the image or text 9 times per page.
false
rotation
integer
Angle of rotation. Accepted integer range: 0-360.
0
font_family
string

Accepted values: Arial, Arial Unicode MS, Verdana, Courier, Times New Roman, Comic Sans MS, WenQuanYi Zen Hei, Lohit Marathi.

Arial Unicode MS
font_style
string
Accepted values: null (Regular/Normal), Bold, Italic.
null
font_size
integer
14
font_color
string
Hexadecimal color.
#000000
transparency
integer
Percentage of opacity for stamping text or image. Accepted integer range 1-100.
100
layer
integer
above=Place stamp over content, below=Place stamp below content.
above
Office to PDF extra parameters
Office to PDF has no extra parameters
Repair PDF extra parameters
Repair PDF has no extra parameters
Rotate PDF extra parameters
Rotate PDF has no extra parameters
Protect extra parameters
password
string
Password with which the PDF file will be encrypted.
PDF to PDF/A extra parameters
conformance
string
Set the PDF/A conformance level. Accepted values: pdfa-1b, pdfa-1a, pdfa-2b, pdfa-2u, pdfa-2a, pdfa-3b, pdfa-3u, pdfa-3a.
pdfa-2b
allow_downgrade
boolean
Allows conformance downgrade in case of conversion error.
true
Validate PDF/A extra parameters
conformance
string
Set the PDF/A conformance level. Accepted values: pdfa-1b, pdfa-1a, pdfa-2b, pdfa-2u, pdfa-2a, pdfa-3b, pdfa-3u, pdfa-3a.
pdfa-2b
allow_downgrade
boolean
Allows conformance downgrade in case of conversion error.
true
HTML to PDF extra parameters
HTML to PDF has no extra parameters
Extract text extra parameters
detailed
boolean
Includes the following PDF properties separated by a comma: PageNo, XPos, YPos, Width, FontName, FontSize, Length and Text
Edit PDF extra parameters
elements
array
Elements to be added into the PDF. They can have several properties including the element type.
type
string
Type of element to be added. Accepted values: bottom, text, image, svg.
pages
string
The page where the element will be inserted. Only numbers format is allowed.
zindex
number
Depth value to decide elements order in case of overlay.
dimensions
object<w: float, h: float>
Size of the element following the format { x: 120, y: 200 }.
coordinates
object<x: float, y: float>
Position of the element in X and Y coordinates following the format { x: 120, y: 200 }.
rotation
integer
Angle of rotation. Accepted integer range: 0-360.
0
opacity
integer
Percentage of opacity for stamping element. Accepted integer range 1-100.
100

Each element type has its own properties. See the following for Text, Image and SVG:
text
type
The chosen element is a text and these are its properties:
text
string
Text to be written in the document.
text_align
string
Horizontal text alignment. Accepted values: left, center, right.
left
font_family
string
Font type of text. See Fonts compatibility for complete list.
Arial Unicode MS
font_size
integer
Size of text font in pixels.
14
font_style
string
Text font styles. Accepted values: Regular, Bold, Italic, Bold italic
Regular
font_color
string
Text font color. Can be set to transparent. Otherwise, the accepted value is hexadecimal.
#000000
letter_spacing
integer
Text letter spacing between characters. Accepted values from 0 to infinite.
0
underline_text
boolean
Text underline active or inactive. Values can be true or false.
false
image
type
The chosen element is an image and these are its properties:
server_filename
string
Upload resource that identifies the image. Accepted file formats: png, jpg, jpeg, jfif and gif.
svg
type
The chosen element is a SVG image type and these are its properties:
server_filename
string
Upload resource that identifies the image. Accepted file formats: svg.
Resize Image extra parameters
resize_mode
string

Choose the resize mode. Accepted values:

  • pixels: the resize will be set using pixels.
  • percentage: the resize will be set as a percentage of the original image.
pixels
pixels_width
integer
If resize_mode is pixels
The width in pixels of the resized image.
pixels_height
integer
If resize_mode is pixels
The height in pixels of the resized image.
percentage
integer
If resize_mode is percentage
The percentage value to resize.
maintain_ratio
boolean
If set as true, resize will keep aspect ratio and images will not be distort.
true
no_enlarge_if_smaller
boolean
Controls if the image can be gigger than the original on resize.
true
Crop Image extra parameters
width
integer
The width in pixels of the area to crop.
height
integer
The height in pixels of the area to crop.
x
integer
The horizontal point where start to crop.
0
y
integer
The vertical point where start to crop.
0
Compress Image extra parameters
compression_level
string
Compression level. Accepted values: extreme=Extreme compression, recommended=Recommended compression, low=Low compression.
recommended
Upscale image extra parameters
multiplier
integer
Upscale multiplier. Accepted values: 2, 4.
Background remove image extra parameters
Background remove image has no extra parameters
Convert Image extra parameters
to
string
The format to convert to. Accepted values are jpg, png, gif, gif_animation (static or animated) and heic. Convert to jpg can be (almost) from any image format. Convert to png and gif can be only from jpg images.
jpg
gif_time
integer
if to is gif_animated
Only for gif_animation, define the seconds per image, in hundredths of a second.
50
gif_loop
integer
if to is gif_animated
Set if animation stops at the end or loops forever.
true
Watermark Image extra parameters
elements
array
An array of elements to stamp. This means you can set multiple elements to stamp.
type
string
The type for the element. Accepted values: image or text.
text
text
string
if type is text
The text to stamp
image
string
if type is image
The stamp image must be uploaded in the Upload resource. This image parameter must referer to the server_filename (JPG or PNG).
gravity
string
Accepted values: North, NorthEast, NorthWest, Center, CenterEast, CenterWest, East, West, South, SouthEast, SouthWest.
Center
vertical_adjustment_percent
integer
Adjust how much space must modify the position of the position defined in gravity, based on a percent of the base image, it accepts positive and negative values.
0
horizontal_adjustment_percent
integer
Adjust how much space must modify the position of the position defined in gravity, based on a percent of the base image, it accepts positive and negative values.
0
rotation
integer
Angle of rotation. Accepted integer range: 0-360.
0
font_family
string
Accepted values: Arial, Arial Unicode MS, Verdana, Courier, Times New Roman, Comic Sans MS, WenQuanYi Zen Hei, Lohit Marathi.
0
font_style
string
Accepted values: null (Regular/Normal), Bold, Italic.
null
font_size
integer
14
font_color
string
Hexadecimal color.
#000000
transparency
integer
Percentage of opacity for stamping text or image. Accepted integer range 1-100.
100
mosaic
boolean
If true, this value overrides all position parameters and stamps the image or text 9 times per page.
false
Rotate Image extra parameters

Rotate tool has no options, just set rotation property in file.

Response
File status types
FileSuccess
This file has been processed successfully.
FileWaiting
This file is waiting to be processed.
WrongPassword
This file has not been processed because needed a password and was not provided or incorrect.
TimeOut
This file has not been processed correctly because it took more than your time limit to process it.
ServerFileNotFound
This file has not been processed because has not been found in the server.
DamagedFile
This file has not been processed because it was damaged or we were unable to read it.
NoImages
This file has not been processed because we couldn't find any images to extract. Maybe there are vectors?
OutOfRange
This file has not been processed because some of the ranges do not match the number of pages.
NonConformant
PDF file validation has not passed against PDF/A conformance provided.
UnknownError
Unknown Error.

Process

Once the files are uploaded for the Task, this resource initiates the processing of all files. In the request, you must specify which files you want to process from the uploaded ones in Step 2 (Upload). This means that you can request to process fewer files than the uploaded ones. If some files have an error while processing, you can check their status in the table of File Status Types. If the error is WrongPassword the response will throw a 400 error. However, the Task Status would be kept as TaskWaiting so you can try to resend the request to process files using the required passwords.


When sending the request, you need to wait until the process is finished. However, if you don't want to wait, you can use the webhook parameter.

Process files
https://{server}/v1/process
task
string
Task ID to be processed.
tool
string
Accepted values: resizeimage, cropimage, compressimage, convertimage, watermarkimage, repairimage and rotateimage.
files
array
Files to process. The order of the array will be the order that files will be processed. The files has the following attributes:
server_filename
string
Server file name.
filename
string
Original filename of the file to process.
rotate
integer
Rotation to apply before process. Accepted values: 0, 90, 180, 270.
0
password
string
Password to open the file in case of having one.
ignore_errors
boolean
Force process although some of the files are damaged or throw an error. If damaged/error files are equal to total files to process, this value does not take effect. On successful response, all files with errors will be listed as warnings. Values: true, false.
true
output_filename
string
{date}=current date, {n}=file number, {filename}=original filename, {tool}=the current processing action. Example: file_{n}_{date}.
packaged_filename
string
If there are more than one output files, they will be compressed into a ZIP file. Specify the filename of the compressed file. {date}=current date, {n}=file number, {filename}=original filename, {tool}=the current processing action. Example: file_{n}_{date}.
output
file_encryption_key
string
If specified, all previously uploaded files for the task will be uploaded encrypted. The key will be used to decrypt the files before processing and re-encrypt them after processing. Only key sizes of 16, 24 or 32 characters are supported.
try_image_repair
boolean
When an image file fails to be processed, we try to repair it automatically.
true
custom_int
integer
Use this parameter to store integers as you wish. You can use it to filter your tasks in the GET /task resource.
custom_string
string
Use this parameter to store integers as you wish. You can use it to filter your tasks in the GET /task resource.
webhook
string
Callback URL. If you don't want to maintain the connection open until the task processing is finished, send webhook equal and a valid URL. The API will close the connection immediately and will POST all the /task resource information to the URL provided. Optionally this parameter can be equal to empty string. When is equal to empty string, the behaviour will be the same but no callback will be sent, this is useful if you don't want to wait the process to end or receive callbacks giving you the freedom of send periodic GET calls to /task/{task} to know the status of that task and if it has been completed.
For security reasons, you need to register the webhook endpoint in your dashboard.
Resize extra parameters
resize_mode
string

Choose the resize mode. Accepted values:

  • pixels: the resize will be set using pixels.
  • percentage: the resize will be set as a percentage of the original image.
pixels
pixels_width
integer
If resize_mode is pixels
The width in pixels of the resized image.
pixels_height
integer
If resize_mode is pixels
The height in pixels of the resized image.
percentage
integer
If resize_mode is percentage
The percentage value to resize.
maintain_ratio
boolean
If set as true, resize will keep aspect ratio and images will not be distort.
true
no_enlarge_if_smaller
boolean
Controls if the image can be gigger than the original on resize.
true
Crop extra parameters
width
integer
The width in pixels of the area to crop.
height
integer
The height in pixels of the area to crop.
x
integer
The horizontal point where start to crop.
0
y
integer
The vertical point where start to crop.
0
Compress extra parameters
compression_level
string
Compression level. Accepted values: extreme=Extreme compression, recommended=Recommended compression, low=Low compression.
recommended
Convert extra parameters
to
string
The format to convert to. Accepted values are jpg, png, gif, gif_animation (static or animated) and heic. Convert to jpg can be (almost) from any image format. Convert to png and gif can be only from jpg images.
jpg
gif_time
integer
if to is gif_animated
Only for gif_animation, define the seconds per image, in hundredths of a second.
50
gif_loop
integer
if to is gif_animated
Set if animation stops at the end or loops forever.
true
Watermark extra parameters
elements
array
An array of elements to stamp. This means you can set multiple elements to stamp.
type
string
The type for the element. Accepted values: image or text.
text
text
string
if type is text
The text to stamp
image
string
if type is image
The stamp image must be uploaded in the Upload resource. This image parameter must referer to the server_filename (JPG or PNG).
gravity
string
Accepted values: North, NorthEast, NorthWest, Center, CenterEast, CenterWest, East, West, South, SouthEast, SouthWest.
Center
vertical_adjustment_percent
integer
Adjust how much space must modify the position of the position defined in gravity, based on a percent of the base image, it accepts positive and negative values.
0
horizontal_adjustment_percent
integer
Adjust how much space must modify the position of the position defined in gravity, based on a percent of the base image, it accepts positive and negative values.
0
rotation
integer
Angle of rotation. Accepted integer range: 0-360.
0
font_family
string
Accepted values: Arial, Arial Unicode MS, Verdana, Courier, Times New Roman, Comic Sans MS, WenQuanYi Zen Hei, Lohit Marathi.
0
font_style
string
Accepted values: null (Regular/Normal), Bold, Italic.
null
font_size
integer
14
font_color
string
Hexadecimal color.
#000000
transparency
integer
Percentage of opacity for stamping text or image. Accepted integer range 1-100.
100
mosaic
boolean
If true, this value overrides all position parameters and stamps the image or text 9 times per page.
false
Rotate extra parameters

Rotate tool has no options, just set rotation property in file.

Repair extra parameters

Repair tool has no options.

Response
File status types
FileSuccess
This file has been processed successfully.
FileWaiting
This file is waiting to be processed.
WrongPassword
This file has not been processed because needed a password and was not provided or incorrect.
TimeOut
This file has not been processed correctly because it took more than your time limit to process it.
ServerFileNotFound
This file has not been processed because has not been found in the server.
DamagedFile
This file has not been processed because it was damaged or we were unable to read it.
NoImages
This file has not been processed because we couldn't find any images to extract. Maybe there are vectors?
OutOfRange
This file has not been processed because some of the ranges do not match the number of pages.
NonConformant
PDF file validation has not passed against PDF/A conformance provided.
UnknownError
Unknown Error.

Download

Download the output files for the given task. If there is only one output file, it is served directly. If there is more than one file, they are served in a compressed ZIP folder. If there is more than one processed file, there will be multiple output files for every processed file. The ZIP will contain a folder for every processed file.

Download output files
https://{server}/v1/download/{task}
Response

Task

The /task resource gives information about processed tasks and the metadata related of their uploaded and result files.


For security reasons, only can be accessed by server side code providing your secret_key as a parameter.

List and filter all tasks
https://api.ilovepdf.com/v1/task
secret_key
string
Your project secret key.
page
integer
Results are offered paginated in 50 results per page.
1
tool
string
Filter tasks by tool.
status
string
Filter tasks by task status type, for example TaskSuccess.
custom_int
integer
Filter tasks by custom_int.

All tasks and their related files are deleted after two hours of being processed. However, if you need to delete the task and all related files immediately, you can do so by sending a DELETE request to /task.


When deleting a task, you'll get the TaskDeleted status in the response, but if the previous status was TaskWaiting the response will contain a UploadDeleted. If called again, it will throw the error TaskNotFound in the following requests:

Delete task
https://{server}/v1/task/{task}

If you need to apply different tools on the same files, connected task resource will allow you to execute a new task on the files resulting from the previous tool. Using this resource means that you don't need to upload your files again.


The response will contain the new task ID and the files as an array of objects where the key is the server_filename and filename is the value. You will need this information for the process step.


Once the new connected task is created, you can add, remove files, and work just like another tool.

Connect task
https://{server}/v1/task/next
task
string
The parent task id.
tool
string
The tool for the next task.
Task status types
TaskWaiting Files for the task have been uploaded but processing order has not been received yet
TaskProcessing The task is currently processing files.
TaskSuccess The task has already been processed successfully.
TaskSuccessWithWarnings The task has already been processed successfully with warnings.
TaskError The task has been processed unsuccessfully.
TaskDeleted The task has already been deleted.
TaskNotFound Task not found.

Signatures

Create signature request

This endpoint is used to create a signature request

Create signature request
https://{server}/v1/signature
Signature works in a different way than the other tools, it does have an Start and Upload, but not a Process or Download, so, before creating a Signature, the following steps must be done (please consider that all the files must be a PDF*):
  • Call the Start with the tool sign (https://api.ilovepdf.com/v1/start/sign).
  • Upload the needed files for that signature.
* With the exception that you can upload a brand logo file
task
string
Use the same task ID obtained when calling the start API call
files
array

Files to be signed. The order of the array is the same order as the receivers will see it. Maximum number allowed is 5

Each file has the following attributes:

For each element on this files attribute, one e-Signature credit will be consumed, please check the following link to see how credit consumption works.
server_filename
string
Server file name. It must be one previously uploaded using the upload endpoint.
filename
string
Original filename of the file to process.
brand_name
string

Name of your brand.

Displayed in email notifications along with brand_logo

It is an optional parameter that becomes mandatory when its counterpart parameter brand_logo is also present
brand_logo
string

Server filename of the uploaded logo file. See files.

Displayed in email notifications along with brand_name

It is an optional parameter that becomes mandatory when its counterpart parameter brand_name is also present
signers
string
Receivers that participate in the signature process. Each signer has the following attributes:
Maximum allowed signers (regardless of it's role) is 50
name
string
Receiver full name.
email
string
Receiver email.
phone
string
Signer phone. Leave it empty or do not specify this attribute on the request if you don't want to activate the SMS validation feature. It is only valid for type signer
For every signer with phone, SMS credit will be consumed, please check the following link to see how credit consumption works.
files
array
Files that a receiver of type signer needs to sign.
server_filename
string
Server filename of an uploaded PDF file. See files
elements
array
Definition of the elements in a PDF document.
The total amount of elements on the request (total) is 1000
position
string

Element position in a page (X, Y)

Example: 300 -100

Y value is always a negative number or zero.
pages
string

Page or pages where element will be placed

Must have one of the following formats:

  • 1
  • 3-12
  • 3,5,9-12
content
string
This property is required when the element type is either date or text.
  • When the type is text, it specifies the text that will appear on the text box.
  • When the type is date, it specifies the date format.

    Allowed formats:

    d-m-Y, d/m/Y, d.m.Y, Y-m-d, Y/m/d, Y.m.d, m-d-Y, m/d/Y, m.d.Y
size
integer

Element size

It corresponds to the height of the element.

Width will adapt automatically according to its content

info
string

This parameter only applies when the element type is input. It must be a JSON string where you can define the attributes of that element, an example is:

{"label": "my input label text", "description": "input description"}

type
string

initials : Signer initials.

signature : Signer signature.

name : Signer full name.

date : Date when the signature is applied.

text : Text to stamp above the pdf content.

input : The signer must fill the input.

signature
type
string

signer : The signer is a receiver type that can reject or sign a document.

validator : The validator is a receiver type that has ability to validate a document. This receiver type is commonly used to either validate the content of a document or the signing process once it is completed. The validator can validate or reject a document.

viewer : The viewer (also called witness in the rest of the document) is a receiver type that receives a copy of the original document and the completely signed one as well. Use this type if someone must only receive and view the document but they don't need to take any action on it.

signer
access_code
string
If provided, all receivers will have to insert an access code. Otherwise the receiver will not be able to access the document
force_signature_type
string

Use this field if you want to force this a receiver of type signer to use a specific signature format.

all : The signer can choose the preferred signature adoption.

text : The signer must sign with a pre-defined font.

sign : The signer must sign drawing a signature.

image : The signer must sign by uploading a signature.

all
language
string
Receivers will receive emails in the provided language. Accepted values: en-US, es, fr, it, ca, zh-cn, zh-tw, ar, ru, de, ja, pt, bg, ko, nl, el, hi, id, ms, pl, sv, th, tr, uk, vi, en-US, es, fr, it, ca, zh-cn, zh-tw, ar, ru, de, ja, pt, bg, ko, nl, el, hi, id, ms, pl, sv, th, tr, uk, vi, zh-Hans, zh-Hant
en
lock_order
boolean

false = allows receivers of signer type to sign in parallel.

true = receivers of signer type must sign sequentially in order.

false
message_signer
string
Use this if you want to change the body of the initial email sent to the receivers.
subject_signer
string
Use this if you want to change the subject of the initial email sent to the receivers.
uuid_visible
boolean
It is highly recommend to enable this, otherwise it lowers the signatures validity.

false = uuid is not shown at the bottom of each signature.

true = uuid is shown at the bottom of each signature element.

true
expiration_days
integer
Days until the signature request will expire. (Value must be between 1 and 130)
120
signer_reminders
boolean

false = No email reminders will be sent to any receivers.

true = Email reminders are sent periodically to receivers.

See also signer_reminder_days_cycle.

true
signer_reminder_days_cycle
integer

It is the time period that will wait between each reminder.

See also signer_reminders.

1
verify_enabled
boolean

false = No QR code is added on the audit trail.

true = It adds a QR code on the audit trail that leads you to the original documents and signed documents where you are free to download them

true
Response

List Signatures

List all created signature requests

List Signatures
https://api.ilovepdf.com/v1/signature/list?page=0&per-page=100
page
integer

Lookup page

0
per-page
integer
Paginator size

Accepted values are in the range [1, 100]

20
Response

Get Signature status

Get Signature status
https://api.ilovepdf.com/v1/signature/requesterview/<token_requester>

Response attributes

completed_on
The date when this signature request was successfully signed by all of the signers. The format is YYYY-mm-dd MM-HH-SS. By default, it is formatted in the timezone that it is in your user panel
created
The date when this signature request was created. The format is YYYY-mm-dd MM-HH-SS. By default, it is formatted in the timezone that it is in your user panel
email
Email from which the signature request was sent. It should match your user's account.
expires
The date when this signature request is going to expire. The format is YYYY-mm-dd MM-HH-SS. By default, it is formatted in the timezone that it is in your user panel
language
The language from which the request was sent
mode
  • multiple: Default and only available mode in the API. A signature request is created by a requester and sends it to one or more receivers.
    The request creator can be also a receiver
  • single: It is the type of signature where the creator is the only one signing. No other receiver participates in the process.

    It corresponds to the Only me signature mode on the website.

    The create_signature endpoint does not allow you to create this kind of signature process.

name
Signature request creator's name. It should match your user's account.
notes
It contains the reasons why a signature was declined by a receiver
signer_reminder_days_cycle
The number of days between each email remainder.
subject_signer
Custom subject of the initial email sent to each receiver.
message_signer
Custom body message of the initial email sent to each receiver.
token_requester
It is the internal identifier of the signature. You have to use it in subsequent requests to perform actions on an already created signature request.
We encourage not to share this ID outside from your systems of your company
uuid
This is a public identifier of the signature.
expiring
If true, it means that it is going to expire in the next 24 hours.
expired
If true, the request has already expired.
files
An array of the files used on that signature.
signers
An array of the receivers of the signature request.
status

It can be one of the following:

  • draft: Signature request was created and is being built in order to send the emails to the receivers.
  • sent: All emails were sent to all of the receivers of the signature.
  • completed: Every receiver has finished the process and no further actions are needed.
  • declined: Either a signer or a validator rejected the signature request.
  • expired: The signature has expired.
  • void: The requester canceled the signature request process before it was completed.
  • deleted: The signature request is completed but it was deleted afterwards.
certified
It is true if the request is a Digital Signature.
All requests created through the API are Digital Signatures
verify_enabled

false = No QR code is added on the audit trail.

true = It adds a QR code on the audit trail from where you can visualize the documents and dowload them (both the original and signed).

lock_order

false = allows signers to sign in any order at any time.

true = if set to true, for a signer to be able to sign, it is necessary that the one that is before them sign first. Until then, it must wait.

signer_reminders

false = No email reminders will be sent to any receivers.

true = Email reminders are sent periodically to the receivers.

uuid_visible

false = UUID is not shown at the bottom of each signature element.

true = UUID is shown at the bottom of each signature element.

Response

Get Receiver info

Get Receiver info
https://api.ilovepdf.com/v1/signature/receiver/info/<receiver_token_requester>

Response attributes

uuid
This is a public identifier of the signature.
name
Name of the receiver.
email
Email of the receiver.
phone
Phone of the receiver
type
  • signer: The signer is a receiver type that can reject or sign a document.
  • validator: The validator is a receiver type that has ability to validate a document. This receiver type is commonly used to either validate the content of a document or the signing process once it is completed. The validator can validate or reject a document.
  • witness: The witness is a receiver type that receives a copy of the original document and the completely signed one as well. This type is used if someone must only receive and view the document but they don't need to take any action on it.
token_requester

It is the internal identifier of the receiver

We encourage not to share this ID outside from your systems of your company
status
  • waiting: The receiver is waiting to receive the initial email.
  • sent: The initial email has been successfully sent to the receiver's email provider.
  • viewed: The receiver has viewed the documents
  • signed: The signer has signed the documents.
  • declined: The signer declined the request.
  • validated: The validator has successfully validated the request.
  • nonvalidated: The validator has rejected the request.
  • error: There was an error and further investigation on our side.
access_code

true if the receiver must provide an access code in order to view the document(s).

false otherwise.

force_signature_type

all : The signer can choose the preferred signature adoption.

text : The signer must sign with a pre-defined font.

sign : The signer must sign drawning a signature.

image : The signer must sign by uploading a signature.

notes

Reject reason if signer or validator rejected the request.

Response

Download Audit

It downloads the audit PDF file.

The signature request status must be completed.

Download Audit
https://{server}/v1/signature/<token_requester>/download-audit
Call start (https://api.ilovepdf.com/v1/start/sign) and use the {server} parameter to get the server which you are going to do the API call.

Download Original files

It downloads the original files.

It returns a PDF file if a single file was uploaded. Otherwise a zip file with all uploaded files is returned.

Download Original files
https://{server}/v1/signature/<token_requester>/download-original
Call start (https://api.ilovepdf.com/v1/start/sign) and use the {server} parameter to get the server which you are going to do the API call.

Download Signed files

It downloads the signed files.

It returns a PDF file if a single file was uploaded. Otherwise a zip file with all uploaded files is returned.

If the Signature request status is different from completed, the call to this API will not return any files and it will yield an HTTP status code 400
Download Signed files
https://{server}/v1/signature/<token_requester>/download-signed
Call start (https://api.ilovepdf.com/v1/start/sign) and use the {server} parameter to get the server which you are going to do the API call.

Fix Receiver Email

Use this endpoint to correct the receiver's email address in the event that the email was not delivered to a valid email address.

Fix Receiver Email
https://api.ilovepdf.com/v1/signature/receiver/fix-email/<receiver_token_requester>
email
string
New valid email for the receiver
Response

Fix Signer Phone

Use this endpoint to correct the signers's mobile number in the event that the SMS was not delivered to a valid mobile number.

Only applicable to receivers of type signer
Fix Signer Phone
https://api.ilovepdf.com/v1/signature/signer/fix-phone/<signer_token_requester>
phone
string

New valid mobile number for the signer.

It must contain only numbers. Any other characters are not allowed. It is mandatory to specify the international prefix followed by the phone number.

Several examples:

For +34 737 105 892 (Spain), the number sent to the API should be 34737105892

For +64 (026) 2511-398 (New Zealand), the number sent to the API should be 640262511398

For +44 077 8019 6390 (United Kingdom), the number sent to the API should be 4407780196390

For +1 (379) 254-8609 (United States), the number sent to the API should be 13792548609

For +55 955 730 5718 (Brazil), the number sent to the API should be 559557305718

Response

Send Reminder emails

When this endpoint is called, sends an email reminder to the receivers that did not finished its action.

It is only available if the following conditions are met:

  • The signature status is sent
  • Signature mode is multiple. If you created the signature request from the API, then this value is always set to multiple
Send Reminder
https://api.ilovepdf.com/v1/signature/sendReminder/<token_requester>
There is a daily limit of 2 calls
Response

Void Signature

It voids a signature that it is currently in progress. Once voided, it will not be accessible for any receiver of the request.

Void Signature
https://api.ilovepdf.com/v1/signature/void/<token_requester>
Response

Increase Expiration Days

Increase the number of days in order to prevent the request from expiring and give receivers extra time to perform remaining actions.

Increase Expiration Days
https://api.ilovepdf.com/v1/signature/increase-expiration-days/<token_requester>
days
integer

The number of days to increase; a minimum of 1 and a maximum of 130.

The signature cannot have an expiration date bigger than 130 days from now.

Response

Topics

Security

As an API user, you will only have access to your tasks and files. The original and processed files are deleted after an hour (depending on your tier, it can be more). After processing and downloading the output files you can also remove the task and the files involved in the process.

Rate Limiting

All endpoints are subject to API rate limiting, depending on the tier. As part of every response, the HTTP headers will show your current rate limit status.

File Encryption

The files are always transmitted encrypted via SSL, but in addition, the iLovePDF API also offers another layer of security: store your files in our servers always encrypted. The only moment when the file will be unencrypted is while processing it. For this encryption and decryption, you must add to your JWT signature the file_encryption_key claim on the JWT Payload data. The value of file_encryption_key must be a string of 16, 24 or 32 chars. That means that nobody can have access to your files without knowing your File Encryption Key. The File Encryption Key must be the same for same task.

Open task limitation

The number of tasks that can be opened at one time is limited to 10% of your monthly subscription’s file limits. If you reach this limit of opened tasks, an error will be sent warning you to close tasks (by processing or destroying them). Note that a task is opened from the moment an Upload is made until the Process is executed, with the exception of password-protected files; in this case, the task will be closed when the Process can be completed with a correct password.

IP and domain filtering

Depending on the tier you have, you can configure from where your API request must be allowed. All API requests coming from other domains or IP that are not configured will be rejected.

Errors

iLovePDF API uses conventional HTTP response codes to indicate the success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that failed due to the information provided (e.g. a required parameter was omitted, a process failed, etc.), and codes in the 5xx range indicate an error with iLovePDF's servers. All error responses have the same structure, and you’ll find all the arguments and errors specified in the param.

For ProcessingError in the param, you'll expect an Array of failed files and the reason for failure. When the error is a 400 Bad request we can specify which type of error we are giving (see the right table).

HTTP Error codes

type
The type of error returned. Can be: HTTP Error, UploadError, ProcessingError, DownloadError.
message
optional
A human-readable message providing more details about the error.
code
optional
HTTP Error code.
param
optional
The parameter the error relates to if the error is parameter-specific. You can use this to display a message near the correct form field, for example.
HTTP Error Codes
200 - OK
Everything worked as expected.
400 - Bad Request
The request was unacceptable, often due to missing a required parameter.
401 - Unauthorized
No valid API key provided or not correct.
404 - Not found
The requested resource doesn't exist.
429 - Too many requests
Too many requests hit the API too quickly. We recommend an exponential backoff of your requests.
5xx - Server Errors
Something went wrong on our API's end
Error 400 types
UploadError
Some parameter or the file is missed in the request or something went wrong.
ProcessingError
Some parameter is missed in the request or the process was unsuccessful.
DownloadError
The file may have already been removed or has expired.

Testing

Debug parameter

Any resource can be called with an additional parameter debug. When sending the debug parameter equal true the resource won't process the request but it will output the parameters received by the server.

Just make sure to add in the payload of your request the parameter debug equal to true.

Credit consumption

How does credit consumption work?

iLovePDF’s subscriptions and pre-paid packages work using credits. These credits allow you to process files, use Digital Signatures, and add SMS authentication to Signature Requests.

In your monthly subscription, you can use a specific number of credits that are automatically renewed each month.

Alternatively, or in addition to your monthly subscription, you can purchase pre-paid packages. Packages provide you with additional credits to get the job done. Credits in your packages don’t expire, so you can use them at any time from your account.

Credits will always be consumed from your subscription first.

How are the credits consumed?

iLovePDF provides credits for PDF & Image processing, Digital Signatures, and SMS authentication. Depending on the tool, the credits consumed vary based on number of files, number of tasks or number of pages. Please refer to the pricing page for detailed information.

Webhooks

You can configure the specific URLs to which you want to receive webhooks, ensuring that each event type is directed to the appropriate endpoint within your application from your user area. Additionally, you have the flexibility to select which events your webhook should subscribe to, allowing you to tailor the notifications to suit your application’s needs. This configurability ensures precise and relevant data delivery, optimizing your system's interaction with our platform.

All of the webhooks have the same structure, a JSON with two keys: "event" and "data". The event is the event name which is being sent, and "data" is the event related data.

Response example

Task webhooks

The tasks haves two related events, "task.completed" and "task.failed". The "data" field always contains the "task" key, which contains information similar to the following example:

Task response example

Signature event

All signature related events contains one mandatory key: "signature", which contains the same information as if you used the API call of Get signature status

Additionally, if an event is directly related to a signer / validator / witness, it also includes an additional key called "signed", the result of which is the same as the API call Get receiver info

Signature response example

Fonts compatibility

For tools such as Add Page Numbers and Add Watermark, which allow you to set a font family for its content, there is a list of compatible fonts to use with any alphabet. Take into account that if you use a font which isn’t on this list, it could cause spelling issues.

Latin, Cirillic and Greek alphabets

Arial (Regular, Bold, Italic, Bold Italic)

Courier (Regular, Bold, Italic, Bold Italic)

Times New Roman (Regular, Bold, Italic, Bold Italic)

Verdana (Regular, Bold, Italic, Bold Italic)

Comic Sans MS (Regular, Bold)

Arabic alphabet

Arial (Regular)

Courier (Regular)

Times New Roman (Regular)

Chinese, Japanese and Korean alphabets

WenQuanYi Zen Hei (Regular)

Arial Unicode MS (Regular)

Hindi alphabets

Lohit Marathi (Regular)

Lohit Devanagari (Regular)