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.
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:
If you have any comments or suggestions for this documentation or the API, please don’t hesitate to contact us.
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.
Authorization: Bearer {signed_token}
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).
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.
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.
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.
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.
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.
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.
file_{n}_{date}
Page ranges to split the files. Every range will be saved as a different PDF file.
Example format: 1,5,10-14
Pages to remove from a PDF. Accepted format: 1,4,8-12,16.
Accepted values: Arial, Arial Unicode MS, Verdana, Courier, Times New Roman, Comic Sans MS, WenQuanYi Zen Hei, Lohit Marathi.
Choose the resize mode. Accepted values:
Rotate tool has no options, just set rotation property in file.
Repair tool has no options.
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.
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.
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:
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.
This endpoint is used to create a signature request
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:
Name of your brand.
Displayed in email notifications along with brand_logo
Server filename of the uploaded logo file. See files.
Displayed in email notifications along with brand_name
Element position in a page (X, Y)
Example: 300 -100
Page or pages where element will be placed
Allowed formats:
Element size
It corresponds to the height of the element.
Width will adapt automatically according to its content
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"}
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.
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.
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.
false = allows receivers of signer type to sign in parallel.
true = receivers of signer type must sign sequentially in order.
false = uuid is not shown at the bottom of each signature.
true = uuid is shown at the bottom of each signature element.
false = No email reminders will be sent to any receivers.
true = Email reminders are sent periodically to receivers.
See also signer_reminder_days_cycle.
It is the time period that will wait between each reminder.
See also signer_reminders.
false = No QR code is added on the audit trail.
true = It adds a QR code on the audit trail that leads you to the original documents and signed documents where you are free to download them
List all created signature requests
Lookup page
Accepted values are in the range [1, 100]
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.
It can be one of the following:
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).
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.
true = Email reminders are sent periodically to the receivers.
false = UUID is not shown at the bottom of each signature element.
true = UUID is shown at the bottom of each signature element.
It is the internal identifier of the receiver
true if the receiver must provide an access code in order to view the document(s).
false otherwise.
sign : The signer must sign drawning a signature.
Reject reason if signer or validator rejected the request.
It downloads the audit PDF file.
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.
It downloads the signed files.
Use this endpoint to correct the receiver's email address in the event that the email was not delivered to a valid email address.
Use this endpoint to correct the signers's mobile number in the event that the SMS was not delivered to a valid mobile number.
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
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:
It voids a signature that it is currently in progress. Once voided, it will not be accessible for any receiver of the request.
Increase the number of days in order to prevent the request from expiring and give receivers extra time to perform remaining actions.
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.
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.
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.
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.
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.
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.
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).
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.
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.
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.
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.
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:
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
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.
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)
Arial (Regular)
Courier (Regular)
Times New Roman (Regular)
WenQuanYi Zen Hei (Regular)
Arial Unicode MS (Regular)
Lohit Marathi (Regular)
Lohit Devanagari (Regular)