Module: HelloSign::Api::SignatureRequest

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

Overview

Contains all the api about the SignatureRequest resource. Take a look at our signature request api document 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 SignatureRequest to cancel.



220
221
222
 
# File 'lib/hello_sign/api/signature_request.rb', line 220

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, a signature page will be affixed where all signers will be required to add their signature, signifying their agreement to all contained documents. 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(
  :test_mode => 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 (Integer) — default: 0 —

    Whether this is a test, the signature request will not be legally binding if set to 1.

  • client_id (String) —

    Client id of the app you’re using to create this embedded signature request. Visit our embedded page page to learn more about this parameter.

  • 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.

  • subject (String) —

    The subject in the email that will be sent to the signers.

  • message (String) —

    The custom message in the email that will be sent to the signers.

  • signing_redirect_url (String) —

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

  • signers (Array<Hash>) —

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

    • :name (String) Sender’ name

    • :email_address (String) Sender’s email address

    • :order (Integer) The order the signer is required to sign in

    • :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.

  • cc_email_addresses (Array<String>) —

    The email addresses that should be CCed.

  • form_fields_per_document (String)

Returns:



288
289
290
291
292
293
294
 
# File 'lib/hello_sign/api/signature_request.rb', line 288

def create_embedded_signature_request(opts)
  opts[:client_id] ||= self.client_id
  prepare_files opts
  prepare_signers 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,
  :client_id => 'b6b8e7deaf8f0b95c029dca049356d4a2cf9710a',
  :template_id => 'c26b8a16784a872da37ea946b9ddec7c1e11dff6',
  :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'
    }
  ],
  :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 (Integer) — default: 0 —

    Whether this is a test, the signature request will not be legally binding if set to 1.

  • client_id (String) —

    Client id of the app you’re using to create this embedded signature request. Visit our embedded page page to learn more about this parameter.

  • template_id (String) —

    The id of the Template to use when creating the SignatureRequest.

  • title (String) —

    The title you want to assign to the SignatureRequest.

  • subject (String) —

    The subject in the email that will be sent to the signers.

  • message (String) —

    The custom message in the email that will be sent to the signers.

  • signing_redirect_url (String) —

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

  • hide_text_tags (Integer) —

    Whether or not your text tags hidden after parsing

  • use_text_tags (Integer) —

    Whether or not your document contains parseable text-tags

  • signers (Array<Hash>) —

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

    • :name (String) Sender’ name

    • :email_address (String) Sender’s email address

    • :order (Integer) The order the signer is required to sign in

    • :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.

  • ccs (Hash) —

    The email address of the CC filling the role of RoleName. Required when a CC role exists for the Template.

  • custom_fields (Hash) —

    The value to fill in for custom field with the name of CustomFieldName. Required when a CustomField exists in the Template.

Returns:



346
347
348
349
350
351
352
353
 
# File 'lib/hello_sign/api/signature_request.rb', line 346

def create_embedded_signature_request_with_template(opts)
  opts[:client_id] ||= self.client_id
  prepare_signers opts
  prepare_ccs opts
  prepare_templates 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
 
# File 'lib/hello_sign/api/signature_request.rb', line 46

def get_signature_request(opts)
  HelloSign::Resource::SignatureRequest.new get("/signature_request/#{opts[:signature_request_id]}")
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 CCed on.

Examples:

signature_requests = @client.get_signature_requests :page => 1

Parameters:

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

    a customizable set of options

Options Hash (opts):

  • page (Integer) — default: 1 —

    Which page number of the Template List to return.

Returns:



59
60
61
62
63
64
 
# File 'lib/hello_sign/api/signature_request.rb', line 59

def get_signature_requests(opts={})
  path = '/signature_request/list'
  path += opts[:page] ? "?page=#{opts[:page]}" : ''
  path += opts[:page_size] ? "&page_size=#{opts[:page_size]}" : ''
  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) —

    The id of the SignatureRequest to send a reminder for.

  • email_address (String) —

    The email address of the signer to send a reminder to.

Returns:



210
211
212
 
# File 'lib/hello_sign/api/signature_request.rb', line 210

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

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

Creates and sends a new SignatureRequest with the submitted documents. If form_fields_per_document is not specified, a signature page will be affixed at the end and all signers will be required to add their signature there.

Examples:

signature_request = @client.send_signature_request(
  :test_mode => 1,
  :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 (Integer) — default: 0 —

    Whether this is a test, the signature request will not be legally binding if set to 1.

  • 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.

  • subject (String) —

    The subject in the email that will be sent to the signers.

  • message (String) —

    The custom message in the email that will be sent to the signers.

  • signing_redirect_url (String) —

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

  • signers (Array<Hash>) —

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

    • :name (String) Sender’ name

    • :email_address (String) Sender’s email address

    • :order (Integer) The order the signer is required to sign in

    • :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.

  • cc_email_addresses (Array<String>) —

    The email addresses that should be CCed.

  • form_fields_per_document (String)

Returns:



112
113
114
115
116
117
 
# File 'lib/hello_sign/api/signature_request.rb', line 112

def send_signature_request(opts)
  prepare_files opts
  prepare_signers opts

  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,
  :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,
  :template_id => 'c26b8a16784a872da37ea946b9ddec7c1e11dff6',
  :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'
    }
  ],
  :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 (Integer) — default: 0 —

    Whether this is a test, the signature request will not be legally binding if set to 1.

  • template_id (String) —

    The id of the Template to use when creating the SignatureRequest.

  • title (String) —

    The title you want to assign to the SignatureRequest.

  • subject (String) —

    The subject in the email that will be sent to the signers.

  • message (String) —

    The custom message in the email that will be sent to the signers.

  • signing_redirect_url (String) —

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

  • signers (Array<Hash>) —

    List of signers

    • :name (String) Sender’ name

    • :email_address (String) Sender’s email address

    • :order (Integer) The order the signer is required to sign in

    • :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.

  • ccs (Array<Hash>) —

    The email addresses CC destinations. Required when a CC role exists for the Template.

  • custom_fields (Array<Hash>) —

    The value to fill in for the custom field with the name of CustomFieldName. Required when a CustomField exists in the Template.

Returns:



193
194
195
196
197
198
199
 
# File 'lib/hello_sign/api/signature_request.rb', line 193

def send_signature_request_with_template(opts)
  prepare_signers opts
  prepare_ccs opts
  prepare_templates opts

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

#signature_request_files(opts) ⇒ Object

Download the PDF copy of the current 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):

  • file_type (String) —

    Either ‘pdf’ or ‘zip’ depending on the file type desired. Defaults to pdf.

  • signature_request_id (String) —

    The id of the SignatureRequest to retrieve.

Returns:

  • a PDF



234
235
236
237
238
239
240
 
# File 'lib/hello_sign/api/signature_request.rb', line 234

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
  get(path)
end