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.

Instance Method Summary collapse

Instance Method Details

#cancel_signature_request(opts) ⇒ Object

Cancels a SignatureRequest.

Examples:

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

Options Hash (opts):

  • signature_request_id (String) —

    The id of the SignatureRequest to cancel.

Parameters:

  • a customizable set of options



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

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']
)

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.

  • custom_fields (Array<Hash>) —

    An array of custom merge fields, representing those present on the document with Text Tags.

  • form_fields_per_document (String)
  • ux_version (Integer) —

    sets the version of the signer page to use

Parameters:

  • a customizable set of options

Returns:

  • a SignatureRequest



325
326
327
328
329
330
331
332
333
 
# File 'lib/hello_sign/api/signature_request.rb', line 325

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'
  }
)

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

Parameters:

  • a customizable set of options

Returns:

  • a SignatureRequest



390
391
392
393
394
395
396
397
398
399
 
# File 'lib/hello_sign/api/signature_request.rb', line 390

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'

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

Parameters:

  • a customizable set of options

Returns:

  • a SignatureRequest object



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:

  • a customizable set of options

  • a customizable set of options

  • 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]) 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]'

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

Parameters:

  • a customizable set of options

Returns:

  • a SignatureRequest



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

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'

Options Hash (opts):

  • signature_request_id (String) —

    The id of the SignatureRequest to remove.

Parameters:

  • a customizable set of options



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

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']
)

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.

  • custom_fields (Array<Hash>) —

    An array of custom merge fields, representing those present on the document with Text Tags.

  • form_fields_per_document (String)

Parameters:

  • a customizable set of options

Returns:

  • a SignatureRequest



121
122
123
124
125
126
127
128
 
# 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
  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'
  }
)

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

Parameters:

  • a customizable set of options

Returns:

  • a SignatureRequest



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

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'

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.

Parameters:

  • a customizable set of options

Returns:

  • a PDF



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

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 



401
402
403
404
405
 
# File 'lib/hello_sign/api/signature_request.rb', line 401

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