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.


There are two type of document request :


  • Synchrone request : This type of document request allow you to create a single document. If the generation works fine, you'll get the generated document directly in the response.


  • Asynchrone request : This type of document request allow you to create a batch of documents in one request. The generation will occur asynchronously and the generated documents will be sent to your application through a webhook when the generation is completed (successfully or not).


A document request includes the following fields :


  • id : a 6 digit unique identifier


  • tag : an identifier that can be provided upon creation used to identify the resource


  • type : the type of document request, can be synchrone or asynchrone.


  • external_application : informations about the external application used to create the document request.


  • documents_generations : the list of documents generated through the document request. Each document generation will have the following fields :


    • id : a 6 digit 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. Can be created, pending, success or error


    • file : informations about the document generated if the generation is succeeded. It includes the following fields :


      • file_name : the name of the file generated


      • url : an s3 url to access the file generated. Note that this url will expire after 10 minutes.


      • size : the size of the document generated.



Create a synchrone document request

A synchrone document request can hold a single document generation and so can be used to generate only a single document.


To create one you need to perform the following HTTP POST request :


1
2curl --location --request POST 'https://app.doclift.io/api/v1/document_requests' \
3--header 'Content-Type: application/json' \
4--header 'X-Api-Key: 152810024b6e15[...]2b3732de83c8ad887ec' \
5--data-raw '{
6  "document_request": {
7    "type": "synchrone",
8    "document_generations": [
9        {
10            "template_id": "100011",
11            "variables": {
12                "firstname": "John",
13                "lastname": "Doe",
14                
15                ...
16                "city": "Paris"
17            },
18            "tag": "sample tag #01"
19        }
20    ],
21    "tag": "sample tag A"
22  }
23}'
24


Then you'll then get the following sample response :


1
2{
3    "id": 100021,
4    "tag": "sample tag #01",
5    "type": "synchrone",
6    "documents_generations": [
7        [
8            {
9                "id": 100320,
10                "tag": "sample tag A",
11                "generated_at": "2021-03-14 15:41:28 +0100",
12                "created_at": "2021-03-14 15:41:25 +0100",
13                "generation_status": "success",
14                "file": {
15                    "filename": "Sample document - 2923899292.pdf",
16                    "url": "https://doclift.s3.eu-west-3.amazonaws.com/106cafa805019dcca046b6df3db15e1b.pdf?[...]",
17                    "size": 40290
18                }
19            }
20        ]
21    ]
22}
23


Note that the template given must be published and that the s3 url will expire after 10 minutes. Take also into account the fact that the generation duration is proportional to the template size and might increase with some external factors this is why at DocLift we strongly recommend to prefer the asynchrone generation.


Create an asynchrone document request

An asynchrone document request can hold up to 100 documents generations. The main difference with the synchrone document request is that upon creation, you only 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.


To create an asynchrone document request, you can perfom the following HTTP POST request :


1
2curl --location --request POST 'https://app.doclift.io/api/v1/document_requests' \
3--header 'Content-Type: application/json' \
4--header 'X-Api-Key: 1528[...]dd887ec' \
5--data-raw '        {
6  "document_request": {
7    "type": "asynchrone",
8    "document_generations": [
9      {
10        "template_id": "100017",
11        "variables": {
12          "firstname": "John",
13          "lastname": "Doe",
14          ...
15          "city": "Paris"
16        },
17        "tag": "Subscription#102"
18      },
19      {
20        "template_id": "100014",
21        "variables": {
22          "firstname": "Lea",
23          "lastname": "Maquize",
24          ...
25          "city": "London"
26        },
27        "tag": "Subscription#103"
28      }
29    ],
30    "tag": "Batch#12"
31  }
32}'
33


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


1
2{
3    "id": 100004,
4    "tag": "TestGeneration10",
5    "type": "asynchrone",
6    "sandbox_mode": true,
7    "status": "in_progress"
8}
9


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 will be completed, you'll receive all the corresponding data as a webhook :


1
2{
3    "id": 100004,
4    "tag": "Batch#12",
5    "type": "asynchrone",
6    "documents_generations": [
7        [
8            {
9                "id": 100230,
10                "tag": "Subscription#102",
11                "generated_at": "2021-03-14 16:55:14 +0100",
12                "created_at": "2021-03-14 16:55:13 +0100",
13                "generation_status": "success",
14                "file": {
15                    "filename": "Attestation de Personne Politiquement Exposée-1615737313.pdf",
16                    "url": "https://doclift.s3.eu-west-3.amazonaws.com/d207f8fe1699150f44b13dbca92b6f35.pdf?[...]",
17                    "size": 40290
18                }
19            },
20            {
21                "id": 100230,
22                "tag": "Subscription#103",
23                "generated_at": "2021-03-14 16:55:14 +0100",
24                "created_at": "2021-03-14 16:55:13 +0100",
25                "generation_status": "success",
26                "file": {
27                    "filename": "Attestation de Personne Politiquement Exposée-1615737313.pdf",
28                    "url": "https://doclift.s3.eu-west-3.amazonaws.com/d207f8fe1699150f44b13dbca92b6f35.pdf?[...]",
29                    "size": 40290
30                }
31            }
32        ]
33    ]
34}
35
36
We'll expect a 200 HTTP response code within 3 seconds. If we don't we'll try again up to 3 times.


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 :


1
2[
3    {
4        "id": 100004,
5        "tag": "TestGeneration10",
6        "type": "asynchrone",
7        "external_application": {
8            "id": 100000,
9            "name": "Application externe #1",
10            "environment": "sandbox",
11            "active": true
12        },
13        "documents_generations": [
14            {
15                "id": 100230,
16                "tag": "Subscription#103",
17                "generated_at": "2021-03-14 16:55:14 +0100",
18                "created_at": "2021-03-14 16:55:13 +0100",
19                "generation_status": "success",
20                "file": {
21                    "filename": "Attestation de Personne Politiquement Exposée-1615737313.pdf",
22                    "url": "https://doclift.s3.eu-west-3.amazonaws.com/d207f8fe1699150f44b13dbca92b6f35.pdf?[...]",
23                    "size": 40290
24                }
25            },
26            ...
27        ]
28    },
29    ...
30]
31
32
The results are paginated. Refer to the pagination chapter for more informations about pagination.


View a document request

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


GET https://app.doclift.io/api/v1/document_requests/<DOCUMENT_REQUEST_ID>


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


1
2{
3    "id": 100004,
4    "tag": "TestGeneration10",
5    "type": "asynchrone",
6    "external_application": {
7        "id": 100000,
8        "name": "Application externe #1",
9        "environment": "sandbox",
10        "active": true
11    },
12    "documents_generations": [
13        {
14            "id": 100003,
15             "file": {
16                    "filename": "Attestation de Personne Politiquement Exposée-1615737313.pdf",
17                    "url": "https://doclift.s3.eu-west-3.amazonaws.com/d207f8fe1699150f44b13dbca92b6f35.pdf?[...]",
18                    "size": 40290
19            },
20            "tag": "Subscription#102",
21            "generated_at": "2021-03-14 16:55:14 +0100",
22            "created_at": "2021-03-14 17:20:08 +0100",
23            "sent_payload": {
24                "firsntame": "John",
25                "lastname": "Doe"
26            },
27            "generation_duration": 1721,
28            "generation_status": "success",
29            "generation_error": null,
30            "template": {
31                "id": 100017,
32                "title": "Contrat de travail",
33                "description": "Contrat de travail de l'entreprise.",
34                "variables": [
35                    {
36                        "title": "firstname",
37                        "description": "firstname of the investor in the Xxxxx format."
38                    },
39                    {
40                        "title": "lastname",
41                        "description": "lastname of the investor in the Xxxxx format."
42                    }
43                ]
44            }
45        },
46        ...
47    ]
48}
49
As you can see, you also get informations about the list of variables keys and values sent to create the document requests. This can be useful for debugging.


;