Template
Templates are created in the same way as regular documents, but instead of associating signature fields with people, we simply associate fields with roles. A role is simply a placeholder for a real person. For example, if we have a purchase order that will always be signed by two people, one from the company and one from the customer, we can create a template with two roles, Customer
and Representative
.
This section demonstrates how to create, list, and delete templates. Templates can be created programmatically or via the BoldSign web interface and then used in your application.
Create template
post/v1/template/createWhen you need to send the same contracts out for signature to different groups of people repeatedly, you can use templates to save time. Once a template is created, sending contracts using that template takes less than a minute. Templates can be created for both self-signing and sending signature requests to other signers.
Code snippet
curl -X 'POST' \ 'https://api.boldsign.com/v1/template/create' \ -H 'accept: application/json' \ -H 'X-API-KEY: {your API key}' \ -H 'Content-Type: multipart/form-data' \ -F 'DocumentMessage=document message for signers' \ -F 'Files=@Bill-of-Sale.pdf;type=application/pdf' \ -F 'Title=title of the template' \ -F 'AllowMessageEditing=true' \ -F 'Description=testingDescription' \ -F 'DocumentTitle=title of the document' \ -F 'Roles={ "name": "Hr", "index": 1, "defaultSignerName": "Alex Gayle", "defaultSignerEmail": "alexgayle@cubeflakes.com", "signerOrder": 1, "signerType": "Signer", "formFields": [ { "id": "sign_id", "fieldType": "Signature", "pageNumber": 1, "bounds": { "x": 50, "y": 100, "width": 100, "height": 60 }, "isRequired": true } ] }'
var apiClient = new ApiClient("https://api.boldsign.com", "API-KEY"); var templateClient = new TemplateClient(apiClient); var documentFilePath = new DocumentFilePath { ContentType = "application/pdf", FilePath = @"D:\Bill-of-Sale.pdf", }; var filesToUpload = new List<IDocumentFile> { documentFilePath, }; var signatureField = new FormField( id: "sign_id", type: FieldType.Signature, pageNumber: 1, bounds: new Rectangle(x: 50, y: 50, width: 200, height: 30)); var formFieldsCollections = new List<FormField> { signatureField, }; var templateRole = new TemplateRole( name: "Hr", index: 1, defaultSignerName: "Alex Gayle", defaultSignerEmail: "alexgayle@cubeflakes.com", signerOrder: 1, signerType: SignerType.Signer, formFields: formFieldsCollections); var roles = new List<TemplateRole> { templateRole, }; var templateRequest = new CreateTemplateRequest() { Title = "title of the template", DocumentMessage = "document message for signers", Files = filesToUpload, Description = "testingDescription", DocumentTitle = "title of the document", Roles = roles }; var templateCreated = templateClient.CreateTemplate(templateRequest);
import requests url = "https://api.boldsign.com/v1/template/create" payload={'BrandId': '', 'EnableReassign': 'true', 'AllowNewRoles': 'true', 'EnablePrintAndSign': 'false', 'DocumentMessage': 'document message for signers', 'EnableSigningOrder': 'false', 'UseTextTags': 'false', 'Title': 'title of the template', 'AllowMessageEditing': 'true', 'Description': 'testingDescription', 'DocumentTitle': 'title of the document', 'Roles': '{ "name": "Hr", "index": 1, "defaultSignerName": "Alex Gayle", "defaultSignerEmail": "alexgayle@cubeflakes.com", "signerOrder": 1, "signerType": "Signer", "language": 1, "imposeAuthentication": "None", "formFields": [ { "id": "sign_id", "name": "sign", "fieldType": "Signature", "pageNumber": 1, "bounds": { "x": 50, "y": 100, "width": 100, "height": 60 }, "isRequired": true } ], "allowRoleEdit": true, "allowRoleDelete": true }'} files=[ ('Files',('file',open('{file path}','rb'),'application/octet-stream')) ] headers = { 'accept': 'application/json', 'X-API-KEY': '<API-KEY>' } response = requests.request("POST", url, headers=headers, data=payload, files=files) print(response.text)
const axios = require('axios'); const FormData = require('form-data'); const fs = require('fs'); const form = new FormData(); form.append('BrandId', ''); form.append('EnableReassign', 'true'); form.append('AllowNewRoles', 'true'); form.append('EnablePrintAndSign', 'false'); form.append('DocumentMessage', 'document message for signers'); form.append('EnableSigningOrder', 'false'); form.append('UseTextTags', 'false'); form.append('Files', fs.readFileSync('Bill-of-Sale.pdf;type=application/pdf'), 'Bill-of-Sale.pdf;type=application/pdf'); form.append('Title', 'title of the template'); form.append('AllowMessageEditing', 'true'); form.append('Description', 'testingDescription'); form.append('DocumentTitle', 'title of the document'); form.append('Roles', '{\n "name": "Hr",\n "index": 1,\n "defaultSignerName": "Alex Gayle",\n "defaultSignerEmail": "alexgayle@cubeflakes.com",\n "signerOrder": 1,\n "signerType": "Signer",\n "language": 1,\n "imposeAuthentication": "None",\n "formFields": [\n {\n "id": "sign_id",\n "name": "sign",\n "fieldType": "Signature",\n "pageNumber": 1,\n "bounds": {\n "x": 50,\n "y": 100,\n "width": 100,\n "height": 60\n },\n "isRequired": true\n }\n ],\n "allowRoleEdit": true,\n "allowRoleDelete": true\n}'); const response = await axios.post( ' https://api.boldsign.com/v1/template/create', form, { headers: { ...form.getHeaders(), 'accept': 'application/json', 'X-API-KEY': '<API-KEY>', 'Content-Type': 'multipart/form-data' } } );
Request body
Heading1 | Heading2 |
---|---|
TitlestringRequired | The title of the template. |
Descriptionstring | The description of the template. |
DocumentTitlestring | This is the name of the document that will be displayed in the BoldSign user interface as well as in the signature request email. |
DocumentMessagestring | The message that will be seen by all recipients. You can include any instructions related to this document that the signer should be aware of before signing. |
Filesarray | The files to be uploaded for the template. .pdf , .png , .jpg , and .docx are supported file formats. You may upload up to 25 files. Each document may have a maximum of 1000 pages and must be no larger than 25MB in size. |
FileUrlsarray | The URL of the file to be uploaded that is publicly accessible. .pdf , .png , .jpg , and .docx are supported file formats. You may upload up to 25 files. Each document may have a maximum of 1000 pages and must be no larger than 25MB in size. |
Rolesarray | A role is simply a placeholder for a real person. For example, if we have a purchase order that will always be signed by two people, one from the company and one from the customer, we can create a template with two roles, Customer and Representative . Role properties are available here. |
CCarray | You can add anyone who needs to receive a copy of the signed document by adding their email address. |
BrandIdstring | You can customize the branding of signature request emails and document signing pages with your own colors, logos, and other elements. The brand id can be obtained from both the branding API and the web app branding page. |
AllowMessageEditingboolean | When disabled, you cannot change the message while creating a document with this template. The default value is true . |
AllowNewRolesboolean | When disabled, you cannot add additional signers to the document. The default value is true . |
EnableReassignboolean | When disabled, the reassign option is not available after sending the document out of signature. The default value is true . |
EnablePrintAndSignboolean | When enabled, the document can be printed and signed offline. The default value is false . |
EnableSigningOrderboolean | When enabled, signers can only sign the document in the order specified. Furthermore, the next signer will be notified when the previous signer has signed the document. The default value is false . |
DocumentInfoarray | This is used to specify the title and description of the document in the various supported languages. DocumentInfo properties are available here. |
UseTextTagsboolean | When enabled, it will convert all the tags defined in the document to boldsign form fields. The default value is false . |
TextTagDefinitionsarray | This can be used for the long text tag handling. TagDefinition properties are available here. |
Role properties
Heading1 | Heading2 |
---|---|
namestring | The name of the Role. |
indexinteger | The row index of the role. The role index should be in linear increments for each role (1, 2, 3, and so on). The index value must be between 1 and 50. |
defaultSignerNamestring | The signer name of the document. This name appears in all email communications, signing notifications, and the audit file. |
defaultSignerEmailstring | The signer email of the document. This email appears in all email communications, signing notifications, and the audit file. |
signerOrderinteger | The order of the signer. When you enable the signing order option, this will be required. The value must be between 1 and 50 . |
signerTypestring | The type of the signer and the values are Signer , Reviewer , and InPersonSigner . |
hostEmailstring | The host email address. It is a required property when the signerType is set to InPersonSigner . Your organization should have HostEmail. |
languageinteger | The language for the signer. The supported languages are 1-English , 2-Spanish , 3-German , 4-French , and 5-Romanian . |
imposeAuthenticationstring | This is used to allow authentication for a specific signer. We have two types of authentication. They are AccessCode and EmailOTP . |
formFieldsarray | List of fields associated with the signer. Form field properties are available here. |
allowRoleEditboolean | You can't change the signer details while sending the document out for signature if it's disabled. The default value is true . |
allowRoleDeleteboolean | You can't remove the signer details while sending the document out for signature if it's disabled. The default value is true . |
FormField properties
Heading1 | Heading2 |
---|---|
idstring | The id of the form field. |
namestring | The name of the form field. |
fieldTypestring | The type of the form field. The available values are Signature , Initial , CheckBox , TextBox , Label , DateSigned , RadioButton , Image , Attachment , EditableDate , Hyperlink , and Dropdown . |
pageNumberinteger | This will be used to specify which page the form field should be placed on. |
boundsobject | This will contain the form field's x and y coordinates, width, and height. Bound properties are available here. |
isRequiredboolean | When disabled, the signer does not want to fill out the form field. The default value is true . |
valuestring | The value of the form field. |
fontSizeinteger | The fontsize of the form field. |
fontstring | The font family of the form field. |
fontHexColorstring | The font color of the form field. |
isBoldFontboolean | When enabled, the font will be displayed in bold. |
isItalicFontboolean | When enabled, the font will be italic. |
isUnderLineFontboolean | When enabled, the font will be displayed in Underline format. |
lineHeightinteger | The line height of the form field. |
characterLimitinteger | The character limit in the form field. |
groupNamestring | The groupName of the form field. This field is required when the fieldType is set to RadioButton . |
placeHolderstring | The placeholder of the form field. |
validationTypestring | The validation type of the text box form field. The available values are None , NumbersOnly , EmailAddress , Currency , and CustomRegex . The default value is None . |
validationCustomRegexstring | The custom regex of the text box form field. When we set the ValidationType to CustomRegex , it will be required. |
validationCustomRegexMessagestring | The text box field's custom regex message. This message is displayed when the signer enters an invalid regex format value in the text box form field while signing the document. |
dateFormatstring | The date format of the form field. |
imageInfoobject | The information about the image field. ImageInfo properties are available here. |
attachmentInfoobject | The information about the attachment field. AttachmentInfo properties are available here. |
editableDateFieldSettingsobject | The settings for the editable date form field and it contains date format, min and max values. EditableDateFieldSettings properties are available here. |
hyperlinkTextstring | The text of the hyperlink form field. |
dataSyncTagstring | The value of the dataSync tag. |
dropdownOptionsarray | The options of the dropdown form field. |
Bound properties
Heading1 | Heading2 |
---|---|
xfloat | The form field's x coordinate value. |
yfloat | The form field's y coordinate value. |
widthfloat | The form field's width. |
heightfloat | The form field's height. |
ImageInfo properties
Heading1 | Heading2 |
---|---|
titlestring | The title of the image. |
descriptionstring | The description of the image. |
allowedFileExtensionsstring | This includes file extensions such as .jpg or .jpeg , .svg , .png , and .bmp . |
AttachmentInfo properties
Heading1 | Heading2 |
---|---|
titlestring | The title of the attachment. |
descriptionstring | The description of the attachment. |
allowedFileTypesstring | The file types that can be used are .pdf , .docx , .jpg , .jpeg , and .png . |
EditableDateField properties
Heading1 | Heading2 |
---|---|
dateFormatstring | The dateFormat of the editable date field. |
minDatestring | The min date of the editable date field. |
maxDatestring | The max date of the editable date field. |
DocumentInfo properties
Heading1 | Heading2 |
---|---|
languageinteger | The language of the document. The supported languages are 1-English , 2-Spanish , 3-German , 4-French , and 5-Romanian . |
titlestring | The title of the document. |
descriptionstring | The description of the document. |
TagDefinition properties
Heading1 | Heading2 |
---|---|
definitionIdstring | The definition id of the text tag. |
typestring | The type of the form field. |
signerIndexinteger | The signer index of the form field. |
isRequiredboolean | When disabled, the signer is not required to fill out the specific form field. The default value is true . |
placeholderstring | The placeholder of the form field. |
fieldIdstring | The field id of the form field. |
fontobject | The font of the form field. Font properties are available here. |
validationobject | When we select the type as TextBox , the validation of the form field is required. Validation properties are available here. |
sizeobject | This can be used to specify the form field's height and width. Size properties are available here. |
dateFormatstring | The dateformat of the form field. |
radioGroupNamestring | The form field's groupName, which is required when we set the type RadioButton . |
valuestring | The value of the form field. |
dropdownOptionsarray | The options of the dropdown form field. |
Font properties
Heading1 | Heading2 |
---|---|
namestring | The name of the font in form field. |
colorstring | The font color of the form field. |
sizeinteger | The font size of the form field. |
stylestring | The font style of the form field. |
lineHeightinteger | The lineheight of the form field. |
Validation properties
Heading1 | Heading2 |
---|---|
typestring | The validation type of the text box form field. The available values are None , NumbersOnly , EmailAddress , Currency , and CustomRegex . The default value is None . |
regexstring | The custom regex of the text box form field. When we set the ValidationType to CustomRegex , it will be required. |
Size properties
Heading1 | Heading2 |
---|---|
widthfloat | The width of the form field. |
heightfloat | The height of the form field. |
Example response
201 Created
{ "templateId": "4e2375dd-xxxx-xxxx-xxxx-870952cee6f8" }