Module: HelloSign::Api::Template

Included in:
Client
Defined in:
lib/hello_sign/api/template.rb

Overview

Contains all the API calls for the Template resource. Take a look at our API Documentation for Templates (app.hellosign.com/api/reference#Template) for more information about this.

Author:

  • hellosign

Instance Method Summary collapse

Instance Method Details

#add_user_to_template(opts) ⇒ HelloSign::Resource::Template

Gives the specified Account access to a Template. The Account must be part of your Team. Note: The account_id prevails if both email_address and acccount_id are provided.

Examples:

templates = @client.add_user_to_template template_id: 'f57db65d3f933b5316d398057a36176831451a35', email_address: '[email protected]'

Parameters:

  • opts (Hash) —

    a customizable set of options

Options Hash (opts):

  • template_id (String) —

    The Template ID to give access to.

  • account_id (String) —

    The Account ID to receive access to the Template.

  • email_address (String) —

    The email address of the Account to receive access to the Template.

Returns:



83
84
85
86
87
 
# File 'lib/hello_sign/api/template.rb', line 83

def add_user_to_template(opts)
  path = "/template/add_user/#{opts[:template_id]}"
  opts.delete(:template_id)
  HelloSign::Resource::Template.new post(path, body: opts)
end

#create_embedded_template_draft(opts) ⇒ HelloSign::Resource::Template

Creates a new Embedded Template draft object that can be launched in an iFrame using the claim_url.

Examples:

template_draft = @client.create_embedded_template_draft(
  test_mode: 1,
  subject: 'The NDA we talked about',
  requester_email_address: '[email protected]',
  message: 'Please sign this NDA and then we can discuss more. Let me know if you have any questions.',
  signer_roles: [
    {
      name: 'Manager',
      order: 0
    },
    {
      name: 'Client',
      order: 1
    }
  ],
  attachments: [{
    name: 'Passport',
    instructions: 'Upload your US Passport',
    signer_index: 0,
    required: true
    },
    {
    name: 'Driver's License',
    instructions: 'Upload your CA Driver's License',
    signer_index: 1,
    required: false
    }
  ],
  cc_roles: ['HRManager'],
  files: ['NDA.pdf', 'AppendixA.pdf'],
  merge_fields: '[
    {
      name: 'contract_id',
      type: 'text'
    },
    {
      name: 'purchase_price',
      order: 'text'
    }
  ]'
)

Parameters:

  • opts (Hash) —

    a customizable set of options

Options Hash (opts):

  • test_mode (Boolean) —

    Indicates if this is a test Template draft. SignatureRequests using this Template will not be legally binding if set to 1. Defaults to 0. (optional)

  • client_id (String) —

    The API App Client ID associated with the Template draft. (optional)

  • files (Array<String>) —

    Specified file path(s) to upload file(s) to send for signature. Currently we only support use of either the files parameter or file_urls parameter, not both.

  • file_urls (Array<String>) —

    URL(s) for HelloSign to download the file(s) to send for signature. Currently we only support use of either the files parameter or file_urls parameter, not both.

  • title (String) —

    The default Template title. (optional)

  • subject (String) —

    The default Template title alias. (optional)

  • message (String) —

    The default message in the email that will be sent to the signer(s). (optional)

  • signers (Array<Hash>) —

    List of signers displayed when the Template is used to create a SignatureRequest

    • name (String) Signer role name

    • order (Integer) The order the signer role is required to sign in. (optional)

  • attachments (Array<Hash>) —

    Sets a list of attachments signers can upload

    • name (String) Attachment name

    • instructions (String) Instructions for uploading the attachment. (optional)

    • signer_index (Integer) The signer’s unique number.

    • required (Boolean) Determines if the signer is required to upload this attachment. Defaults to 0. (Optional)

  • cc_roles (Array<Hash>) —

    The CC roles that must be assigned when using the Template to create a SignatureRequest. (optional)

  • merge_fields (String<Array><Hash>) —

    List of fields that can be pre-populated by your application when using the Template to send a SignatureRequest. (optional)

    • name (String) Merge field name

    • type (String) Field type - either “text” or “checkbox”

  • skip_me_now (Boolean) —

    Sets the “Me (Now)” option for the Template preparer. Defaults to 0. (optional)

  • use_preexisting_fields (Boolean) —

    Sets the detection of predefined PDF fields. Defaults to 0. (optional)

  • metadata (Hash) —

    Key-value data attached to the Template and all SignatureRequests created from the Template. (optional)

  • allow_reassign (Boolean) —

    Sets the ability for signers to reassign the SignatureRequest to other signers. Defaults to 0. (optional)

Returns:



174
175
176
177
178
179
180
181
 
# File 'lib/hello_sign/api/template.rb', line 174

def create_embedded_template_draft(opts)
  opts[:client_id] ||= self.client_id
  prepare_files opts
  prepare_signer_roles opts
  prepare_attachments opts
  prepare_merge_fields opts
  HelloSign::Resource::TemplateDraft.new post("/template/create_embedded_draft", body: opts)
end

#delete_template(opts) ⇒ HTTP::Status

Deletes the specified Template.

Examples:

template = @client.delete_template template_id: 'f57db65d3f933b5316d398057a36176831451a35'

Parameters:

  • opts (Hash) —

    a customizable set of options

Options Hash (opts):

  • template_id (String) —

    The ID of the Template to delete.

Returns:

  • (HTTP::Status) —

    200 OK



51
52
53
 
# File 'lib/hello_sign/api/template.rb', line 51

def delete_template(opts)
  post("/template/delete/#{opts[:template_id]}")
end

#get_template(opts) ⇒ HelloSign::Resource::Template

Retrieves the Template with the given ID.

Examples:

template = @client.get_template template_id: 'f57db65d3f933b5316d398057a36176831451a35'

Parameters:

  • opts (Hash) —

    a customizable set of options

Options Hash (opts):

  • template_id (String) —

    The ID of the Template to retrieve.

Returns:



40
41
42
 
# File 'lib/hello_sign/api/template.rb', line 40

def get_template(opts)
  HelloSign::Resource::Template.new get("/template/#{opts[:template_id]}")
end

#get_template_files(opts) ⇒ Object

Downloads the original files of a specified Template.

Examples:

file = @client.get_template_files template_id: 'f57db65d3f933b5316d398057a36176831451a35', file_type: 'zip'

Parameters:

  • opts (Hash) —

    a customizable set of options

Options Hash (opts):

  • template_id (String) —

    The Template ID to retrieve.

  • file_type (String) —

    Determines the format of the file - either ‘pdf’ or ‘zip’ depending on the file type desired. Defaults to pdf. (optional)

  • get_url (Boolean) —

    Response contains a URL link to the file if set to true. Links are only available for PDFs and have a TTL of 3 days. Defaults to false. (optional)

Returns:

  • a PDF or Zip



192
193
194
195
196
197
198
199
200
201
202
203
 
# File 'lib/hello_sign/api/template.rb', line 192

def get_template_files(opts)
  path = "/template/files/#{opts[:template_id]}"
  if opts[:file_type]
    path = path + "?file_type=#{opts[:file_type]}"
  end
  if opts[:get_url]
    separator = opts[:file_type].nil? ? '?' : '&'
    path = path + "#{separator}get_url=#{opts[:get_url]}"
  end

  get(path)
end

#get_templates(opts = {}) ⇒ HelloSign::Resource::ResourceArray

Retrieves the Templates for the accessible by the current user.

Examples:

templates = @client.get_templates page: 1

Parameters:

  • opts (Hash) (defaults to: {}) —

    a customizable set of options

Options Hash (opts):

  • account_id (String) —

    The Account ID to return Templates for. Use “all” for all team members. Defaults to current account. (optional)

  • page (Integer) —

    Sets the page number of the list to return. Defaults to 1. (optional)

  • page_size (Integer) —

    Determines the number of Templates returned per page. Defaults to 20. (optional)

  • query (String) —

    Search terms and/or fields to filter the Templates. (optional)

Returns:



65
66
67
68
69
70
71
 
# File 'lib/hello_sign/api/template.rb', line 65

def get_templates(opts={})
  path = '/template/list'
  opts[:query] = create_search_string(opts[:query]) if opts[:query]
  query = create_query_string(opts, [:page, :page_size, :query])
  path += query
  HelloSign::Resource::ResourceArray.new get(path, opts), 'templates', HelloSign::Resource::Template
end

#remove_user_from_template(opts) ⇒ HelloSign::Resource::Template

Removes the specified Account access to the specified Template. Note: The account_id prevails if both email_address and acccount_id are provided.

Examples:

templates = @client.remove_user_from_template template_id: 'f57db65d3f933b5316d398057a36176831451a35', email_address: '[email protected]'

Parameters:

  • opts (Hash) —

    a customizable set of options

Options Hash (opts):

  • template_id (String) —

    The Template ID to remove access to.

  • account_id (String) —

    The Account ID to remove access to the Template.

  • email_address (String) —

    The email address of the Account to remove access to the Template.

Returns:



99
100
101
102
103
 
# File 'lib/hello_sign/api/template.rb', line 99

def remove_user_from_template(opts)
  path = "/template/remove_user/#{opts[:template_id]}"
  opts.delete(:template_id)
  HelloSign::Resource::Template.new post(path, body: opts)
end

#update_template_files(opts) ⇒ Object

Overlays a new file with the overlay of the specified Template.

Examples:

templates = @client.update_template_files template_id: 'f57db65d3f933b5316d398057a36176831451a35', file: '@NDA.pdf'

Parameters:

  • opts (Hash) —

    a customizable set of options

Options Hash (opts):

  • template_id (String) —

    The Template ID to update.

  • files (Array<String>) —

    Specified file path(s) to upload file(s) to send for signature. Currently we only support use of either the files parameter or file_urls parameter, not both.

  • file_urls (Array<String>) —

    URL(s) for HelloSign to download the file(s) to send for signature. Currently we only support use of either the files parameter or file_urls parameter, not both.

  • subject (String) —

    The updated default Template title alias. (optional)

  • message (String) —

    The updated default message in the email that will be sent to the signer(s). (optional)

  • client_id (String) —

    The API App Client ID associated with the Template. (optional)

  • test_mode (Boolean) —

    Indicates if this is a test Template. SignatureRequests using this Template will not be legally binding if set to 1. Defaults to 0. (optional)

Returns:

  • a Template ID



219
220
221
222
223
224
225
 
# File 'lib/hello_sign/api/template.rb', line 219

def update_template_files(opts)
  template_id = opts.delete(:template_id)
  path = "/template/update_files/#{template_id}"
  prepare_files opts

  HelloSign::Resource::Template.new post(path, body: opts)
end