API Basics

A RESTful API

We designed the DocLift API in a RESTful way, so that your user experience is simple and close to what you are used to when working with APIs :


  • Submit data requires an HTTP POST request


  • Retrieve data requires an HTTP GET request


  • Change data requires an HTTP PUT request


  • Delete data requires an HTTP DELETE request


  • Requests must be sent using Content-Type "application/json". The request and response body encoding is always UTF-8. Any request should be sent through the HTTPS protocol.


Communication with the DocLift ™ API should be done from your server directly to our server, and not from a user's browser - otherwise your security is easily compromised.


Dates format

All dates and times in the DocLift ™ API are given in the ISO-8601 format in the GTM+1 timeline (Paris).


For instance 2021-02-23 16:39:00 +0100 is equivalent to the 23th of February, 2021 at 4:39 PM in the Paris timeline.


Response codes

The following HTTP codes are used by the API to respond to requests:


  • 200 : Request successful


  • 422 : Any kind of logical error with your request (missing parameters, invalid operation, constraint violation etc.)


  • 403 : Access is forbidden (authentication or authorisation failure)


  • 404 : Object not found


  • 500 : Internal server error - we advise you to try again later, or contact support if the problem persists 



Authentication

Any request made the DocLift ™ API requires an authentification made through an API Key.


In order to be authenticated, you need to provide an X-API-Key header with your API Key as a value. You can't create one from your DocLift ™ account.


If the X-API-Key header is not provided, you'll receive the following 403 error :


{ "error": "Please add an 'X-Api-Key' HTTP header." }


If you provide an invalid API key (deleted, inexistant or disabled) through your X-API-Key header, you'll receive the following 403 error :


{ "error": "Invalid or disabled API Key." }



Environments

The DocLift ™ API is divided into two environments :


  • Development : This environment is available and fully operational as soon as you have created your account. The generated documents are not accounted in your monthly generations quota. Therefore, the generated document are watermaked. This environment includes all the features of the DocLift ™ API.


  • Production : In order to use this environment, you need to activate your account and subscribe to a premium plan. To upgrade your account, please contact an administrator at [email protected]. When using this environment, each generated documents will be accounted in your monthly generations quota.


The 2 environments share the same templates and datas, this allows to first test your template before using them in production. Upon creating an external application, you'll be prompted to choose wether it will be a development or production external application, then depending on your choice, the document generated will belongs to the corresponding environment.


External applications

External applications will allow you to use the DocLift ™ with your web or mobile platforms. They are your credentials. You can have as many as you need. Each external application will have the following fields :


  • Name * : A name you can provide to identify it easily. By default External Application #{index}.


  • Environment * : wether it will be used for "development" or "production" purpose. It cannot be changed.


  • API Key * : The API Key needed to use it. Be sure to save, it will be shown only upon creation.


  • Webhook URL : The URL where we'll notify when a document request has been completed. It is mandatory if you want to use batch generation which is asynchronous.


  • State : Wether the external application is active or disabled. Please note that only active external application can be used through the DocLift ™ API.



Pagination

Every list in the DocLift ™ API is paginated. The records are paginated by 30. To help you navigate through pages, we provided you pagination headers:


  • current_page: the current page you're in.


  • results : the number of results in the current page.


  • results_per_page: a reminder of how many records are retrieved in each page.


  • pages_count: the total pages count for this list.


You can navigate through page by providing a params ?page=X , for instance if you want to go the fourth page of the templates API :


GET https://app.doclift.io/api/v1/templates?page=4


If you don't provide any ?page=X params, we'll fallback to the first page.


;