Skip to main content
A Box Sign template is a specific type of document that not only contains the text, but also the signature requirements and placement. It is prepared for signing in advance, and as such can be sent directly to the signer or signers. Required fields include, for example, the signature pad field, the full name, and the date. These fields have an owner, meaning they are populated by a specific signer and cannot be shared between them. They can be mandatory or optional , and be pre-populated by your application. However even if pre-populated, they can always be changed by the signer. Within the Box web app, the template not only sets the signature fields, but also the number of signers, the order in which they sign, other roles and recipients such as approver, and final_copy_recipient, email notification settings, and a few more options. For a complete set of options of the signature request please refer to the request options section. These templates are exclusively created and managed in the Box Sign web app, and can be used to create signature requests using the API or the web app. Let’s start by creating a template.

​
Creating a template

From the Box app navigate to the sign menu on the left, then select templates.
Navigating to templates under Box Sign
Then, click on the New Template button, and choose or upload the document from Box.
Selecting a document when creating a template
For example, drag and drop a date, a name and a signature pad to the template, like so:
Adding the signature, name, and date to the template
You can add an extra layer of security for a recipient. It works for both a defined recipient with a pre-defined email address, and a placeholder recipient, where the template user has to provide their email address.
Save the template.

​
Identify the template

In order to work with templates in the Box Sign API we are going to need the template_id . Consider this method to list all the templates available to the user: 
curl --location 'https://api.box.com/2.0/sign_templates' \
    --header 'Authorization: Bearer E9...Q0'
Returns something similar to (simplified): 
{
  "limit": 10,
  "next_marker": null,
  "prev_marker": null,
  "entries": [
    {
      "type": "sign-template",
      "id": "f2ec720d-47a6-4052-8210-9bfa8d6c349c",
      "name": "Simple-DOC.pdf",
      "parent_folder": {
        "id": "157064745449",
        "type": "folder",
        "name": "My Sign Requests"
      },
      "source_files": [
        {
          "id": "1393013714313",
          "type": "file",
        }
      ],
      "signers": [
        {
          "email": "",
          "label": "",
          "role": "final_copy_reader",
          "inputs": []
        },
        {
          "email": "",
          "label": "Signer",
          "role": "signer",
          "inputs": [
            {
              "document_tag_id": null,
              "id": "d02c8e16-5050-475e-b74b-9a952193e4f8",
              "type": "date",
              "date_value": null,
              "content_type": "date",
            },
            {
              "document_tag_id": null,
              "id": "bdcc966e-2ebf-4b3b-aaee-99d4e1161a9e",
              "type": "text",
              "text_value": null,
              "is_required": true,
              "content_type": "full_name",
            },
            {
              "document_tag_id": null,
              "id": "1a8f4cb1-5c09-46bd-96f5-0ab449f19640",
              "type": "signature",
              "text_value": null,
              "is_required": true,
              "content_type": "signature",
            }
          ]
        }
      ],
    }
  ]
}

​
Creating a signature request from a template

The big advantage of using templates is that we do not need to worry about document preparation. Most of the signature options can be set in the template itself. This is how the flow would look like:
Signing using a template
Using a signature template, create the signature request, and finally sign the document. See this example: 
curl --location 'https://api.box.com/2.0/sign_requests' \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Bearer E9...Q0' \
    --data-raw '{
      "template_id": "f2ec720d-47a6-4052-8210-9bfa8d6c349c",
      "parent_folder": {
        "id": "234102987614",
        "type": "folder"
      },
      "signers": [
        {
          "email": "[email protected]",
          "role": "signer"
        }
      ]
    }'
Resulting in (simplified): 
{
  "signers": [
    {
      "email": "[email protected]",
      "role": "final_copy_reader",
    },
    {
      "email": "[email protected]",
      "role": "signer",
    }
  ],
  "id": "71e86670-5850-44cc-8b4d-9f5eab6c04de",
  "parent_folder": {
    "id": "234102987614",
    "type": "folder",
    "name": "signed docs"
  },
  "name": "Simple-DOC (1).pdf",
  "type": "sign-request",
  "status": "created",
  "sign_files": {
    "files": [
      {
        "id": "1393030489686",
        "type": "file",
        "name": "Simple-DOC (1).pdf",
      }
    ],
  },
  "template_id": "f2ec720d-47a6-4052-8210-9bfa8d6c349c"
}
The signer receives an email from Box.com with a link to the document, and can sign it.
Since the template already had the signature requirements, document preparation was not needed. Notice the date was automatically populated with the current date.

​
Pre-populate the signature attributes

From a usability perspective, it is a good idea to pre-populate the inputs you require from your users.
Some inputs may be intentionally left unpopulated. For example, when your legal department specifies that the “Yes, I agree” field must be explicitly set by the signer.
Using the Box app sign template editor, you can assign an external_id to each of the inputs, and have the app populate them from any data source. Let’s implement this for the name. Go back to the template design and add an id to the name field:
Assigning a tag id to a signature property input
Save the template. Let’s create a new method to pre-populate the name: 
curl --location 'https://api.box.com/2.0/sign_requests' \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Bearer E9..Q0' \
    --data-raw '{
      "template_id": "f2ec720d-47a6-4052-8210-9bfa8d6c349c",
      "parent_folder": {
        "id": "234102987614",
        "type": "folder"
      },
      "signers": [
        {
          "email": "[email protected]",
          "role": "signer"
        }
      ],
      "prefill_tags": [
        {
          "document_tag_id": "signer_full_name",
          "text_value": "Signer A"
        }
      ]
    }'

{
  "signers": [
    {
      "email": "[email protected]",
      "role": "final_copy_reader",
    },
    {
      "email": "[email protected]",
      "role": "signer",
      "is_in_person": false,
    }
  ],
  "id": "6f42a041-7ed8-4e08-9958-78a97259f80d",
  "prefill_tags": [
    {
      "document_tag_id": "signer_full_name",
      "text_value": "Signer A",
    }
  ],
  "parent_folder": {
    "id": "234102987614",
    "type": "folder",
    "name": "signed docs"
  },
  "name": "Simple-DOC (2).pdf",
  "type": "sign-request",
  "status": "created",
  "sign_files": {
    "files": [
      {
        "id": "1393047116817",
        "type": "file",
        "name": "Simple-DOC (2).pdf",
      }
    ],
  },
  "template_id": "f2ec720d-47a6-4052-8210-9bfa8d6c349c"
}
Open the signer inbox and complete the sign request.
Signing the document
When the signer views the document, the signer can still change it.

​
Get more information about a template

You’ve seen that you can list the templates available to a user. But you can also get more information about a specific template. Let’s create a method that returns basic information of a template, but details all the signature requirements: 
curl --location 'https://api.box.com/2.0/sign_templates/
f2ec720d-47a6-4052-8210-9bfa8d6c349c' \
    --header 'Authorization: Bearer OL..BQ'

{
  "type": "sign-template",
  "id": "f2ec720d-47a6-4052-8210-9bfa8d6c349c",
  "name": "Simple-DOC.pdf",
  "parent_folder": {
    "id": "234102987614",
    "type": "folder",
    "name": "signed docs"
  },
  "source_files": [
    {
      "id": "1393013714313",
      "type": "file",
    }
  ],
  "signers": [
    {
      "email": "",
      "label": "",
      "role": "final_copy_reader",
    },
    {
      "email": "",
      "label": "Signer",
      "role": "signer",
      "inputs": [
        {
          "document_tag_id": null,
          "id": "d02c8e16-5050-475e-b74b-9a952193e4f8",
          "type": "date",
          "is_required": true,
          "date_value": null,
          "content_type": "date",
        },
        {
          "document_tag_id": "signer_full_name",
          "id": "bdcc966e-2ebf-4b3b-aaee-99d4e1161a9e",
          "type": "text",
          "text_value": null,
          "is_required": true,
          "content_type": "full_name",
        },
        {
          "document_tag_id": null,
          "id": "1a8f4cb1-5c09-46bd-96f5-0ab449f19640",
          "type": "signature",
          "is_required": true,
          "content_type": "signature",
        }
      ]
    }
  ],
}
Notice that the signer_full_name is the tag_id we used to pre-populate the name.

​
Summary

Templates are a form of signing structured documents where the signature requirements are already defined and placed on the document. This not only keeps your contract management team happy, but it also creates a process which is consistent and requires a low level of effort from your users. Finally if your document signature requirements have a lot of options, you can pre-populate these from another data source and save the user some time. Remember that the user who owns these properties can always change them. There is no API entry point to create a template, so you will have to create and manage them manually from the Box app, unless the document already includes signature tags that can be used by the Box Sign engine. Take a look at our Structured Docs section for more information.