Create a sign request with a template

A Box Sign template is a document that already has signature and initials fields, signer roles, and optional email settings. You create and manage templates in the Box web app. The API can list templates and create sign requests from them. It cannot create, edit, or delete templates. Signature and initials fields on a template belong to a specific signer. They can be required or optional. Your app can prefill them when you create a request from the template, but the signer who owns a field can still change it when they open the request. You can also verify signer identity for a template recipient. For every create-time option, see Create a Box Sign request.

Create a template

In Box Sign, open Sign and select Templates. Select New Template, then choose or upload a document.

Selecting a document when creating a template

Place the signature and initials fields you need, such as date, name, and signature, then save the template.

Adding the signature, name, and date to the template

See the Creating templates in Box Sign support article for UI details.

Get the template ID

Use the list Box Sign templates endpoint to find the template_id.

curl -i -X GET "https://api.box.com/2.0/sign_templates" \
     -H "authorization: Bearer <ACCESS_TOKEN>"

The response is similar to this abbreviated example. For the full schema, see the List Box Sign templates endpoint.

{
  "entries": [
    {
      "id": "6ae28666-03c4-4ac1-80db-06a90d3b1361",
      "name": "Contract.pdf",
      "parent_folder": {
        "id": "157064745449",
        "type": "folder",
        "name": "My Sign Requests"
      },
      "signers": [
        {
          "email": "",
          "label": "reader",
          "role": "final_copy_reader"
        },
        {
          "email": "",
          "label": "signer1",
          "role": "signer"
        },
        {
          "email": "",
          "label": "signer2",
          "role": "signer",
          "inputs": [
            {
              "document_tag_id": "signer2_full_name",
              "type": "text",
              "content_type": "full_name"
            },
            {
              "document_tag_id": null,
              "type": "signature"
            },
            {
              "document_tag_id": null,
              "type": "date"
            }
          ]
        }
      ]
    }
  ]
}

To inspect one template, including every input and document_tag_id, use the get Box Sign template by ID endpoint.

curl -i -X GET "https://api.box.com/2.0/sign_templates/6ae28666-03c4-4ac1-80db-06a90d3b1361" \
     -H "authorization: Bearer <ACCESS_TOKEN>"

Create the sign request

Pass template_id, parent_folder, and signer emails when you create the request. You do not need source_files when the template already references the document. Keep signer order in the POST body the same as the order on the template. In the template editor, assign a tag ID to any signature or initials field you want to prefill, then send prefill_tags with that document_tag_id.

Assigning a tag id to a signature property input

{
  "template_id": "6ae28666-03c4-4ac1-80db-06a90d3b1361",
  "parent_folder": {
    "id": "123456789000",
    "type": "folder"
  },
  "signers": [
    {
      "email": "signer1@example.com",
      "role": "signer"
    },
    {
      "email": "signer2@example.com",
      "role": "signer"
    }
  ],
  "prefill_tags": [
    {
      "document_tag_id": "signer1_full_name",
      "text_value": "Ebenezer Scrooge"
    },
    {
      "document_tag_id": "signer2_full_name",
      "text_value": "Bob Cratchit"
    }
  ]
}

curl -i -X POST "https://api.box.com/2.0/sign_requests" \
     -H "authorization: Bearer <ACCESS_TOKEN>" \
     -H "content-type: application/json" \
     -d '{
       "template_id": "6ae28666-03c4-4ac1-80db-06a90d3b1361",
       "parent_folder": {
         "type": "folder",
         "id": "123456789000"
       },
       "signers": [
         {
           "email": "signer1@example.com",
           "role": "signer"
         },
         {
           "email": "signer2@example.com",
           "role": "signer"
         }
       ],
       "prefill_tags": [
         {
           "document_tag_id": "signer1_full_name",
           "text_value": "Ebenezer Scrooge"
         },
         {
           "document_tag_id": "signer2_full_name",
           "text_value": "Bob Cratchit"
         }
       ]
     }'

The response includes the new request id, template_id, and the prefill values. Preparation is not needed when the template already placed the signature and initials fields. The date field, if present, is populated with the current date. Signers can still change values they own.

Signing the document with a prefilled name

If the document already includes signature and initials tags and you do not want to manage a template in the web app, see Signing structured docs.

Getting started

Applications & integrations

Identity & access

Using the API

Troubleshooting

Content

Collaboration

Metadata & search

Events & webhooks

Users

Intelligent workflow

E-signatures

Security & compliance

Create a sign request with a template

Create a template

Get the template ID

Create the sign request

​Create a template

​Get the template ID

​Create the sign request

Create a template

Get the template ID

Create the sign request