Introduction

The iLovePDF API is organized around REST. Our API has predictable, resource-oriented URLs, and uses HTTP response codes to indicate API errors. We use built-in HTTP features, like HTTP authentication and HTTP verbs, which are understood by off-the-shelf HTTP clients. We support cross-origin resource sharing, allowing you to interact securely with our API from a client-side web application (though you should never expose your secret API key in any public website's client-side code). JSON is returned by all API responses, including errors, although our API libraries convert responses to appropriate language-specific objects.

To develop what you need we provide a Free Account in order to test it, although this account is limited to a few hundreds of processing files per month, if you need more, you can contact us.

Quick Start

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

  • Register as developer.
  • Get a Project ID and its related Secret Key.
  • Download one of our API Libraries.
  • Try out our demos in the API Library.
  • And, of course, read this documentation!

If you have any kind of suggestion about this documentation or about the API, please we invite you to contact us.

Request workflow

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

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

Authentication

We are using a very simple but effective Authentication method: JWT, JSON Web Tokens. It consist in sending a Bearer Header in every request with 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. All the signed tokens must have no more of 2 hour expiration. 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 you can find the JWT libraries directly on the JWT official website. Remember: the claims 'exp', 'nbf' and 'iat' must be in UTC timezone.

If you are using a client language like JavaScript and our JS API Library, you must sign the token always server side and pass it to JavaScript.

Start

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

Get Server & Task ID

GET https://api.ilovepdf.com/v1/start/{tool}

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 order of process will be 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 upload either from local or web source.

Upload file

POST https://{server}/v1/upload

task
string
REQUIRED
Task ID where the files must be uploaded
SOURCE FILE IS LOCAL
file
file
OPTIONAL
File to be uploaded.
chunk
integer
OPTIONAL
If is a chunk upload this number indicate the number of chunk being uploaded. Always send the chunks in order. First chunk must be 0.
chunks
integer
OPTIONAL
If is a chunk upload this number indicate the total number of chunks for this file.
SOURCE FILE IS FROM CLOUD
Instead of uploading the file from local storage, the iLovePDF API allows you to upload files from an URL.
cloud_file
string
OPTIONAL
The public URL of the file to be uploaded (will be downloaded directly by the server API).

Remove an already uploaded file from server

POST https://{server}/v1/upload/delete

task
string
REQUIRED
Task ID
server_filename
string
REQUIRED
The file to be removed on the server.

Process

Once uploaded the files for the Task this resource initiate the processing of all files. In the request you must specify which files to process of the uploaded ones in the Step 2 (Upload). That means that you can send the order to process less files than the uploaded ones. If some file has an error while processing check the table of File Status Types to know all statuses. If the error is WrongPassword the response will throw a 400 error but the task status would be kept as TaskWaiting so you can try to re-send the request to process with the required passwords.

When sending the request is not needed to maintain the connection open although is recommended. If you close the connection before receiving the response you can make calls to /task/{task} to know the status of that task and if it has been completed.

Process files

POST https://{server}/v1/process

task
string
REQUIRED
Task ID to be processed
tool
string
REQUIRED
Accepted values: merge, split, compress, pdfjpg, imagepdf, unlock, pagenumber, watermark, officepdf, repair, rotate, protect, pdfa, validatepdfa, extract
files
array
REQUIRED
Files to process. The order of the array will be the order that files will be processed. Files has the following attributes:

[server_filename]
string
REQUIRED
Server file name
[filename]
string
REQUIRED
Original filename of the file to process.
[rotate]
integer
OPTIONAL
Accepted values: 0,90,180,270
Default: 0
[password]
string
OPTIONAL
Password protected or no.
Default: null
metas
array
OPTIONAL
The optional Info entry in the trailer of a PDF file can hold a document information dictionary containing metadata for the document. See the following

[Title]
string
OPTIONAL
The document's title.
[Author]
string
OPTIONAL
The name of the person who created the document.
[Subject]
string
OPTIONAL
The subject of the document.
[Keywords]
string
OPTIONAL
Keywords associated with the document.
[Creator]
string
OPTIONAL
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
OPTIONAL
If the document was converted to PDF from another format, the name of the application that converted it to PDF.
[CreationDate]
string
OPTIONAL
The date and time the document was created, in human-readable form.
[ModDate]
string
OPTIONAL
The date and time the document was most recently modified, in human-readable form
[Trapped]
string
OPTIONAL
A name object indicating whether the document has been modified to include trapping information. Values true, false or unknown

Default: unknown
ignore_errors
boolean
OPTIONAL
Force process although some of the files to process 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 reponse all error files will be listed as warnings. Values: true, false
Default: true
ignore_password
boolean
OPTIONAL
Force process although some of the files to process need a password. If files that need password are equal to total files to process this value does not take effect. . Values: true, false
Default: false
output_filename
string
OPTIONAL
{date}=current date, {n}=file number, {filename}=original filename, {tool}=the current processing action. Example: file_{n}_{date}
packaged_filename
string
OPTIONAL
If output files are more than one will be served compressed. Specify the filename of the compressed file. {date}=current date, {n}=file number,{filename}=original filename, {app}=the current processing action. Example: zipped_{n}_{date}
Default:output
file_encryption_key
string
OPTIONAL
If specified it is assumed all previously uploaded files for the task has been uploaded encrypted. The key will be used to decrypt the files before processing and re-encrypt them after processing. Only keys of sizes 16, 24 or 32 are supported.
Default: null
try_pdf_repair
boolean
OPTIONAL
When a PDF to process fails we try to repair it automatically.
Default: true
custom_int
integer
OPTIONAL
Use this parameter to store integers as you wish. You can use it to filter your tasks in the GET /task resource.
Default: null
custom_string
string
OPTIONAL
Use this parameter to store the strings as you wish. It can't be used to filter tasks in GET /task resource.
Default: null
SPECIFIC TOOL PARAMETERS
List of parameters for every tool that supports custom configurations. If a tool isn't listed below, means that tool has no custom parameters (but still exists!).
SPLIT
split_mode
string
OPTIONAL
Choose split mode.
  • ranges: define different ranges of pages {ranges} param is required.
  • fixed_range: define a fixed range of pages to split the PDF. {fixed_range} is required.
  • remove_pages: remove pages from a PDF, {remove_pages} is required.
Default: ranges
ranges
string
OPTIONAL
Page ranges to split the files. Every range will be saved as different PDF file.
Example format: 1,5,10-14
Default: null
fixed_range
integer
OPTIONAL
Split the PDF file in chunks by every defined number.
Default: 1
remove_pages
string
OPTIONAL
Pages to remove from a PDF. Accepted format: 1,4,8-12,16.
Default: null
merge_after
boolean
OPTIONAL
Merge all ranges after being split. This param takes offect only when {mode} is range.
Default: false
COMPRESS
compression_level
string
OPTIONAL
Compression level. Accepted values: extreme=Extreme compression, recommended=Recommended compression, low=Low compression
Default: recommended
PDF to JPG
pdfjpg_mode
string
OPTIONAL
Accepted values: pages=Convert every PDF page to a JPG image, extract=extract all PDF's embed images to separate JPG images
Default: pages.
IMAGE to PDF
orientation
string
OPTIONAL
Accepted values: portrait, landscape
Default: portrait.
*To rotate the image use files[]['rotate'].
margin
integer
OPTIONAL
Define a margin in pixels for the image in the output PDF.
Default: 0.
pagesize
string
OPTIONAL
Page size of the output PDF.
  • fit: PDF page is the same size of image
  • A4
  • letter
Default: fit.
merge_after
boolean
OPTIONAL
Serve all converted images in an unique PDF if true. If false, serve every image into a separate PDF.
Default: true.
PAGE NUMBERS
facing_pages
boolean
OPTIONAL
Define it to true if the PDF is in facing page mode.
Default: false.
first_cover
boolean
OPTIONAL
If first page is cover will not be numbered.
Default: false.
pages
string
OPTIONAL
Pages to be numbered. Accepted formats:
  • all
  • 3-end
  • 1,3,4-9
  • -2-end
  • 3-234

Default: all.
starting_number
integer
OPTIONAL
Start page numbering with this number.
Default: 1.
vertical_position
string
OPTIONAL
Define if page number will be on top or bottom. Accepted values: bottom, top.
Default: bottom.
horizontal_position
string
OPTIONAL
Define where the numbers will be placed horizontally. If are facing places and horizontal position is left or right the numbers will be placed as mirror. Accepted values: left, center, right.
Default: center.
vertical_position_adjustment
integer
OPTIONAL
Adjust how much pixels must modify the position of the position defined in vertical_position, it accepts positive and negative values.
horizontal_position_adjustment
integer
OPTIONAL
Adjust how much pixels must modify the position of the position defined in horizontal_position, it accepts positive and negative values.
font_family
string
OPTIONAL
Accepted values: Arial, Arial Unicode MS, Verdana, Courier, Times New Roman, Comic Sans MS, WenQuanYi Zen Hei, Lohit Marathi.
Check our guide for Fonts
Default: Arial Unicode MS.
font_style
string
OPTIONAL
Accepted values: null (Regular/Normal), Bold, Italic.
Check our guide for Fonts
Default: null.
font_size
integer
OPTIONAL
Default: 14.
font_color
string
OPTIONAL
Hexadecimal color.
Default: #000000.
text
string
OPTIONAL
To define text in addition of a number use {n} for current page number and {p} for total pages number for the file. Example Page {n} of {p}. If null only page number will be placed.
Default: {n}.
WATERMARK
mode
string
OPTIONAL
Accepted values: text, image.
Default: text.
text
string
OPTIONAL
Text to be stamped. If mode is image this value does not take effect. If mode is text this value is required.
Default: null.
image
string
OPTIONAL
The image to stamp if mode is image. The stamp image must be uploaded in the /upload resource. This image parameter must referer to the server_filename (JPG or PNG) to stamp in the PDF.
pages
string
OPTIONAL
Pages to be stamped. Accepted formats:
  • all
  • 3-end
  • 1,3,4-9
  • -2-end
  • 3-234

Default: all.
vertical_position
string
OPTIONAL
Accepted values: bottom, top, middle.
Default: middle.
horizontal_position
string
OPTIONAL
Accepted values: left, center, right.
Default: center.
vertical_position_adjustment
integer
OPTIONAL
Adjust how much pixels must modify the position of the position defined in vertical_position, it accepts positive and negative values.
horizontal_position_adjustment
integer
OPTIONAL
Adjust how much pixels must modify the position of the position defined in horizontal_position, it accepts positive and negative values.
mosaic
boolean
OPTIONAL
If true, this value overrides all position parameters and stamps the image or text 9 times per page.
Default: false.
rotation
integer
OPTIONAL
Angle of rotation. Accepted integer range: 0-360.
Default: 0.
font_family
string
OPTIONAL
Accepted values: Arial, Arial Unicode MS, Verdana, Courier, Times New Roman, Comic Sans MS, WenQuanYi Zen Hei, Lohit Marathi.
Check our guide for Fonts
Default: Arial Unicode MS.
font_style
string
OPTIONAL
Accepted values: null (Regular/Normal), Bold, Italic.
Check our guide for Fonts
Default: null.
font_size
integer
OPTIONAL
Default: 14.
font_color
string
OPTIONAL
Hexadecimal color.
Default: #000000.
transparency
integer
OPTIONAL
Percentage of opacity for stamping text or image. Accepted integer range 1-100.
Default: 100.
layer
string
OPTIONAL
above=Place stamp over content, below=Place stamp below content.
Default: above.
PROTECT
password
string
REQUIRED
Password which the PDF file will be encrypted with
PDF to PDF/A
conformance
string
OPTIONAL
Set the PDF/A conformance level. Accepted values: pdfa-1b, pdfa-1a, pdfa-2b, pdfa-2u, pdfa-2a, pdfa-3b, pdfa-3u, pdfa-3a
Default: pdfa-2b.
Validate PDF/A
conformance
string
OPTIONAL
Set the PDF/A conformance level to validate against. Accepted values: pdfa-1b, pdfa-1a, pdfa-2b, pdfa-2u, pdfa-2a, pdfa-3b, pdfa-3u, pdfa-3a
Default: pdfa-2b.
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.
UnknowError
Unknow Error.


Download

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

Download output files

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

Task

The /task/{task} resource give information about a task status. If the task is TaskSuccess, TaskSuccessWithWarnings or TaskError it will also specify all files of the Task and their status one by one.

Get a Task details

GET https://api.ilovepdf.com/v1/task/{task}


List and filter all Tasks

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

Append parameters GET to the URL like https://{server}/v1/task?page=1&tool=compress&status=TaskSuccess to filter results. The available filters are:

page
integer
OPTIONAL
Results are offered paginated in 50 results per page.
Default: 1
tool
string
OPTIONAL
Filter tasks by tool.
Default: null
status
string
OPTIONAL
Filter tasks by task status type, for instance TaskSuccess.
Default: null
custom_int
integer
OPTIONAL
Filter tasks by custom_int.
Default: null

All Tasks and their related files are deleted after one hour of being processed. But if is needed to delete the task and all related files immediately you can by sending a DELETE request to /task.

When deleting a Task you'll get the TaskDeleted status in the response but if the its previous status was TaskWaiting the response will contain a UploadDeleted and if called again it will throw an error TaskNotFound in the following requests.

Delete a Task

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

TASK STATUS TYPES
TaskWaiting
Files for the task have been uploaded but processing order has not been received yet.
TaskProcessing
This task is currently processing files.
TaskSuccess
This task has already been processed successfully.
TaskSuccessWithWarnings
This task has already been processed successfully with warnings.
TaskError
This task has already been processed unsuccessfully.
TaskDeleted
This task has already been deleted.
TaskNotFound
Task not found.

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 can be more). After processing and downloading the output files you can also remove the task and the files inherit.

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 offer also another layer of security: store in our servers your files 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

There is a limitation to tasks that can be opened about 10% of your monthly file limits subscription. If you reach this limit of opened tasks an error will be sent warning you to close tasks (by process or destroy them). Note that a task is opened since an Upload is made until Process is executed with the exception of password protected files; in this case task will be closed when Process can be done with a right 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 given the information provided (e.g., a required parameter was omitted, a processing failed, etc.), and codes in the 5xx range indicate an error with iLovePDF's servers. All error responses have the same structure, and in the param you'll find specified the arguments and errors.

For ProcessingError in the param you'll expect an Array of failed files and the reason of failure. When 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 Response 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 been already removed or 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.

Fonts compatibility

For tools like Add Page Numbers and Add Watermark which allows to set a font family for its content, there are a list of compatible fonts to use with any alphabet. Take into account that any use of a font no set on this list 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)