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.



238
239
240
 
# File 'lib/hello_sign/api/signature_request.rb', line 238

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,
  :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 (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)
  • ux_version (Integer) —

    sets the version of the signer page to use

Returns:



323
324
325
326
327
328
329
330
 
# File 'lib/hello_sign/api/signature_request.rb', line 323

def create_embedded_signature_request(opts)
  opts[:client_id] ||= self.client_id
  prepare_files opts
  prepare_signers opts
  prepare_form_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 (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) — default: deprecated —

    The value to fill in for custom field with the name of CustomFieldName.

  • custom_fields (Array<Hash>) —

    An array of custom merge fields, representing those present in the template. Only specify this when NOT specifying custom_fields by hash (the old way)

  • ux_version (Integer) —

    sets the version of the signer page to use

Returns:



387
388
389
390
391
392
393
394
395
396
 
# File 'lib/hello_sign/api/signature_request.rb', line 387

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.

  • ux_version (Integer) —

    sets the version of the signer page to use

Returns:



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

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 CCed on.

Examples:

signature_requests = @client.get_signature_requests :page => 1

Parameters:

  • opts[:page] (Hash) —

    a customizable set of options

  • opts[:ux_version] (Hash) —

    a customizable set of options

  • opts[:query] (Hash) —

    a customizable set of options

Returns:



65
66
67
68
69
70
71
72
 
# 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) —

    The id of the SignatureRequest to send a reminder for.

  • email_address (String) —

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

  • ux_version (Integer) —

    sets the version of the signer page to use

Returns:



228
229
230
 
# File 'lib/hello_sign/api/signature_request.rb', line 228

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 SignatureRequest to remove.



248
249
250
 
# File 'lib/hello_sign/api/signature_request.rb', line 248

def remove_signature_request(opts)
  post("/signature_request/remove/#{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,
  :allow_decline => 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:



121
122
123
124
125
126
127
 
# File 'lib/hello_sign/api/signature_request.rb', line 121

def send_signature_request(opts)
  prepare_files opts
  prepare_signers opts
  prepare_form_fields 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,
  :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 (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 (Hash) — default: deprecated —

    The value to fill in for the custom field with the name of CustomFieldName.

  • custom_fields (Array<Hash>) —

    An array of custom merge fields, representing those present in the template. Only specify this when NOT specifying custom_fields by hash (the old way).

  • ux_version (Integer) —

    sets the version of the signer page to use

Returns:



208
209
210
211
212
213
214
215
216
 
# File 'lib/hello_sign/api/signature_request.rb', line 208

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

  • get_url (String) —

    Boolean. If true, the response will contain a url link to the file instead. Links are only available for PDFs and have a TTL of 3 days.Either ‘pdf’ or ‘zip’ depending on the file type desired. Defaults to false.

  • signature_request_id (String) —

    The id of the SignatureRequest to retrieve.

Returns:

  • a PDF



263
264
265
266
267
268
269
270
271
272
273
 
# File 'lib/hello_sign/api/signature_request.rb', line 263

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)
end

#update_signature_request(opts) ⇒ Object 



398
399
400
401
402
 
# File 'lib/hello_sign/api/signature_request.rb', line 398

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