Module: HelloSign::Api::SignatureRequest

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

Overview

Contains all the API calls for the SignatureRequest resource. Take a look at our API Documentation on Signature Requests (app.hellosign.com/api/reference#SignatureRequest) for more information about this.

Author:

  • hellosign

Instance Method Summary collapse

Instance Method Details

#bulk_send_with_template(opts) ⇒ HelloSign::Resource::BulkSendJob

Creates a BulkSendJob based off of the Template specified with the template_id parameter.

Examples:

signature_request = @client.bulk_send_with_template(
  test_mode: 1,
  allow_decline: 0,
  client_id: 'b6b8e7deaf8f0b95c029dca049356d4a2cf9710a',
  template_id: 'c26b8a16784a872da37ea946b9ddec7c1e11dff6',
  title: 'Purchase Order',
  subject: 'Purchase Order',
  message: 'Glad we could come to an agreement.',
  metadata: {
    client_name: 'John Doe',
    custom_text: 'NDA #9'
  },
  signer_list: [
    {
      signers: {
        Client: {
          name: 'George',
          email_address: '[email protected]'
        }
      },
      custom_fields: {
        address: '100 Grand'
      }
    },
    {
      signers: {
        Client: {
          name: 'Mary',
          email_address: '[email protected]'
        }
      }
    }
  ],
  ccs: [
    {
     email_address: '[email protected]',
     role: 'Accounting'
    }
  ]
)

Parameters:

  • opts (Hash) —

    a customizable set of options

Options Hash (opts):

  • test_mode (Boolean) —

    Indicates if this is a test BulkSendJob, its SignatureRequests will not be legally binding if set to 1. Defaults to 0. (optional)

  • template_id (String) —

    The Template ID to use when creating the SignatureRequest.

    • Use template_ids if using multiple templates, replacing %i% with an integer to indicate the order of the Templates

  • title (String) —

    Assigns a title to the SignatureRequest. (optional)

  • subject (String) —

    Sets the subject in the email sent to the signer(s). (optional)

  • message (String) —

    Sets the message in the email sent to the signer(s). (optional)

  • signing_redirect_url (String) —

    Redirects the signer(s) to this URL after completing the SignatureRequest. (optional)

  • signer_file (String) —

    Uploads a CSV file defining values and options for signer fields. Required if signer_list is not used.

  • signer_list (String) —

    A JSON array defining values and options for signer fields. Required if signer_file is not used.

  • custom_fields (Array<Hash>) —

    An array of custom merge fields, representing those present on the Template. (optional)

    • name (String) Custom field name or “Field Label”

    • value (String) The value of the field. This data will appear on the SignatureRequest.

    • editor (String) The signer name indicated on the Text Tag or form_fields_per_document that can edit the value of the field. (optional)

    • required (Boolean) Determines if the field is required or not. (optional)

  • ccs (Array<Hash>) —

    The individual(s) to be CC’d on the SignatureRequest. Required when a CC role exists for the Template.

    • role (String) The CC role indicated on the Template. Note that the role name is case sensitive.

    • email_address (String) CC Recipient’s email address

  • metadata (Hash) —

    Key-value data attached to the SignatureRequest. (optional)

  • client_id (String) —

    The API App Client ID associated with the SignatureRequest. (optional)

Returns:



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

def bulk_send_with_template(opts)
  opts[:client_id] ||= self.client_id
  prepare_bulk_signers opts
  prepare_ccs opts
  prepare_templates opts
  prepare_custom_fields opts

  HelloSign::Resource::BulkSendJob.new post('/signature_request/bulk_send_with_template', body: opts)
end

#cancel_signature_request(opts) ⇒ HTTP::Status

Cancels an incomplete 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 SignatureRequest to cancel.

Returns:

  • (HTTP::Status) —

    200 OK



435
436
437
 
# File 'lib/hello_sign/api/signature_request.rb', line 435

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 or use_text_tags is not enabled, a signature page will be affixed at the end. See our Embedded Signing Walkthrough for more information on Embedded Signing: app.hellosign.com/api/embeddedSigningWalkthrough.

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_name: 'John Doe',
    custom_text: 'NDA #9'
  },
  signers: [
    {
      email_address: '[email protected]',
      name: 'Jack',
      order: 0,
    },
    {
      email_address: '[email protected]',
      name: 'Jill',
      order: 1,
    }
  ],
  attachments: [{
    name: 'Passport',
    instructions: 'Upload your US Passport',
    signer_index: 0,
    required: true
    },
    {
    name: 'Driver's License',
    instructions: 'Upload your CA Driver's License',
    signer_index: 1,
    required: false
    }
  ],
  cc_email_addresses: ['[email protected]', '[email protected]'],
  files: ['NDA.pdf', 'AppendixA.pdf'],
  signing_options: {
    draw: true,
    type: true,
    upload: false,
    phone: true,
    default: 'phone'
  }
)

Parameters:

  • opts (Hash) —

    a customizable set of options

Options Hash (opts):

  • test_mode (Boolean) —

    Indicates if this is a test SignatureRequest, it will not be legally binding if set to 1. Defaults to 0. (optional)

  • client_id (String) —

    The API App Client ID associated with this embedded SignatureRequest.

  • 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) —

    Assigns a title to the SignatureRequest. (optional)

  • subject (String) —

    Sets the subject in the email sent to the signer(s). (optional)

  • message (String) —

    Sets the message in the email sent to the signer(s). (optional)

  • signers (Array<Hash>) —

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

    • name (String) Signer’s name

    • email_address (String) Signer’s email address

    • order (Integer) The order the signers are required to sign in (optional)

    • pin (Integer) Secures the SignatureRequest using this 4-12 character access code. A business plan is required to use this feature. (optional)

  • attachments (Array<Hash>) —

    Sets a list of attachments signers can upload

    • name (String) Attachment name

    • instructions (String) Instructions for uploading the attachment. (optional)

    • signer_index (Integer) The signer’s unique number.

    • required (Boolean) Determines if the signer is required to upload this attachment. Defaults to 0. (Optional)

  • custom_fields (Array<Hash>) —

    An array of custom merge fields, representing those present on the document with Text Tags or form_fields_per_document (optional)

    • name (String) Custom field name or “Field Label”

    • value (String) The value of the field. This data will appear on the SignatureRequest.

    • editor (String) The signer name indicated on the Text Tag or form_fields_per_document that can edit the value of the field. (optional)

    • required (Boolean) Determines if the field is required or not. (optional)

  • cc_email_addresses (Array<String>) —

    The email addresses that should be CCed on the SignatureRequest. (optional)

  • use_text_tags (Boolean) —

    Indicates whether the SignatureRequest should have Text Tags enabled. Defaults to 0. (optional)

  • hide_text_tags (Boolean) —

    Indicates whether the Text Tags should be removed automatically. Note that this is not the preferred method. Defaults to 0. (optional)

  • metadata (Hash) —

    Key-value data attached to the SignatureRequest. (optional)

  • allow_decline (Boolean) —

    Allows signers to decline the SignatureRequest. Defaults to 0. (optional)

  • allow_reassign (Boolean) —

    Allows signers to reassign the SignatureRequest to another signer. Defaults to 0. (optional)

  • form_fields_per_document (Array<Hash>) —

    The fields that should appear on the document. (optional)

  • signing_options (Hash) —

    Specifies the types allowed for creating a signature. (optional)

Returns:



559
560
561
562
563
564
565
566
567
568
 
# File 'lib/hello_sign/api/signature_request.rb', line 559

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
  prepare_attachments 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. See our Embedded Signing Walkthrough for more information on Embedded Signing: app.hellosign.com/api/embeddedSigningWalkthrough.

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_name: 'John Doe',
    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'
  },
 signing_options: {
   draw: true,
   type: true,
   upload: false,
   phone: true,
   default: 'phone'
 }
)

Parameters:

  • opts (Hash) —

    a customizable set of options

Options Hash (opts):

  • test_mode (Boolean) —

    Indicates if this is a test SignatureRequest, it will not be legally binding if set to 1. Defaults to 0. (optional)

  • client_id (String) —

    The API App Client ID associated with this embedded SignatureRequest.

  • template_id (String) —

    The Template ID to use when creating the SignatureRequest.

    • Use template_ids if using multiple templates, replacing %i% with an integer to indicate the order of the Templates

  • title (String) —

    Assigns a title to the SignatureRequest. (optional)

  • subject (String) —

    Sets the subject in the email sent to the signer(s). (optional)

  • message (String) —

    Sets the message in the email sent to the signer(s). (optional)

  • signers (Array<Hash>) —

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

    • name (String) Signer’s name

    • email_address (String) Signer’s email address

    • order (Integer) The order the signers are required to sign in (optional)

    • pin (Integer) Secures the SignatureRequest using this 4-12 character access code. A business plan is required to use this feature. (optional)

  • ccs (Array<Hash>) —

    The individual(s) to be CC’d on the SignatureRequest. Required when a CC role exists for the Template.

    • role (String) The CC role indicated on the Template. Note that the role name is case sensitive.

    • email_address (String) CC Recipient’s email address

  • custom_fields (Array<Hash>) —

    An array of custom merge fields, representing those present in the Template. (optional)

    • name (String) Custom field name or “Field Label”

    • value (String) The value of the field. This data will appear on the SignatureRequest.

    • editor (String) The signer name indicated on the Text Tag or form_fields_per_document that can edit the value of the field. (optional)

    • required (Boolean) Determines if the field is required or not. (optional)

  • metadata (Hash) —

    Key-value data attached to the SignatureRequest. (optional)

  • files (Array<String>) —

    Use files to indicate the uploaded file(s) to append to the SignatureRequest. (optional)

  • file_urls (Array<String>) —

    Use file_urls to have HelloSign download the file(s) to append to the SignatureRequest. (optional)

  • signing_options (Hash) —

    Specifies the types allowed for creating a signature. (optional)

Returns:



638
639
640
641
642
643
644
645
646
647
 
# File 'lib/hello_sign/api/signature_request.rb', line 638

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

#embedded_bulk_send_with_template(opts) ⇒ HelloSign::Resource::BulkSendJob

Creates an embedded BulkSendJob based off of the Template specified with the template_id parameter.

Examples:

signature_request = @client.embedded_bulk_send_with_template(
  test_mode: 1,
  allow_decline: 0,
  template_id: 'c26b8a16784a872da37ea946b9ddec7c1e11dff6',
  client_id: 'b6b8e7deaf8f0b95c029dca049356d4a2cf9710a',
  title: 'Purchase Order',
  subject: 'Purchase Order',
  message: 'Glad we could come to an agreement.',
  metadata: {
    client_name: 'John Doe',
    custom_text: 'NDA #9'
  },
  signer_list: [
    {
      signers: {
        Client: {
          name: 'George',
          email_address: '[email protected]'
        }
      },
      custom_fields: {
        address: '100 Grand'
      }
    },
    {
      signers: {
        Client: {
          name: 'Mary',
          email_address: '[email protected]'
        }
      }
    }
  ],
  ccs: [
    {
     email_address: '[email protected]',
     role: 'Accounting'
    }
  ]
)

Parameters:

  • opts (Hash) —

    a customizable set of options

Options Hash (opts):

  • test_mode (Boolean) —

    Indicates if this is a test BulkSendJob, its SignatureRequests will not be legally binding if set to 1. Defaults to 0. (optional)

  • template_id (String) —

    The Template ID to use when creating the SignatureRequest.

    • Use template_ids if using multiple templates, replacing %i% with an integer to indicate the order of the Templates

  • client_id (String) —

    The API App Client ID associated with this embedded BulkSendJob.

  • title (String) —

    Assigns a title to the SignatureRequest. (optional)

  • subject (String) —

    Sets the subject in the email sent to the signer(s). (optional)

  • message (String) —

    Sets the message in the email sent to the signer(s). (optional)

  • signing_redirect_url (String) —

    Redirects the signer(s) to this URL after completing the SignatureRequest. (optional)

  • signer_file (String) —

    Uploads a CSV file defining values and options for signer fields. Required if signer_list is not used.

  • signer_list (String) —

    A JSON array defining values and options for signer fields. Required if signer_file is not used.

  • custom_fields (Array<Hash>) —

    An array of custom merge fields, representing those present on the Template. (optional)

    • name (String) Custom field name or “Field Label”

    • value (String) The value of the field. This data will appear on the SignatureRequest.

    • editor (String) The signer name indicated on the Text Tag or form_fields_per_document that can edit the value of the field. (optional)

    • required (Boolean) Determines if the field is required or not. (optional)

  • ccs (Array<Hash>) —

    The individual(s) to be CC’d on the SignatureRequest. Required when a CC role exists for the Template.

    • role (String) The CC role indicated on the Template. Note that the role name is case sensitive.

    • email_address (String) CC Recipient’s email address

  • metadata (Hash) —

    Key-value data attached to the SignatureRequest. (optional)

  • client_id (String) —

    The API App Client ID associated with the SignatureRequest. (optional)

Returns:



402
403
404
405
406
407
408
409
410
 
# File 'lib/hello_sign/api/signature_request.rb', line 402

def embedded_bulk_send_with_template(opts)
  opts[:client_id] ||= self.client_id
  prepare_bulk_signers opts
  prepare_ccs opts
  prepare_templates opts
  prepare_custom_fields opts

  HelloSign::Resource::BulkSendJob.new post('/signature_request/bulk_create_embedded_with_template', body: opts)
end

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

Retrieves a SignatureRequest with the given ID. 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:



40
41
42
43
44
 
# File 'lib/hello_sign/api/signature_request.rb', line 40

def get_signature_request(opts)
  path = "/signature_request/#{opts[:signature_request_id]}"

  HelloSign::Resource::SignatureRequest.new get(path)
end

#get_signature_requests(opts = {}) ⇒ HelloSign::Resource::ResourceArray

Returns a list of send and received SignatureRequests that you can access. This does not include ones that you have been CC’d on. signature_requests = @client.get_signature_requests(

page: 1,
query: "to:[email protected]+AND+client_id:b6b8e7deaf8f0b95c029dca049356d4a2cf9710a"

)

Parameters:

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

    a customizable set of options

Options Hash (opts):

  • account_id (String) —

    Indicates which account to return SignatureRequests for. Defaults to your account. (optional)

  • page (Integer) —

    Sets the page number of the list to return. Defaults to 1. (optional)

  • page_size (Integer) —

    Determines the number of SignatureRequests returned per page. Defaults to 20. (optional)

  • query (String) —

    Filters the SignatureRequests based on the search parameters. (optional)

Returns:



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

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, :query])
  path += query
  HelloSign::Resource::ResourceArray.new get(path, opts), 'signature_requests', HelloSign::Resource::SignatureRequest
end

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

Releases a held SignatureRequest that was claimed and prepared from an UnclaimedDraft.

Examples:

@client.release_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 release.

Returns:



686
687
688
 
# File 'lib/hello_sign/api/signature_request.rb', line 686

def release_hold_signature_request(opts)
HelloSign::Resource::SignatureRequest.new post("/signature_request/release_hold/#{opts[:signature_request_id]}", body: opts)
end

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

Releases a held SignatureRequest that was claimed and prepared from an UnclaimedDraft.

Examples:

@client.release_on_hold_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 release.

Returns:



656
657
658
 
# File 'lib/hello_sign/api/signature_request.rb', line 656

def release_on_hold_signature_request(opts)
HelloSign::Resource::SignatureRequest.new post("/signature_request/release_hold/#{opts[:signature_request_id]}", body: opts)
end

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

Sends an email reminder to the signer about the SignatureRequest.

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

    Indicates the ID of the SignatureRequest to send a reminder.

  • email_address (String) —

    The email address of the signer who will receive a reminder.

  • name (String) —

    The name of the signer who will receive a reminder. (optional)

Returns:



424
425
426
 
# File 'lib/hello_sign/api/signature_request.rb', line 424

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

#remove_signature_request(opts) ⇒ HTTP::Status

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

Returns:

  • (HTTP::Status) —

    200 OK



446
447
448
 
# File 'lib/hello_sign/api/signature_request.rb', line 446

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.

Examples:

signature_request = @client.send_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_name: 'John Doe',
    custom_text: 'NDA #9'
  },
  signers: [{
    email_address: '[email protected]',
    name: 'Jack',
    order: 0,
    },
    {
    email_address: '[email protected]',
    name: 'Jill',
    order: 1,
    }],
  attachments: [{
    name: 'Passport',
    instructions: 'Upload your US Passport',
    signer_index: 0,
    required: true
    },
    {
    name: 'Driver's License',
    instructions: 'Upload your CA Driver's License',
    signer_index: 1,
    required: false
    }
  ],
  cc_email_addresses: ['[email protected]', '[email protected]'],
  files: ['NDA.pdf', 'AppendixA.pdf'],
  form_fields_per_document: [
     [
       {
         name: 'address',
         type: 'text',
         x: 160,
         y: 80,
         width: 206,
         height: 32,
         signer: 0
       }
     ],
     [
       {
         name: 'phone',
         type: 'text',
         x: 160,
         y: 150,
         width: 206,
         height: 32,
         signer: 1
         }
     ]
   ],
  signing_options: {
    draw: true,
    type: true,
    upload: false,
    phone: true,
    default: 'phone'
    }
  )

Parameters:

  • opts (Hash) —

    a customizable set of options

Options Hash (opts):

  • test_mode (Boolean) —

    Indicates if this is a test SignatureRequest, it will not be legally binding if set to 1. Defaults to 0. (optional)

  • files (Array<String>) —

    Specifies the file path(s) to send for the SignatureRequest.

  • file_urls (Array<String>) —

    Specifies the URL(s) for the file(s) to send for the SignatureRequest.

  • title (String) —

    Assigns a title to the SignatureRequest. (optional)

  • subject (String) —

    Sets the subject in the email sent to the signer(s). (optional)

  • message (String) —

    Sets the message in the email sent to the signer(s). (optional)

  • signing_redirect_url (String) —

    Redirects the signer(s) to this URL after completing the SignatureRequest. (optional)

  • signers (Array<Hash>) —

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

    • name (String) Signer’s name

    • email_address (String) Signer’s email address

    • order (Integer) The order the signers are required to sign in (optional)

    • pin (Integer) Secures the SignatureRequest using this 4-12 character access code. A business plan is required to use this feature. (optional)

  • attachments (Array<Hash>) —

    Sets a list of attachments signers can upload

    • name (String) Attachment name

    • instructions (String) Instructions for uploading the attachment. (optional)

    • signer_index (Integer) The signer’s unique number.

    • required (Boolean) Determines if the signer is required to upload this attachment. Defaults to 0. (Optional)

  • custom_fields (Array<Hash>) —

    An array of custom merge fields, representing those present on the document with Text Tags or form_fields_per_document (optional)

    • name (String) Custom field name or “Field Label”

    • value (String) The value of the field. This data will appear on the SignatureRequest.

    • editor (String) The signer name indicated on the Text Tag or form_fields_per_document that can edit the value of the field. (optional)

    • required (Boolean) Determines if the field is required or not. (optional)

  • cc_email_addresses (Array<String>) —

    The email addresses that should be CCed on the SignatureRequest. (optional)

  • use_text_tags (Boolean) —

    Indicates whether the SignatureRequest should have Text Tags enabled. Defaults to 0. (optional)

  • hide_text_tags (Boolean) —

    Indicates whether the Text Tags should be removed automatically. Note that this is not the preferred method. Defaults to 0. (optional)

  • metadata (Hash) —

    Key-value data attached to the SignatureRequest. (optional)

  • client_id (String) —

    The API App Client ID associated with the SignatureRequest. (optional)

  • allow_decline (Boolean) —

    Allows signers to decline the SignatureRequest. Defaults to 0. (optional)

  • allow_reassign (Boolean) —

    Allows signers to reassign the SignatureRequest to another signer. Defaults to 0. (optional)

  • form_fields_per_document (Array<Hash>) —

    The fields that should appear on the document. (optional)

  • signing_options (Hash) —

    Specifies the types allowed for creating a signature. (optional)

Returns:



171
172
173
174
175
176
177
178
179
180
 
# File 'lib/hello_sign/api/signature_request.rb', line 171

def send_signature_request(opts)
  opts[:client_id] ||= self.client_id
  prepare_files opts
  prepare_signers opts
  prepare_form_fields opts
  prepare_custom_fields opts
  prepare_attachments 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: 0,
  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_name: 'John Doe',
    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'
    }
  ],
  signing_options: {
    draw: true,
    type: true,
    upload: false,
    phone: true,
    default: 'phone'
   }
)

Parameters:

  • opts (Hash) —

    a customizable set of options

Options Hash (opts):

  • test_mode (Boolean) —

    Indicates if this is a test SignatureRequest, it will not be legally binding if set to 1. Defaults to 0. (optional)

  • allow_decline (Boolean) —

    Allows signers to decline the SignatureRequest. Defaults to 0. (optional)

  • template_id (String) —

    The Template ID to use when creating the SignatureRequest.

    • Use template_ids if using multiple templates, replacing %i% with an integer to indicate the order of the Templates

  • title (String) —

    Assigns a title to the SignatureRequest. (optional)

  • subject (String) —

    Sets the subject in the email sent to the signer(s). (optional)

  • message (String) —

    Sets the message in the email sent to the signer(s). (optional)

  • signing_redirect_url (String) —

    Redirects the signer(s) to this URL after completing the SignatureRequest. (optional)

  • signer_file (Array<Hash>) —

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

    • role (Integer) The signer role indicated on the Template.

    • name (String) Signer’s name

    • email_address (String) Signer’s email address

    • pin (Integer) Secures the SignatureRequest using this 4-12 character access code. A business plan is required to use this feature. (optional)

  • ccs (Array<Hash>) —

    The individual(s) to be CC’d on the SignatureRequest. Required when a CC role exists for the Template.

    • role (String) The CC role indicated on the Template. Note that the role name is case sensitive.

    • email_address (String) CC Recipient’s email address

  • custom_fields (Array<Hash>) —

    An array of custom merge fields, representing those present on the Template. (optional)

    • name (String) Custom field name or “Field Label”

    • value (String) The value of the field. This data will appear on the SignatureRequest.

    • editor (String) The signer name indicated on the Text Tag or form_fields_per_document that can edit the value of the field. (optional)

    • required (Boolean) Determines if the field is required or not. (optional)

  • metadata (Hash) —

    Key-value data attached to the SignatureRequest. (optional)

  • client_id (String) —

    The API App Client ID associated with the SignatureRequest. (optional)

  • files (Array<String>) —

    Use files to indicate the uploaded file(s) to append to the SignatureRequest. (optional)

  • file_urls (Array<String>) —

    Use file_urls to have HelloSign download the file(s) to append to the SignatureRequest. (optional)

  • signing_options (Hash) —

    Specifies the types allowed for creating a signature. (optional)

Returns:



252
253
254
255
256
257
258
259
260
261
 
# File 'lib/hello_sign/api/signature_request.rb', line 252

def send_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/send_with_template', body: opts)
end

#signature_request_files(opts) ⇒ Object

Downloads a copy of the SignatureRequest documents.

Examples:

pdf = @client.signature_request_files 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 download.

  • file_type (String) —

    Determines the format of the file - either ‘pdf’ or ‘zip’ depending on the file type desired. Defaults to pdf. (optional)

  • get_url (Boolean) —

    Response contains a URL link to the file if set to true. Links are only available for PDFs and have a TTL of 3 days. Defaults to false. (optional)

Returns:

  • a PDF or Zip



459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
 
# File 'lib/hello_sign/api/signature_request.rb', line 459

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]}"
  elsif opts[:get_data_uri]
    separator = opts[:file_type].nil? ? '?' : '&'
    path = path + "#{separator}get_data_uri=#{opts[:get_data_uri]}"
  end

  get(path)[:body]
end

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

Updates the email address on a SignatureRequest.

Examples:

@client.update_signature_request(
  signature_request_id: '75cdf7dc8b323d43b347e4a3614d1f822bd09491',
   signature_id: '5064ca698bde9581ad75f6d62450eb4b',
  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 update.

  • signature_id (String) —

    The Signature ID of the recipient to update.

  • email_address (String) —

    The new email address of the recipient.

Returns:



673
674
675
676
677
 
# File 'lib/hello_sign/api/signature_request.rb', line 673

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