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.



230
231
232
 
# File 'lib/hello_sign/api/signature_request.rb', line 230

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:



299
300
301
302
303
304
305
 
# File 'lib/hello_sign/api/signature_request.rb', line 299

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:



359
360
361
362
363
364
365
366
367
 
# File 'lib/hello_sign/api/signature_request.rb', line 359

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

  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
 
# 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])
  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:



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

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:



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

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:



201
202
203
204
205
206
207
208
 
# File 'lib/hello_sign/api/signature_request.rb', line 201

def send_signature_request_with_template(opts)
  prepare_signers opts
  prepare_ccs opts
  prepare_templates opts
  prepare_custom_fields 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



244
245
246
247
248
249
250
 
# File 'lib/hello_sign/api/signature_request.rb', line 244

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