Create a dossier based on a template

Sometimes users want to generate a dossier based on a template, for example a rental agreement. In the API it is possible to create a dossier based on an existing template. Templates can be created, edited, and deleted from the dashboard, but also from the API. For more information on managing templates from the API, refer to Templates API reference.

To use a template in the API, the template must abide the following conditions:

Have at least one document
Have only placeholder recipients, and no real recipients (recipients with real data)
Not have any open text labels

To create a dossier based on an existing template, the template ID needs to be obtained. This ID can be obtained from the API, but also from the dashboard by logging in and going to the Templates section. If you haven't created a template already, you can create one in this section. Select the 3 dots at the right hand side of the template you want to use, then click on the info option. A window containing the template ID will be shown. The template ID can be copied and used to create the dossier via the API.
An example of a template ID is 06c2e210-54a8-417f-adf2-fc767c31c929.

To create the dossier, add the obtained template ID to the template field in the request body.

Note: make sure you add the same number of invitees to the dossier as configured in the template.

Request

POST https://api.cm.com/sign/v1/dossiers

Request headers

Content-Type: application/json
Authorization: Bearer GENERATED_TOKEN_HERE

Request body

{
    "name": "Rental agreement based on an existing template",
    "template": "06c2e210-54a8-417f-adf2-fc767c31c929",
    "invitees": [
        {
            "name": "Invitee",
            "email": "[email protected]"
        }
    ]
}

Response

{
    "id": "397d92f7-5a68-40fe-abb8-ef2ccfa4127e",
    "name": "Rental agreement based on an existing template",
    "state": "draft",
    "locale": "en-US",
    "completed": false,
    "invitees": [
        {
            "id": "c85b009c-6b94-4be6-974c-70464323699d",
            "name": "Invitee",
            "email": "[email protected]",
            "readOnly": false,
            "fields": [
                {
                    "id": "ae4bb99d-ef9e-4a2d-8a13-63e4ca8ede1a",
                    "name": "AE4BB99D",
                    "type": "signature",
                    "required": true,
                    "invitee": "c85b009c-6b94-4be6-974c-70464323699d",
                    "locations": [
                        {
                            "range": "1",
                            "unit": "point",
                            "x": 70.3448,
                            "y": 262.0345,
                            "width": 164.431,
                            "height": 45.7241
                        }
                    ]
                }
            ]
        }
    ],
    "expiresIn": 2592000,
    "expiresAt": "2023-01-31T00:00:00+00:00",
    "createdAt": "2023-01-01T00:00:00+00:00"
}

API template

A template can be created from the API, for more information refer to API reference.

URL

POST https://api.cm.com/sign/v1/templates

To create a template ready for a dossier, some of the optional fields are required.

Request body

{
    "name": "API template",
    "files": [
        {
            "id": "8d817359-7eb8-4b6e-9030-17ac286b7dc0"
        }
    ],
    "attachments": [
        {
            "id": "8d817359-7eb8-4b6e-9030-17ac286b7dc0"
        }
    ],
    "invitees": [
        {
            "name": "Recipient 1"
        }
    ],
    "fields": [
        {
            "required": false,
            "invitee": 0,
            "type": "label",
            "value": "product",
            "file": 0,
            "locations": [
                {
                    "range": "1",
                    "unit": "point",
                    "x": 100,
                    "y": 250,
                    "width": 100,
                    "height": 50
                }
            ]
        }
    ]
}

This template includes a label field that makes use of the optional value field to specify the value of the label :"product". The value field can be any custom string. This label can later be overwritten when creating the dossier as shown in the section below.

Overwritable template labels

In some situations, you might need to adjust data in a template to fit specific needs. That's why we've enhanced predefined label fields. They can now also serve as handy placeholders for different information, offering a new level of flexibility.

Let's extend the example above where we have a rental agreement based on a template. In this template we will add two predefined labels. One label that acts as a placeholder for a product, and one label for its price. We will name these labels accordingly.

Select the "Predefined text" label option and add it to the document.

As you see we have now added two labels. When that will act as a placeholder for the product and another for its price. — As you see, we have now added two labels. One that will act as a placeholder for the product, and another for its price.

There is also the option to place the invitee's name and email address in the template. These will be set from the invitee object inside the request.

Now when we create a dossier based on this template, we can add the templateLabelValues property inside the request. This will be an object containing key value pairs. The key represents the current predefined label value and must match this exactly. It will then be overwritten with the value.

Request body

{
    "name": "Rental agreement based on an existing template",
    "template": "06c2e210-54a8-417f-adf2-fc767c31c929",
    "templateLabelValues": {
        "product": "Party tent XXL",
        "price": "499"
    },
    "invitees": [
        {
            "name": "Invitee",
            "email": "[email protected]"
        }
    ]
}