Module: HelloSign::Api::SignatureRequest

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

Overview

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

Author:

  • hellosign

Instance Method Summary collapse

Instance Method Details

#cancel_signature_request(opts) ⇒ Object

Cancels a SignatureRequest.

Examples:

@client.cancel_signature_request :signature_request_id => '75cdf7dc8b323d43b347e4a3614d1f822bd09491'

Parameters:

  • opts (Hash) —

    a customizable set of options

Options Hash (opts):

  • signature_request_id (String) —

    The ID of the incomplete SignatureRequest to cancel.



282
283
284
 
# File 'lib/hello_sign/api/signature_request.rb', line 282

def cancel_signature_request(opts)
  post("/signature_request/cancel/#{opts[:signature_request_id]}", :body => opts)
end

#create_embedded_signature_request(opts) ⇒ HelloSign::Resource::SignatureRequest

Creates a new SignatureRequest with the submitted documents to be signed in an embedded iFrame. If form_fields_per_document is not specified or use_text_tags is not enabled, a signature page will be affixed at the end and all signers will be required to add their signature there. Note that embedded signature requests can only be signed in embedded iFrames whereas normal signature requests can only be signed on HelloSign.com. See our Embedded Signing Walkthrough for more information on Embedded Signing: app.hellosign.com/api/embeddedSigningWalkthrough

Examples:

request = @client.create_embedded_signature_request(
  :test_mode => 1,
  :allow_decline => 1,
  :client_id => 'b6b8e7deaf8f0b95c029dca049356d4a2cf9710a',
  :title => 'NDA with Acme Co.',
  :subject => 'The NDA we talked about',
  :message => 'Please sign this NDA and then we can discuss more. Let me know if you have any questions.',
  :metadata => {
   :client_id => '1234',
   :custom_text => 'NDA #9'
  },
  :signers => [{
      :email_address => '[email protected]',
      :name => 'Jack',
      :order => 0,
    },{
      :email_address => '[email protected]',
      :name => 'Jill',
      :order => 1,
    }
  ],
  :cc_email_addresses => ['[email protected]', '[email protected]'],
  :files => ['NDA.pdf', 'AppendixA.pdf']
)

Parameters:

  • opts (Hash) —

    a customizable set of options

Options Hash (opts):

  • test_mode (Boolean) —

    Indicates if this is a test SignatureRequest, it will not be legally binding if set to 1. A boolean value is also accepted. Defaults to 0. (optional)

  • client_id (String) —

    The API App Client ID associated with the this embedded SignatureRequest.

  • files (Array<String>) —

    Use files to indicate the uploaded 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>) —

    Use file_urls to have HelloSign 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 title you want to assign to the SignatureRequest. (optional)

  • subject (String) —

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

  • message (String) —

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

  • signers (Array<Hash>) —

    List of signers, each item is a Hash with these keys:

    • :name (String) Signer’s name

    • :email_address (String) Signer’s email address

    • :order (Integer) The order the signers are required to sign in (optional)

    • :pin (Integer) The 4- to 12-character access code that will secure this signer’s signature page. You must have a business plan to use this feature. (optional)

  • custom_fields (Array<Hash>) —

    An array of custom merge fields, representing those present on the document with Text Tags or form_fields_per_document (optional)

    • :name (String) Custom field name or “Field Label”

    • :value (String) The value of the field. This data will appear on the SignatureRequest

    • :editor (String) The signer name indicated on the Text Tag or form_fields_per_document that can edit the value of the field. (optional)

    • :required (Boolean) Determines if the field is required or not. (optional)

  • cc_email_addresses (Array<String>) —

    The email addresses that should be CCed on the SignatureRequest. (optional)

  • use_text_tags (Boolean) —

    Indicates whether the SignatureRequest should have Text Tags enabled. Defaults to 0. (optional)

  • hide_text_tags (Boolean) —

    Indicates whether the Text Tags should be removed automatically. Note that this is not the preferred method. Defaults to 0. (optional)

  • metadata (Hash) —

    Key-value data attached to the SignatureRequest. (optional)

  • allow_decline (Boolean) —

    Allows signers to decline the SignatureRequest. Defaults to 0. (optional)

  • allow_reassign (Boolean) —

    Allows signers to reassign the SignatureRequest to another signer. Defaults to 0. (optional)

  • form_fields_per_document (Array<Hash>) —

    The fields that should appear on the document. (optional)

Returns:



378
379
380
381
382
383
384
385
386
 
# File 'lib/hello_sign/api/signature_request.rb', line 378

def create_embedded_signature_request(opts)
  opts[:client_id] ||= self.client_id
  prepare_files opts
  prepare_signers opts
  prepare_form_fields opts
  prepare_custom_fields opts

  HelloSign::Resource::SignatureRequest.new post('/signature_request/create_embedded', :body => opts)
end

#create_embedded_signature_request_with_template(opts) ⇒ HelloSign::Resource::SignatureRequest

Creates a new SignatureRequest based on the given Template to be signed in an embedded iFrame. Note that embedded signature requests can only be signed in embedded iFrames whereas normal signature requests can only be signed on HelloSign.

Examples:

request = @client.create_embedded_signature_request_with_template(
  :test_mode => 1,
  :allow_decline => 1,
  :client_id => 'b6b8e7deaf8f0b95c029dca049356d4a2cf9710a',
  :template_id => 'c26b8a16784a872da37ea946b9ddec7c1e11dff6',
  :title => 'Purchase Order',
  :subject => 'Purchase Order',
  :message => 'Glad we could come to an agreement.',
  :files => ['NDA.pdf', 'AppendixA.pdf'],
  :metadata => {
   :client_id => '1234',
   :custom_text => 'NDA #9'
  },
  :signers => [
    {
      :email_address => '[email protected]',
      :name => 'George',
      :role => 'Client'
    }
  ],
  :ccs => [
    {
      :email_address =>'[email protected]',
      :role => "Accounting"
    }
  ],
  :custom_fields => {
    :Cost => '$20,000'
  }
)

Parameters:

  • opts (Hash) —

    a customizable set of options

Options Hash (opts):

  • test_mode (Boolean) —

    Indicates if this is a test SignatureRequest, it will not be legally binding if set to 1. A boolean value is also accepted. Defaults to 0. (optional)

  • client_id (String) —

    The API App Client ID associated with the this embedded SignatureRequest.

  • template_id (String) —

    The Template ID to use when creating the SignatureRequest.

    • Use template_ids if using multiple templates, replacing %i% with an integer to indicate the order of the Templates

  • title (String) —

    The title you want to assign to the SignatureRequest. (optional)

  • subject (String) —

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

  • message (String) —

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

  • signers (Array<Hash>) —

    List of signers

    • :role (String) The signer role indicated on the Template. Note that the role name is case sensitive.

    • :name (String) Signer’s name

    • :email_address (String) Signer’s email address

    • :pin (Integer) The 4- to 12-character access code that will secure this signer’s signature page. You must have a business plan to use this feature. (optional)

  • ccs (Array<Hash>) —

    The individual(s) to be CC’d on the SignatureRequest. Required when a CC role exists for the Template.

    • :role (String) The CC role indicated on the Template. Note that the role name is case sensitive.

    • :email_address (String) CC Recipient’s email address

  • custom_fields (Array<Hash>) —

    An array of custom merge fields, representing those present in the Template. (optional)

    • :name (String) Custom field name or “Field Label”

    • :value (String) The value of the field. This data will appear on the SignatureRequest.

    • :editor (String) The signer name indicated on the Text Tag or form_fields_per_document that can edit the value of the field. (optional)

    • :required (Boolean) Determines if the field is required or not. (optional)

  • metadata (Hash) —

    Key-value data attached to the SignatureRequest. (optional)

  • files (Array<String>) —

    Use files to indicate the uploaded file(s) to append to the SignatureRequest. (optional)

  • file_urls (Array<String>) —

    Use file_urls to have HelloSign download the file(s) to append to the SignatureRequest. (optional)

Returns:



448
449
450
451
452
453
454
455
456
457
 
# File 'lib/hello_sign/api/signature_request.rb', line 448

def create_embedded_signature_request_with_template(opts)
  opts[:client_id] ||= self.client_id
  prepare_signers opts
  prepare_ccs opts
  prepare_templates opts
  prepare_custom_fields opts
  prepare_files opts

  HelloSign::Resource::SignatureRequest.new post('/signature_request/create_embedded_with_template', :body => opts)
end

#get_signature_request(opts) ⇒ HelloSign::Resource::SignatureRequest

Retrieves a Signature Request with the given ID.

Examples:

signature_request = @client.get_signature_request :signature_request_id => 'fa5c8a0b0f492d768749333ad6fcc214c111e967'

Parameters:

  • opts (Hash) —

    a customizable set of options

Options Hash (opts):

  • signature_request_id (String) —

    The id of the SignatureRequest to retrieve.

Returns:



46
47
48
49
50
51
 
# File 'lib/hello_sign/api/signature_request.rb', line 46

def get_signature_request(opts)
    path = "/signature_request/#{opts[:signature_request_id]}"
    query = create_query_string(opts, [:ux_version])
    path += query
  HelloSign::Resource::SignatureRequest.new get(path)
end

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

Returns a list of SignatureRequests that you can access. This includes SignatureRequests you have sent as well as received, but not ones that you have been CC’d on.

Examples:

signature_requests = @client.get_signature_requests :page => 1

Parameters:

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

    a customizable set of options

Options Hash (opts):

  • account_id (String) —

    Indicates which account to return SignatureRequests for. Defaults to your account. (optional)

  • page (Integer) —

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

  • page_size (Integer) —

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

  • query (String) —

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

Returns:



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

def get_signature_requests(opts={})
  path = '/signature_request/list'
  opts[:query] = create_search_string(opts[:query]) if opts[:query]
  query = create_query_string(opts, [:page, :page_size, :ux_version, :query])
  path += query
  HelloSign::Resource::ResourceArray.new get(path, opts), 'signature_requests', HelloSign::Resource::SignatureRequest
end

#remind_signature_request(opts) ⇒ HelloSign::Resource::SignatureRequest

Sends an email to the signer reminding them to sign the signature request.

Examples:

signature_request = @client.remind_signature_request :signature_request_id => '75cdf7dc8b323d43b347e4a3614d1f822bd09491', :email_address => '[email protected]'

Parameters:

  • opts (Hash) —

    a customizable set of options

Options Hash (opts):

  • signature_request_id (String) —

    Indicates the ID of the SignatureRequest to send a reminder.

  • email_address (String) —

    The email address of the signer who will receive a reminder.

  • name (String) —

    The name of the signer who will receive a reminder. (optional)

Returns:



272
273
274
 
# File 'lib/hello_sign/api/signature_request.rb', line 272

def remind_signature_request(opts)
  HelloSign::Resource::SignatureRequest.new post("/signature_request/remind/#{opts[:signature_request_id]}", :body => opts)
end

#remove_signature_request(opts) ⇒ Object

Removes your access to a completed a SignatureRequest.

Examples:

@client.remove_signature_request :signature_request_id => '75cdf7dc8b323d43b347e4a3614d1f822bd09491'

Parameters:

  • opts (Hash) —

    a customizable set of options

Options Hash (opts):

  • signature_request_id (String) —

    The ID of the completed SignatureRequest to remove access.



292
293
294
 
# File 'lib/hello_sign/api/signature_request.rb', line 292

def remove_signature_request(opts)
  post("/signature_request/remove/#{opts[:signature_request_id]}", :body => opts)
end

#send_signature_request(opts) ⇒ Object

)



155
156
157
158
159
160
161
162
 
# File 'lib/hello_sign/api/signature_request.rb', line 155

def send_signature_request(opts)
  prepare_files opts
  prepare_signers opts
  prepare_form_fields opts
  prepare_custom_fields opts

  request = HelloSign::Resource::SignatureRequest.new post('/signature_request/send', :body => opts)
end

#send_signature_request_with_template(opts) ⇒ HelloSign::Resource::SignatureRequest

Creates and sends a new SignatureRequest based off of the Template specified with the template_id parameter.

Examples:

signature_request = @client.send_signature_request_with_template(
  :test_mode => 1,
  :allow_decline => 1,
  :template_ids => [
             'c26b8a16784a872da37ea946b9ddec7c1e11dff6',
             'c7ab48e9a9ee7102dd6229dbbc719abc7d90ff9f'
  ],
  :title => 'Purchase Order',
  :subject => 'Purchase Order',
  :message => 'Glad we could come to an agreement.',
  :metadata => {
    :client_id => '1234',
    :custom_text => 'NDA #9'
   },
  :signers => [
    {
      :email_address => '[email protected]',
      :name => 'George',
      :role => 'Client'
    },
    {
      :email_address => '[email protected]',
      :name => 'Mary',
      :role => 'Manager'
    }
  ]
)
signature_request = @client.send_signature_request_with_template(
  :test_mode => 1,
  :allow_decline => 0,
  :template_id => 'c26b8a16784a872da37ea946b9ddec7c1e11dff6',
  :title => 'Purchase Order',
  :subject => 'Purchase Order',
  :message => 'Glad we could come to an agreement.',
  :files => ['NDA.pdf', 'AppendixA.pdf'],
  :metadata => {
    :client_id => '1234',
    :custom_text => 'NDA #9'
   },
  :signers => [
    {
      :email_address => '[email protected]',
      :name => 'George',
      :role => 'Client'
    }
  ],
  :ccs => [
    {
      :email_address =>'[email protected]',
      :role => "Accounting"
    }
  ],
  :custom_fields => [
   {
     :CustomFieldName => '$20,000'
   }
 ]
)

Parameters:

  • opts (Hash) —

    a customizable set of options

Options Hash (opts):

  • test_mode (Boolean) —

    Indicates if this is a test SignatureRequest, it will not be legally binding if set to 1. A boolean value is also accepted. Defaults to 0. (optional)

  • template_id (String) —

    The Template ID to use when creating the SignatureRequest.

    • Use template_ids if using multiple templates, replacing %i% with an integer to indicate the order of the Templates

  • title (String) —

    The title you want to assign to the SignatureRequest. (optional)

  • subject (String) —

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

  • message (String) —

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

  • signing_redirect_url (String) —

    The URL you want the signer(s) redirected to after they successfully sign. (optional)

  • signers (Array<Hash>) —

    List of signers

    • :role (String) The signer role indicated on the Template. Note that the role name is case sensitive.

    • :name (String) Signer’s name

    • :email_address (String) Signer’s email address

    • :pin (Integer) The 4- to 12-character access code that will secure this signer’s signature page. You must have a business plan to use this feature. (optional)

  • ccs (Array<Hash>) —

    The individual(s) to be CC’d on the SignatureRequest. Required when a CC role exists for the Template.

    • :role (String) The CC role indicated on the Template. Note that the role name is case sensitive.

    • :email_address (String) CC Recipient’s email address

  • custom_fields (Array<Hash>) —

    An array of custom merge fields, representing those present in the Template. (optional)

    • :name (String) Custom field name or “Field Label”

    • :value (String) The value of the field. This data will appear on the SignatureRequest.

    • :editor (String) The signer name indicated on the Text Tag or form_fields_per_document that can edit the value of the field. (optional)

    • :required (Boolean) Determines if the field is required or not. (optional)

  • metadata (Hash) —

    Key-value data attached to the SignatureRequest. (optional)

  • client_id (String) —

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

  • files (Array<String>) —

    Use files to indicate the uploaded file(s) to append to the SignatureRequest. (optional)

  • file_urls (Array<String>) —

    Use file_urls to have HelloSign download the file(s) to append to the SignatureRequest. (optional)

Returns:



252
253
254
255
256
257
258
259
260
 
# File 'lib/hello_sign/api/signature_request.rb', line 252

def send_signature_request_with_template(opts)
  prepare_signers opts
  prepare_ccs opts
  prepare_templates opts
  prepare_custom_fields opts
  prepare_files opts

  HelloSign::Resource::SignatureRequest.new post('/signature_request/send_with_template', :body => opts)
end

#signature_request_files(opts) ⇒ Object

Download a copy of the SignatureRequest documents specified by the signature_request_id parameter.

Examples:

pdf = @client.signature_request_files :signature_request_id => '75cdf7dc8b323d43b347e4a3614d1f822bd09491'

Parameters:

  • opts (Hash) —

    a customizable set of options

Options Hash (opts):

  • signature_request_id (String) —

    The ID of the SignatureRequest to download.

  • 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



307
308
309
310
311
312
313
314
315
316
317
318
 
# File 'lib/hello_sign/api/signature_request.rb', line 307

def signature_request_files(opts)
  path = "/signature_request/files/#{opts[:signature_request_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)[:body]
end

#update_signature_request(opts) ⇒ Object

Updates the email address on a SignatureRequest.

Examples:

@client.update_signature_request(
:signature_request_id => '75cdf7dc8b323d43b347e4a3614d1f822bd09491',
:signature_id => '5064ca698bde9581ad75f6d62450eb4b',
:email_address => '[email protected]'
)

Parameters:

  • opts (Hash) —

    a customizable set of options

Options Hash (opts):

  • signature_request_id (String) —

    The ID of the SignatureRequest to update.

  • signature_id (String) —

    The Signature ID of the recipient to update.

  • email_address (String) —

    The new email address of the recipient.



472
473
474
475
476
 
# File 'lib/hello_sign/api/signature_request.rb', line 472

def update_signature_request(opts)
  signature_request_id = opts.delete(:signature_request_id)
  path = "/signature_request/update/#{signature_request_id}"
  HelloSign::Resource::SignatureRequest.new post(path, :body => opts)
end