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.

Request workflow

The image processing workflow with iLoveIMG API 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 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.

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 iLoveIMG 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.

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.

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.

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.

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.

Task

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 iLoveIMG 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

iLoveIMG 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 iLoveIMG'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

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 file processing, Digital Signatures, and SMS authentication. They are consumed like this:

• 1 File Processing credit is consumed for each file that is successfully processed in a tool.*
• 1 Digital Signature credit is consumed for each file that is used in a Signature Request.
• 1 SMS credit is consumed for each mobile number provided in a Signature Request.

*File processing credits are not consumed in the Sign PDF tool.