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 or PATCH 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.

Base URL

All API endpoints use the following base URL:

https://app.doclift.io/api/v1

Dates format

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

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

Response codes

The DocLift API returns the following HTTP response codes:

  • 200 OK: the request was successful.
  • 201 Created: the resource was successfully created (returned by POST endpoints).
  • 204 No Content: the request was successful and there is no response body (returned by DELETE endpoints).
  • 400 Bad Request: the request body is malformed or missing required parameters.
  • 403 Forbidden: the API key is missing, invalid, or disabled.
  • 404 Not Found: the requested resource does not exist.
  • 422 Unprocessable Entity: the request body contains invalid data (e.g. invalid variable values).
  • 500 Internal Server Error: an unexpected error occurred on our side.

Pagination

Every list in the DocLift API is paginated. To help you navigate through pages, we provide pagination response headers:

  • results: the number of records on the current page
  • results_per_page: the number of records per page
  • current_page: the current page number
  • pages_count: the total number of pages

To navigate to a specific page, add the page query parameter to the request URL.

Environments

DocLift works with two types of environments:

  • Sandbox: 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 documents are watermarked. 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 document will be accounted in your monthly generations quota.

The 2 environments share the same templates and data, this allows you to first test your templates before using them in production. Upon creating an external application, you'll be prompted to choose whether it will be a sandbox or production external application, then depending on your choice, the documents generated will belong to the corresponding environment.

External applications and authentication

In order to communicate with the DocLift API you'll need to add an API key to each request.

You can create a new API key by navigating to this page or clicking on "Nouvelle clé API" on the API keys' page. An API key is called an external application and has the following attributes:

  • Name: The name you gave to your external application.
  • API key: A hash that authenticates your request to the DocLift API. To authenticate, add the X-Api-Key header to each request with the API key value.
  • Environment: The environment of the external application (sandbox or production).
  • Webhook URL (optional): The URL where DocLift will send webhook notifications for asynchronous document generations. Must be an HTTPS URL. See the Webhooks section for details.

User info

You can retrieve information about the authenticated user and the current external application by performing:

GET https://app.doclift.io/api/v1/user

{
    "id": 100001,
    "firstname": "John",
    "lastname": "Doe",
    "email": "[email protected]",
    "created_at": "2021-02-15 10:30:00 +0100",
    "updated_at": "2021-06-20 14:00:00 +0100",
    "document_max_length_allowed": 800000,
    "webhooks_replays_count": 3,
    "allowed_to_use_production_mode": false,
    "current_external_application": {
        "id": 100000,
        "name": "My App",
        "environment": "sandbox",
        "active": true,
        "webhook_url": "https://myapp.com/webhooks/doclift",
        "revealable_secret_key": "•••...abc12345"
    }
}