API Document Requests

The Document Request object

A document request is the object that you'll get when you request to create one or more documents from one or more templates.

The generation occurs asynchronously: upon creation, you get the ID of the document request as the HTTP response, and the generated documents are delivered to your application through a webhook when the generation is completed (successfully or not).

A document request includes the following fields:

id: a unique identifier
tag: an identifier that can be provided upon creation, used to identify the resource
type: the type of document request — asynchrone
priority: the generation priority — critical, default, or low. Defaults to critical. In sandbox mode, priority is always forced to low. See Priority below.
external_application: information about the external application used to create the document request
documents_generations: the list of documents generated through the document request. Each document generation includes the following fields:
- id: a unique identifier
- tag: an identifier that can be provided upon creation, used to identify the resource
- created_at: the document generation creation date in the ISO-8601 format
- generated_at: the document generation date in the ISO-8601 format
- generation_status: the status of the document generation — created, in_progress, success, or error
- file: information about the generated document if the generation succeeded. Includes the following fields:
  - filename: the name of the generated file
  - url: a pre-signed S3 URL to download the generated file. This URL expires after 2 hours for webhook payloads and 20 hours for the GET show endpoint.
  - size: the size of the generated document in bytes

The GET show endpoint also returns additional fields per document generation:

generation_duration: the duration of the generation in milliseconds
generation_error: error details if the generation failed, null otherwise
sent_payload: the variables key/value pairs that were sent to generate the document (useful for debugging)
template: the template used (id, title, description)

Priority

You can set a generation priority when creating a document request. This determines how quickly your document will be processed in the queue:

critical (default): processed first, ideal for user-facing documents that need immediate generation
default: standard processing order
low: processed last, suitable for batch or background generations

In sandbox mode, the priority is always forced to low regardless of the value provided.

To set a priority, include the priority field in your document request:

{
    "document_request": {
        "type": "asynchrone",
        "priority": "critical",
        "document_generations": [...]
    }
}

Create a document request

A document request can hold up to 100 document generations. Upon creation, you get the ID of the document request as the HTTP response. The document generations will be sent to you through webhooks.

Note that the webhook will be sent to the webhook URL attached to the external application used. You need to specify one from your DocLift account. The request will be rejected if no webhook URL is configured.

To create a document request, perform the following HTTP POST request:

curl --location --request POST 'https://app.doclift.io/api/v1/document_requests' \
--header 'Content-Type: application/json' \
--header 'X-Api-Key: 1528[...]dd887ec' \
--data-raw '{
  "document_request": {
    "type": "asynchrone",
    "document_generations": [
      {
        "template_id": "100017",
        "variables": {
          "firstname": "John",
          "lastname": "Doe",
          "city": "Paris"
        },
        "tag": "Subscription#102"
      },
      {
        "template_id": "100014",
        "variables": {
          "firstname": "Lea",
          "lastname": "Maquize",
          "city": "London"
        },
        "tag": "Subscription#103"
      }
    ],
    "tag": "Batch#12"
  }
}'

You'll then get the ID and status of your document request:

{
    "id": 100004,
    "tag": "Batch#12",
    "type": "asynchrone",
    "sandbox_mode": true,
    "status": "in_progress"
}

At this step, we strongly recommend you to store the document request ID. This will allow you to easily associate the webhook you'll receive with the request or perform a GET later in case you missed the webhook or lost any data.

Once your document(s) generation is completed, you'll receive all the corresponding data as a webhook. See Webhooks for details on the webhook payload format, signature verification, and retry policy.

Variable validation errors

When generating a document from a template that uses radio or select variables with allowed_values, the API validates the provided values. If a value is not in the allowed list, you'll receive a 422 Unprocessable Entity response:

{
    "error": "Invalid variables",
    "invalid_variables": [
        {
            "field": "status",
            "value": "unknown",
            "allowed_values": ["active", "inactive", "pending"]
        }
    ]
}

List document requests

You can list the document requests of an account by performing the following HTTP GET request:

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

You'll get:

[
    {
        "id": 100004,
        "tag": "TestGeneration10",
        "type": "asynchrone",
        "external_application": {
            "id": 100000,
            "name": "Application externe #1",
            "environment": "sandbox",
            "active": true
        },
        "documents_generations": [
            {
                "id": 100230,
                "tag": "Subscription#103",
                "generated_at": "2021-03-14 16:55:14 +0100",
                "created_at": "2021-03-14 16:55:13 +0100",
                "generation_status": "success",
                "file": {
                    "filename": "Attestation-1615737313.pdf",
                    "url": "https://doclift.s3.eu-west-3.amazonaws.com/d207f8fe.pdf?[...]",
                    "size": 40290
                }
            }
        ]
    }
]

The results are paginated. Refer to the pagination chapter for more information about pagination.

View a document request

You can show detailed information about any document request of your account by performing the following HTTP GET request:

GET https://app.doclift.io/api/v1/document_requests/:id

If the provided document request exists, you'll get:

{
    "id": 100004,
    "tag": "TestGeneration10",
    "type": "asynchrone",
    "external_application": {
        "id": 100000,
        "name": "Application externe #1",
        "environment": "sandbox",
        "active": true
    },
    "documents_generations": [
        {
            "id": 100003,
            "tag": "Subscription#102",
            "generated_at": "2021-03-14 16:55:14 +0100",
            "created_at": "2021-03-14 17:20:08 +0100",
            "generation_status": "success",
            "generation_duration": 1721,
            "generation_error": null,
            "sent_payload": {
                "firstname": "John",
                "lastname": "Doe"
            },
            "file": {
                "filename": "Attestation-1615737313.pdf",
                "url": "https://doclift.s3.eu-west-3.amazonaws.com/d207f8fe.pdf?[...]",
                "size": 40290
            },
            "template": {
                "id": 100017,
                "title": "Contrat de travail",
                "description": "Contrat de travail de l'entreprise."
            }
        }
    ]
}

The detailed view includes sent_payload, generation_duration, generation_error, and the associated template for each document generation — useful for debugging. The S3 URLs in this view expire after 20 hours.