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.



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

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

    sets the version of the signer page to use

Returns:



296
297
298
299
300
301
302
 
# File 'lib/hello_sign/api/signature_request.rb', line 296

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.

  • ux_version (Integer) —

    sets the version of the signer page to use

Returns:



356
357
358
359
360
361
362
363
 
# File 'lib/hello_sign/api/signature_request.rb', line 356

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.

  • 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 (Hash) (defaults to: {}) —

    a customizable set of options

Options Hash (opts):

  • page (Integer) — default: 1 —

    Which page number of the Template List to return.

  • ux_version (Integer) —

    sets the version of the signer page to use

Returns:



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

def get_signature_requests(opts={})
  path = '/signature_request/list'
  query = create_query_string(opts, [:page, :page_size, :ux_version])
  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:



217
218
219
 
# File 'lib/hello_sign/api/signature_request.rb', line 217

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:



117
118
119
120
121
122
 
# File 'lib/hello_sign/api/signature_request.rb', line 117

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.

  • ux_version (Integer) —

    sets the version of the signer page to use

Returns:



199
200
201
202
203
204
205
 
# File 'lib/hello_sign/api/signature_request.rb', line 199

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



241
242
243
244
245
246
247
 
# File 'lib/hello_sign/api/signature_request.rb', line 241

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