Module: HelloSign::Api::UnclaimedDraft

Included in:: Client

Defined in:: lib/hello_sign/api/unclaimed_draft.rb

Overview

Contains all the API calls for the UnclaimedDraft resource. Take a look at our API documentation for creating UnclaimedDrafts (app.hellosign.com/api/reference#UnclaimedDraft) for more information about this.

Author:

hellosign

Instance Method Summary collapse

#create_embedded_unclaimed_draft(opts) ⇒ HelloSign::Resource::UnclaimedDraft

Creates a new Embedded UnclaimedDraft that can be opened in an embedded iFrame.
#create_embedded_unclaimed_draft_with_template(opts) ⇒ HelloSign::Resource::UnclaimedDraft

Creates a new Embedded UnclaimedDraft from a Template that can be opened in an embedded iFrame.
#create_unclaimed_draft(opts) ⇒ HelloSign::Resource::UnclaimedDraft

Creates a new UnclaimedDraft that can be claimed using the claim_url.
#edit_and_resend_unclaimed_draft(opts) ⇒ HelloSign::Resource::UnclaimedDraft

Creates a new SignatureRequest from an Embedded UnclaimedDraft.

Instance Method Details

#create_embedded_unclaimed_draft(opts) ⇒ `HelloSign::Resource::UnclaimedDraft`

Creates a new Embedded UnclaimedDraft that can be opened in an embedded iFrame.

Examples:

type: request_signature

unclaimed_draft = @client.create_embedded_unclaimed_draft(
  test_mode: 1,
  type: 'request_signature',
  subject: 'The NDA we talked about',
  requester_email_address: '[email protected]',
  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
    }
  ],
  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 UnclaimedDraft.
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.
requester_email_address (String) —

The email address of the requester, if “request_signature” type.
type (String) —
The type of UnclaimedDraft to create. Use “send_document” to create a claimable file, and “request_signature” for a claimable signature request.
- For “send_document,” only the file parameter is required.
- For “request_signature,” then signer name and email_address are required.
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)
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)
cc_email_addresses (Array<String>) —

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

Redirects the signer(s) to this URL after completing the SignatureRequest. (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.
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)
use_preexisting_fields (Boolean) —

Sets the detection of predefined PDF fields. Defaults to 0. (optional)
is_for_embedded_signing (Boolean) —

Enable the UnclaimedDraft to be used for an Embedded SignatureRequest. Defaults to 0. (optional)
skip_me_now (Boolean) —

Disables the “Me (Now)” option for the preparer. Not available for type “send_document.” 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:

(HelloSign::Resource::UnclaimedDraft) —

an UnclaimedDraft

# File 'lib/hello_sign/api/unclaimed_draft.rb', line 215

def create_embedded_unclaimed_draft(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::UnclaimedDraft.new post('/unclaimed_draft/create_embedded', body: opts)
end

#create_embedded_unclaimed_draft_with_template(opts) ⇒ `HelloSign::Resource::UnclaimedDraft`

Creates a new Embedded UnclaimedDraft from a Template that can be opened in an embedded iFrame.

Examples:

type: request_signature

unclaimed_draft = @client.create_embedded_unclaimed_draft_with_template(
  test_mode: 1,
  subject: 'The NDA we talked about',
  template_id: 'c26b8a16784a872da37ea946b9ddec7c1e11dff6',
  requester_email_address: '[email protected]',
  message: 'Please sign this NDA and then we can discuss more. Let me know if you have any questions.',
  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'
  },
  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 the UnclaimedDraft.
template_id (String) —
The Template ID to use when creating the UnclaimedDraft.
- Use template_ids if using multiple templates, replacing %i% with an integer to indicate the order of the Templates
requester_email_address (String) —

The email address of the requester, if “request_signature” type.
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>) —
List of signers
- role (String) The signer role indicated on the Template.
- name (String) Signer’s name
- email_address (String) Signer’s email address
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
signing_redirect_url (String) —

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

Redirects the requester to this URL after sending a SignatureRequest. (optional)
metadata (Hash) —

Key-value data attached to the SignatureRequest. (optional)
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.
files (Array<String>) —

Specifies the file path(s) to append to the SignatureRequest. (optional)
file_urls (Array<String>) —

Specifies the URL(s) for the file(s) to append to the SignatureRequest. (optional)
skip_me_now (Boolean) —

Disables the “Me (Now)” option for the preparer. Not available for type “send_document.” Defaults to 0. (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)
signing_options (Hash) —

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

Returns:

(HelloSign::Resource::UnclaimedDraft) —

an UnclaimedDraft

# File 'lib/hello_sign/api/unclaimed_draft.rb', line 293

def create_embedded_unclaimed_draft_with_template(opts)
  opts[:client_id] ||= self.client_id
  prepare_signers opts
  prepare_custom_fields opts
  prepare_ccs opts
  prepare_templates opts
  prepare_files opts

  HelloSign::Resource::UnclaimedDraft.new post('/unclaimed_draft/create_embedded_with_template', body: opts)
end

#create_unclaimed_draft(opts) ⇒ `HelloSign::Resource::UnclaimedDraft`

Creates a new UnclaimedDraft that can be claimed using the claim_url. The first authenticated user to access the claim_url claims the Draft and will be shown either the “Sign and send” or the “Request signature” page with the Draft loaded. Subsequent access to the claim_url will result in a 404 not found error.

Examples:

type: send_document

unclaimed_draft = @client.create_unclaimed_draft(
  test_mode: 1,
  files: ['NDA.pdf', 'AppendixA.pdf']
)

type: request_signature

unclaimed_draft = @client.create_unclaimed_draft(
  test_mode: 1,
  type: 'request_signature',
  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
    }
  ],
  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)
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.
type (String) —
The type of UnclaimedDraft to create. Use “send_document” to create a claimable file, and “request_signature” for a claimable SignatureRequest.
- For “send_document,” only the file parameter is required.
- For “request_signature,” then signer name and email_address are required.
subject (String) —

The subject in the email that will be sent to the signer(s). (optional)
message (String) —

The custom message in the email that will be 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)
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.
cc_email_addresses (Array<String>) —

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

Redirects the signer(s) to this URL after completing 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)
use_preexisting_fields (Boolean) —

Sets the detection of predefined PDF fields. 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:

(HelloSign::Resource::UnclaimedDraft) —

an UnclaimedDraft

# File 'lib/hello_sign/api/unclaimed_draft.rb', line 121

def create_unclaimed_draft opts
  prepare_files opts
  prepare_signers opts
  prepare_form_fields opts
  prepare_custom_fields opts
  prepare_attachments opts

  HelloSign::Resource::UnclaimedDraft.new post('/unclaimed_draft/create', body: opts)
end

#edit_and_resend_unclaimed_draft(opts) ⇒ `HelloSign::Resource::UnclaimedDraft`

Creates a new SignatureRequest from an Embedded UnclaimedDraft.

Examples:

unclaimed_draft = @client.edit_and_resend_unclaimed_draft(
  signature_request_id: '75cdf7dc8b323d43b347e4a3614d1f822bd09491',
  test_mode: 1,
  client_id: 'b6b8e7deaf8f0b95c029dca049356d4a2cf9710a',
)

Parameters:

opts (Hash) —

a customizable set of options

Options Hash (opts):

signature_request_id (String) —

The SignatureRequest ID to edit and resend.
client_id (String) —

The API App Client ID associated with the UnclaimedDraft.
test_mode (Boolean) —

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

Redirects the requester to this URL after sending a SignatureRequest. (optional)
signing_redirect_url (String) —

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

Enable the UnclaimedDraft to be used for an Embedded SignatureRequest. Defaults to 0. (optional)

Returns:

(HelloSign::Resource::UnclaimedDraft) —

an UnclaimedDraft

# File 'lib/hello_sign/api/unclaimed_draft.rb', line 320

def edit_and_resend_unclaimed_draft(opts)
  signature_request_id = opts.delete(:signature_request_id)
  path = "/unclaimed_draft/edit_and_resend/#{signature_request_id}"

  HelloSign::Resource::UnclaimedDraft.new post(path, body: opts)
end

Module: HelloSign::Api::UnclaimedDraft

Overview

Instance Method Summary collapse

Instance Method Details

#create_embedded_unclaimed_draft(opts) ⇒ HelloSign::Resource::UnclaimedDraft

Examples:

type: request_signature

#create_embedded_unclaimed_draft_with_template(opts) ⇒ HelloSign::Resource::UnclaimedDraft

Examples:

type: request_signature

#create_unclaimed_draft(opts) ⇒ HelloSign::Resource::UnclaimedDraft

Examples:

type: send_document

type: request_signature

#edit_and_resend_unclaimed_draft(opts) ⇒ HelloSign::Resource::UnclaimedDraft

Examples:

#create_embedded_unclaimed_draft(opts) ⇒ `HelloSign::Resource::UnclaimedDraft`

#create_embedded_unclaimed_draft_with_template(opts) ⇒ `HelloSign::Resource::UnclaimedDraft`

#create_unclaimed_draft(opts) ⇒ `HelloSign::Resource::UnclaimedDraft`

#edit_and_resend_unclaimed_draft(opts) ⇒ `HelloSign::Resource::UnclaimedDraft`