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
PHP	See on GitHub
.Net	See on GitHub
Ruby	See on GitHub
Node.js	See on GitHub
Postman

Image Libraries
PHP	See on GitHub
Postman

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.

https://api.ilovepdf.com/v1/auth

public_key

string

Project public key that you can find in admin panel.

Response

{
    "token": "eyJ0eXAiOiJKV1Q..."
}

 
{    "token": "eyJ0eXAiOiJKV1Q..."}        

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.

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.

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

{
    "server": "api11.ilovepdf.com",
    "task": "g27d4mrsg3ztmnzAgm5d..."
    "remaining_credits": 1234
}

xxxxxxxxxx
 
{    "server": "api11.ilovepdf.com",    "task": "g27d4mrsg3ztmnzAgm5d..."    "remaining_credits": 1234}

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.

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.

https://{server}/v1/upload/{task}/{server_filename}

Response

{
    "server_filename": "cd29201ebe...5257c95d9843.pdf"
}

xxxxxxxxxx
 
{    "server_filename": "cd29201ebe...5257c95d9843.pdf"}

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.

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.

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.

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.

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.

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

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.

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

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.

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.

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.

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.

integer

The horizontal point where start to crop.

integer

The vertical point where start to crop.

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

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.

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.

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.

rotation

integer

Angle of rotation. Accepted integer range: 0-360.

font_family

string

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

font_style

string

Accepted values: null (Regular/Normal), Bold, Italic.

null

font_size

integer

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

{
    "download_filename": "output.zip",
    "filesize": 0,
    "output_filesize": 0,
    "output_filenumber": 2,
    "output_extensions": "[\"pdf\"]",
    "timer": "0.028",
    "status": "TaskSuccess"
}

xxxxxxxxxx
 
{    "download_filename": "output.zip",    "filesize": 0,    "output_filesize": 0,    "output_filenumber": 2,    "output_extensions": "[\"pdf\"]",    "timer": "0.028",    "status": "TaskSuccess"}

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

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.

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.

password

string

Password to open the file in case of having one.

ignore_errors

boolean

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

output

file_encryption_key

string

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

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.

integer

The horizontal point where start to crop.

integer

The vertical point where start to crop.

Compress extra parameters

compression_level

string

Compression level. Accepted values: extreme=Extreme compression, recommended=Recommended compression, low=Low compression.

recommended

Convert extra parameters

string

jpg

gif_time

integer

if to is gif_animated

Only for gif_animation, define the seconds per image, in hundredths of a second.

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.

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.

rotation

integer

Angle of rotation. Accepted integer range: 0-360.

font_family

string

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

font_style

string

Accepted values: null (Regular/Normal), Bold, Italic.

null

font_size

integer

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

{
    "download_filename": "output.zip",
    "filesize": 0,
    "output_filesize": 0,
    "output_filenumber": 2,
    "output_extensions": "[\"pdf\"]",
    "timer": "0.028",
    "status": "TaskSuccess"
}

xxxxxxxxxx
 
{    "download_filename": "output.zip",    "filesize": 0,    "output_filesize": 0,    "output_filenumber": 2,    "output_extensions": "[\"pdf\"]",    "timer": "0.028",    "status": "TaskSuccess"}

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.

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

Response

// ArrayBuffer

xxxxxxxxxx
 
// ArrayBuffer        

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.

https://api.ilovepdf.com/v1/task

secret_key

string

Your project secret key.

page

integer

Results are offered paginated in 50 results per page.

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:

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.

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

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.

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

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.

List Signatures

List all created signature requests

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

page

integer

Lookup page

per-page

integer

Paginator size

Accepted values are in the range [1, 100]

Response

[
    {
        "completed_on": null,
        "created": "2021-10-18 14:03:43",
        "email": "email@email.com",
        "expires": "2022-02-15 15:00:00",
        "language": "en",
        "mode": "multiple",
        "name": "name",
        "notes": null,
        "signer_reminder_days_cycle": 2,
        "subject_cc": null,
        "subject_signer": null,
        "token_requester": "token-requester",
        "uuid": "18B06FDC-8643-447C-BAFB-9D3F8CA421B6",
        "expiring": false,
        "expired": false,
        "files": [
            {
                "filename": "sample.pdf",
                "pages": 2,
                "filesize": 22698
            }
        ],
        "signers": [
            {
                "uuid": "FCE3CAB9-2320-44C1-B18B-0F23BE2CF2FD",
                "name": "name",
                "email": "email@email.com",
                "phone": null,
                "type": "signer",
                "token_requester": "token-signer-requester",
                "status": "waiting",
                "access_code": false,
                "phone_access_code": false,
                "force_signature_type": "all",
                "notes": null
            }
        ],
        "status": "draft",
        "certified": true,
        "verify_enabled": true,
        "lock_order": false,
        "signer_reminders": true,
        "about_to_expire_reminder": true,
        "uuid_visible": true
    }
]

xxxxxxxxxx
 
[    {        "completed_on": null,        "created": "2021-10-18 14:03:43",        "email": "email@email.com",        "expires": "2022-02-15 15:00:00",        "language": "en",        "mode": "multiple",        "name": "name",        "notes": null,        "signer_reminder_days_cycle": 2,        "subject_cc": null,        "subject_signer": null,        "token_requester": "token-requester",        "uuid": "18B06FDC-8643-447C-BAFB-9D3F8CA421B6",        "expiring": false,        "expired": false,        "files": [            {                "filename": "sample.pdf",                "pages": 2,                "filesize": 22698            }        ],        "signers": [            {                "uuid": "FCE3CAB9-2320-44C1-B18B-0F23BE2CF2FD",                "name": "name",                "email": "email@email.com",                "phone": null,                "type": "signer",                "token_requester": "token-signer-requester",                "status": "waiting",                "access_code": false,                "phone_access_code": false,                "force_signature_type": "all",                "notes": null            }        ],        "status": "draft",        "certified": true,        "verify_enabled": true,        "lock_order": false,        "signer_reminders": true,        "about_to_expire_reminder": true,        "uuid_visible": true    }]

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

{
    "completed_on": null,
    "created": "2021-10-18 14:03:43",
    "email": "email@email.com",
    "expires": "2022-02-15 15:00:00",
    "language": "en",
    "mode": "multiple",
    "name": "name",
    "notes": null,
    "signer_reminder_days_cycle": 2,
    "subject_signer": null,
    "message_signer": null,
    "token_requester": "token-requester",
    "uuid": "18B06FDC-8643-447C-BAFB-9D3F8CA421B6",
    "expiring": false,
    "expired": false,
    "files": [
        {
            "filename": "sample.pdf",
            "pages": 2,
            "filesize": 22698
        }
    ],
    "signers": [
        {
            "uuid": "FCE3CAB9-2320-44C1-B18B-0F23BE2CF2FD",
            "name": "name",
            "email": "email@email.com",
            "phone": null,
            "type": "signer",
            "token_requester": "token-signer-requester",
            "status": "waiting",
            "access_code": false,
            "phone_access_code": false,
            "force_signature_type": "all",
            "notes": null
        }
    ],
    "status": "draft",
    "certified": true,
    "verify_enabled": true,
    "lock_order": false,
    "signer_reminders": true,
    "about_to_expire_reminder": true,
    "uuid_visible": true
}

xxxxxxxxxx
 
{    "completed_on": null,    "created": "2021-10-18 14:03:43",    "email": "email@email.com",    "expires": "2022-02-15 15:00:00",    "language": "en",    "mode": "multiple",    "name": "name",    "notes": null,    "signer_reminder_days_cycle": 2,    "subject_signer": null,    "message_signer": null,    "token_requester": "token-requester",    "uuid": "18B06FDC-8643-447C-BAFB-9D3F8CA421B6",    "expiring": false,    "expired": false,    "files": [        {            "filename": "sample.pdf",            "pages": 2,            "filesize": 22698        }    ],    "signers": [        {            "uuid": "FCE3CAB9-2320-44C1-B18B-0F23BE2CF2FD",            "name": "name",            "email": "email@email.com",            "phone": null,            "type": "signer",            "token_requester": "token-signer-requester",            "status": "waiting",            "access_code": false,            "phone_access_code": false,            "force_signature_type": "all",            "notes": null        }    ],    "status": "draft",    "certified": true,    "verify_enabled": true,    "lock_order": false,    "signer_reminders": true,    "about_to_expire_reminder": true,    "uuid_visible": true}

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

{
    "uuid": "FCE3CAB9-2320-44C1-B18B-0F23BE2CF2FD",
    "name": "name",
    "email": "email@email.com",
    "phone": null,
    "type": "signer",
    "token_requester": "tokenrequester",
    "status": "waiting",
    "access_code": false,
    "force_signature_type": "all",
    "notes": null
}

xxxxxxxxxx
 
{    "uuid": "FCE3CAB9-2320-44C1-B18B-0F23BE2CF2FD",    "name": "name",    "email": "email@email.com",    "phone": null,    "type": "signer",    "token_requester": "tokenrequester",    "status": "waiting",    "access_code": false,    "force_signature_type": "all",    "notes": null}

Download Audit

It downloads the audit PDF file.

The signature request status must be completed.

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.

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

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.

https://api.ilovepdf.com/v1/signature/receiver/fix-email/<receiver_token_requester>

string

New valid email for the receiver

Response

{
    "uuid": "FCE3CAB9-2320-44C1-B18B-0F23BE2CF2FD",
    "name": "name",
    "email": "email@email.com",
    "phone": null,
    "type": "signer",
    "token_requester": "tokenrequester",
    "status": "waiting",
    "access_code": false,
    "force_signature_type": "all",
    "notes": null
}

xxxxxxxxxx
 
{    "uuid": "FCE3CAB9-2320-44C1-B18B-0F23BE2CF2FD",    "name": "name",    "email": "email@email.com",    "phone": null,    "type": "signer",    "token_requester": "tokenrequester",    "status": "waiting",    "access_code": false,    "force_signature_type": "all",    "notes": null}

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

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

{
    "uuid": "FCE3CAB9-2320-44C1-B18B-0F23BE2CF2FD",
    "name": "name",
    "email": "email@email.com",
    "phone": null,
    "type": "signer",
    "token_requester": "tokenrequester",
    "status": "waiting",
    "access_code": false,
    "force_signature_type": "all",
    "notes": null
}

xxxxxxxxxx
 
{    "uuid": "FCE3CAB9-2320-44C1-B18B-0F23BE2CF2FD",    "name": "name",    "email": "email@email.com",    "phone": null,    "type": "signer",    "token_requester": "tokenrequester",    "status": "waiting",    "access_code": false,    "force_signature_type": "all",    "notes": null}

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

https://api.ilovepdf.com/v1/signature/sendReminder/<token_requester>

There is a daily limit of 2 calls

Response

{
    "uuid": "FCE3CAB9-2320-44C1-B18B-0F23BE2CF2FD",
    "name": "name",
    "email": "email@email.com",
    "phone": null,
    "type": "signer",
    "token_requester": "tokenrequester",
    "status": "waiting",
    "access_code": false,
    "force_signature_type": "all",
    "notes": null
}

xxxxxxxxxx
 
{    "uuid": "FCE3CAB9-2320-44C1-B18B-0F23BE2CF2FD",    "name": "name",    "email": "email@email.com",    "phone": null,    "type": "signer",    "token_requester": "tokenrequester",    "status": "waiting",    "access_code": false,    "force_signature_type": "all",    "notes": null}

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.

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

Response

{
    "completed_on": null,
    "created": "2021-10-18 14:03:43",
    "email": "email@email.com",
    "expires": "2022-02-15 15:00:00",
    "language": "en",
    "mode": "multiple",
    "name": "name",
    "notes": null,
    "signer_reminder_days_cycle": 2,
    "subject_signer": null,
    "message_signer": null,
    "token_requester": "token-requester",
    "uuid": "18B06FDC-8643-447C-BAFB-9D3F8CA421B6",
    "expiring": false,
    "expired": false,
    "files": [
        {
            "filename": "sample.pdf",
            "pages": 2,
            "filesize": 22698
        }
    ],
    "signers": [
        {
            "uuid": "FCE3CAB9-2320-44C1-B18B-0F23BE2CF2FD",
            "name": "name",
            "email": "email@email.com",
            "phone": null,
            "type": "signer",
            "token_requester": "token-signer-requester",
            "status": "waiting",
            "access_code": false,
            "phone_access_code": false,
            "force_signature_type": "all",
            "notes": null
        }
    ],
    "status": "draft",
    "certified": true,
    "verify_enabled": true,
    "lock_order": false,
    "signer_reminders": true,
    "about_to_expire_reminder": true,
    "uuid_visible": true
}

xxxxxxxxxx
 
{    "completed_on": null,    "created": "2021-10-18 14:03:43",    "email": "email@email.com",    "expires": "2022-02-15 15:00:00",    "language": "en",    "mode": "multiple",    "name": "name",    "notes": null,    "signer_reminder_days_cycle": 2,    "subject_signer": null,    "message_signer": null,    "token_requester": "token-requester",    "uuid": "18B06FDC-8643-447C-BAFB-9D3F8CA421B6",    "expiring": false,    "expired": false,    "files": [        {            "filename": "sample.pdf",            "pages": 2,            "filesize": 22698        }    ],    "signers": [        {            "uuid": "FCE3CAB9-2320-44C1-B18B-0F23BE2CF2FD",            "name": "name",            "email": "email@email.com",            "phone": null,            "type": "signer",            "token_requester": "token-signer-requester",            "status": "waiting",            "access_code": false,            "phone_access_code": false,            "force_signature_type": "all",            "notes": null        }    ],    "status": "draft",    "certified": true,    "verify_enabled": true,    "lock_order": false,    "signer_reminders": true,    "about_to_expire_reminder": true,    "uuid_visible": true}

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.

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

{
    "completed_on": null,
    "created": "2021-10-18 14:03:43",
    "email": "email@email.com",
    "expires": "2022-02-15 15:00:00",
    "language": "en",
    "mode": "multiple",
    "name": "name",
    "notes": null,
    "signer_reminder_days_cycle": 2,
    "subject_signer": null,
    "message_signer": null,
    "token_requester": "token-requester",
    "uuid": "18B06FDC-8643-447C-BAFB-9D3F8CA421B6",
    "expiring": false,
    "expired": false,
    "files": [
        {
            "filename": "sample.pdf",
            "pages": 2,
            "filesize": 22698
        }
    ],
    "signers": [
        {
            "uuid": "FCE3CAB9-2320-44C1-B18B-0F23BE2CF2FD",
            "name": "name",
            "email": "email@email.com",
            "phone": null,
            "type": "signer",
            "token_requester": "token-signer-requester",
            "status": "waiting",
            "access_code": false,
            "phone_access_code": false,
            "force_signature_type": "all",
            "notes": null
        }
    ],
    "status": "draft",
    "certified": true,
    "verify_enabled": true,
    "lock_order": false,
    "signer_reminders": true,
    "about_to_expire_reminder": true,
    "uuid_visible": true
}

xxxxxxxxxx
 
{    "completed_on": null,    "created": "2021-10-18 14:03:43",    "email": "email@email.com",    "expires": "2022-02-15 15:00:00",    "language": "en",    "mode": "multiple",    "name": "name",    "notes": null,    "signer_reminder_days_cycle": 2,    "subject_signer": null,    "message_signer": null,    "token_requester": "token-requester",    "uuid": "18B06FDC-8643-447C-BAFB-9D3F8CA421B6",    "expiring": false,    "expired": false,    "files": [        {            "filename": "sample.pdf",            "pages": 2,            "filesize": 22698        }    ],    "signers": [        {            "uuid": "FCE3CAB9-2320-44C1-B18B-0F23BE2CF2FD",            "name": "name",            "email": "email@email.com",            "phone": null,            "type": "signer",            "token_requester": "token-signer-requester",            "status": "waiting",            "access_code": false,            "phone_access_code": false,            "force_signature_type": "all",            "notes": null        }    ],    "status": "draft",    "certified": true,    "verify_enabled": true,    "lock_order": false,    "signer_reminders": true,    "about_to_expire_reminder": true,    "uuid_visible": true}

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

    {
        "event": "signature.created",
        "data": {
            "signature": {
                .....
            }
        }
    }

xxxxxxxxxx
 
    {        "event": "signature.created",        "data": {            "signature": {                .....            }        }    }                    

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

{
  "event": "task.completed",
  "data": {
    "task": {
      "tool": "compress",
      "process_start": "2024-06-17 10:18:17",
      "custom_int": null,
      "custom_string": null,
      "status": "TaskSuccess",
      "status_message": "This task has been processed successfully.",
      "timer": "0.206",
      "filesize": 13264,
      "output_filesize": 9792,
      "output_filenumber": 1,
      "output_extensions": [
        "pdf"
      ],
      "server": "api70.ilovepdf.com",
      "task": "xxxxxxxxxxxxxxxxxxxxxxxxx",
      "file_number": "1",
      "download_filename": "server.pdf"
    }
  }
}

xxxxxxxxxx
 
{  "event": "task.completed",  "data": {    "task": {      "tool": "compress",      "process_start": "2024-06-17 10:18:17",      "custom_int": null,      "custom_string": null,      "status": "TaskSuccess",      "status_message": "This task has been processed successfully.",      "timer": "0.206",      "filesize": 13264,      "output_filesize": 9792,      "output_filenumber": 1,      "output_extensions": [        "pdf"      ],      "server": "api70.ilovepdf.com",      "task": "xxxxxxxxxxxxxxxxxxxxxxxxx",      "file_number": "1",      "download_filename": "server.pdf"    }  }}                

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

                {
  "event": "signature.signer.completed",
  "data": {
    "signature": {
      "expired": false,
      "lock_order": false,
      "expiring": false,
      "notes": null,
      "brand_name": null,
      "language": null,
      "subject_cc": null,
      "message_signer": null,
      "subject_signer": null,
      "token_requester": "xxxxxxxxxxxxx",
      "created": "2024-06-17 12:02:59",
      "completed_on": "2024-06-17 12:39:34",
      "expires": "2024-10-25 13:00:00",
      "status": "completed",
      "name": "test",
      "email": "test@isfjdijasdifjdasfadsf.com",
      "uuid_visible": true,
      "certified": true,
      "signer_reminders": true,
      "signer_reminder_days_cycle": 2,
      "verify_enabled": true,
      "uuid": "9B41A389-6645-45FB-A72D-3A19CC3EF9F9",
      "mode": "multiple",
      "files": [
        {
          "filename": "a.pdf",
          "pages": 62,
          "filesize": 2617649
        }
      ]
    },
    "signer": {
      "uuid": "5E4E6228-CF1E-4533-BC85-4FA660117EF5",
      "name": "asdfadsfafas",
      "email": "test2@8usijfas9yudsfsdf.com",
      "phone": null,
      "phone_retries_left": 1,
      "type": "signer",
      "token_requester": "xxxxxxxxxxxxxxxxxxx",
      "status": "signed",
      "access_code": false,
      "force_signature_type": "all",
      "notes": null,
      "fix_email_needed": false,
      "fix_phone_needed": false
    }
  }
}

xxxxxxxxxx
 
                {  "event": "signature.signer.completed",  "data": {    "signature": {      "expired": false,      "lock_order": false,      "expiring": false,      "notes": null,      "brand_name": null,      "language": null,      "subject_cc": null,      "message_signer": null,      "subject_signer": null,      "token_requester": "xxxxxxxxxxxxx",      "created": "2024-06-17 12:02:59",      "completed_on": "2024-06-17 12:39:34",      "expires": "2024-10-25 13:00:00",      "status": "completed",      "name": "test",      "email": "test@isfjdijasdifjdasfadsf.com",      "uuid_visible": true,      "certified": true,      "signer_reminders": true,      "signer_reminder_days_cycle": 2,      "verify_enabled": true,      "uuid": "9B41A389-6645-45FB-A72D-3A19CC3EF9F9",      "mode": "multiple",      "files": [        {          "filename": "a.pdf",          "pages": 62,          "filesize": 2617649        }      ]    },    "signer": {      "uuid": "5E4E6228-CF1E-4533-BC85-4FA660117EF5",      "name": "asdfadsfafas",      "email": "test2@8usijfas9yudsfsdf.com",      "phone": null,      "phone_retries_left": 1,      "type": "signer",      "token_requester": "xxxxxxxxxxxxxxxxxxx",      "status": "signed",      "access_code": false,      "force_signature_type": "all",      "notes": null,      "fix_email_needed": false,      "fix_phone_needed": false    }  }}                

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)