lib/hello_sign/api/signature_request.rb in hellosign-ruby-sdk-3.7.0 vs lib/hello_sign/api/signature_request.rb in hellosign-ruby-sdk-3.7.1

- old
+ new

@@ -24,22 +24,21 @@ module HelloSign module Api # - # Contains all the api about the SignatureRequest resource. - # Take a look at our {https://app.hellosign.com/api/reference#SignatureRequest signature request api document} + # Contains all the API calls for the SignatureRequest resource. + # Take a look at our API Documentation for sending Signature Requests (https://app.hellosign.com/api/reference#SignatureRequest) # for more information about this. # # @author [hellosign] # module SignatureRequest # # Retrieves a Signature Request with the given ID. # @option opts [String] signature_request_id The id of the SignatureRequest to retrieve. - # @option opts [Integer] ux_version sets the version of the signer page to use # # @return [HelloSign::Resource::SignatureRequest] a SignatureRequest object # # @example # signature_request = @client.get_signature_request :signature_request_id => 'fa5c8a0b0f492d768749333ad6fcc214c111e967' @@ -50,14 +49,15 @@ path += query HelloSign::Resource::SignatureRequest.new get(path) end # - # 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. - # @option opts[:page] [Integer] page (1) Which page number of the Template List to return. - # @option opts[:ux_version] [Integer] ux_version sets the version of the signer page to use - # @option opts[:query] [String] query string to search on, such as "title:Field Trip Release AND from:me" + # 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 CC'd on. + # @option opts [String] account_id Indicates which account to return SignatureRequests for. Defaults to your account. (optional) + # @option opts [Integer] page Sets the page number of the list to return. Defaults to 1. (optional) + # @option opts [Integer] page_size Determines the number of SignatureRequests returned per page. Defaults to 20. (optional) + # @option opts [String] query Search terms and/or fields to filter the SignatureRequests. (optional) # # @return [HelloSign::Resource::ResourceArray] # # @example # signature_requests = @client.get_signature_requests :page => 1 @@ -70,27 +70,37 @@ HelloSign::Resource::ResourceArray.new get(path, opts), 'signature_requests', HelloSign::Resource::SignatureRequest end # # 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 + # If form_fields_per_document is not specified or use_text_tags is not enabled, a signature page will be affixed at the end # and all signers will be required to add their signature there. - # @option opts [Integer] test_mode (0) Whether this is a test, the signature request will not be legally binding if set to 1. - # @option opts [Array<String>] files 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. - # @option opts [Array<String>] file_urls 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. - # @option opts [String] title The title you want to assign to the SignatureRequest. - # @option opts [String] subject The subject in the email that will be sent to the signers. - # @option opts [String] message The custom message in the email that will be sent to the signers. - # @option opts [String] signing_redirect_url The URL you want the signer redirected to after they successfully sign. (optional) + # @option opts [Boolean] test_mode Indicates if this is a test SignatureRequest, it will not be legally binding if set to 1. A boolean value is also accepted. Defaults to 0. (optional) + # @option opts [Array<String>] files Specified file path(s) to upload file(s) to send for signature. Currently we only support use of either the files parameter or file_urls parameter, not both. + # @option opts [Array<String>] file_urls URL(s) for HelloSign to download the file(s) to send for signature. Currently we only support use of either the files parameter or file_urls parameter, not both. + # @option opts [String] title The title you want to assign to the SignatureRequest. (optional) + # @option opts [String] subject The subject in the email that will be sent to the signer(s). (optional) + # @option opts [String] message The custom message in the email that will be sent to the signer(s). (optional) + # @option opts [String] signing_redirect_url The URL you want the signer(s) redirected to after they successfully sign. (optional) # @option opts [Array<Hash>] signers 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. - # @option opts [Array<String>] cc_email_addresses The email addresses that should be CCed. - # @option opts [Array<Hash>] custom_fields An array of custom merge fields, representing those present on the document with Text Tags. - # @option opts [String] form_fields_per_document + # * :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) 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. (optional) + # @option opts [Array<Hash>] custom_fields 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) + # @option opts [Array<String>] cc_email_addresses The email addresses that should be CCed on the SignatureRequest. (optional) + # @option opts [Boolean] use_text_tags Indicates whether the SignatureRequest should have Text Tags enabled. Defaults to 0. (optional) + # @option opts [Boolean] hide_text_tags Indicates whether the Text Tags should be removed automatically. Note that this is not the preferred method. Defaults to 0. (optional) + # @option opts [Hash] metadata Key-value data attached to the SignatureRequest. (optional) + # @option opts [String] client_id The API App Client ID associated with the SignatureRequest. (optional) + # @option opts [Boolean] allow_decline Allows signers to decline the SignatureRequest. Defaults to 0. (optional) + # @option opts [Boolean] allow_reassign Allows signers to reassign the SignatureRequest to another signer. Defaults to 0. (optional) + # @option opts [Array<Hash>] form_fields_per_document The fields that should appear on the document. (optional) # # @return [HelloSign::Resource::SignatureRequest] a SignatureRequest # # @example # signature_request = @client.send_signature_request( @@ -112,11 +122,35 @@ # :name => 'Jill', # :order => 1, # } # ], # :cc_email_addresses => ['lawyer@example.com', 'lawyer@example2.com'], - # :files => ['NDA.pdf', 'AppendixA.pdf'] + # :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 + # } + # ] + # ] # ) # def send_signature_request(opts) prepare_files opts @@ -127,26 +161,34 @@ request = HelloSign::Resource::SignatureRequest.new post('/signature_request/send', :body => opts) end # # Creates and sends a new SignatureRequest based off of the Template specified with the template_id parameter. - # @option opts [Integer] test_mode (0) Whether this is a test, the signature request will not be legally binding if set to 1. - # @option opts [String] template_id The id of the Template to use when creating the SignatureRequest. - # @option opts [String] title The title you want to assign to the SignatureRequest. - # @option opts [String] subject The subject in the email that will be sent to the signers. - # @option opts [String] message The custom message in the email that will be sent to the signers. - # @option opts [String] signing_redirect_url The URL you want the signer redirected to after they successfully sign. (optional) + # @option opts [Boolean] test_mode Indicates if this is a test SignatureRequest, it will not be legally binding if set to 1. A boolean value is also accepted. Defaults to 0. (optional) + # @option opts [String] template_id The Template ID to use when creating the SignatureRequest. + # * Use template_ids[%i%] if using multiple templates, replacing %i% with an integer to indicate the order of the Templates + # @option opts [String] title The title you want to assign to the SignatureRequest. (optional) + # @option opts [String] subject The subject in the email that will be sent to the signer(s). (optional) + # @option opts [String] message The custom message in the email that will be sent to the signer(s). (optional) + # @option opts [String] signing_redirect_url The URL you want the signer(s) redirected to after they successfully sign. (optional) # @option opts [Array<Hash>] signers 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. - # @option opts [Array<Hash>] ccs The email addresses CC destinations. Required when a CC role exists for the Template. - # @option opts [Hash] custom_fields (deprecated) The value to fill in for the custom field with the name of CustomFieldName. - # @option opts [Array<Hash>] custom_fields 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). - # @option opts [Integer] ux_version sets the version of the signer page to use - # + # * :role (String) The signer role indicated on the Template. Note that the role name is case sensitive. + # * :name (String) Signer's name + # * :email_address (String) Signer's email address + # * :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. (optional) + # @option opts [Array<Hash>] ccs 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 + # @option opts [Array<Hash>] custom_fields 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) + # @option opts [Hash] metadata Key-value data attached to the SignatureRequest. (optional) + # @option opts [String] client_id The API App Client ID associated with the SignatureRequest. (optional) + # @option opts [Array<String>] files Use files to indicate the uploaded file(s) to append to the SignatureRequest. (optional) + # @option opts [Array<String>] file_urls Use file_urls to have HelloSign download the file(s) to append to the SignatureRequest. (optional) # @return [HelloSign::Resource::SignatureRequest] a SignatureRequest # @example # signature_request = @client.send_signature_request_with_template( # :test_mode => 1, # :allow_decline => 1, @@ -198,14 +240,15 @@ # { # :email_address =>'accounting@example.com', # :role => "Accounting" # } # ], - # :custom_fields => - # { - # :CustomFieldName => '$20,000' - # } + # :custom_fields => [ + # { + # :CustomFieldName => '$20,000' + # } + # ] # ) # def send_signature_request_with_template(opts) prepare_signers opts prepare_ccs opts @@ -216,13 +259,13 @@ HelloSign::Resource::SignatureRequest.new post('/signature_request/send_with_template', :body => opts) end # # Sends an email to the signer reminding them to sign the signature request. - # @option opts [String] signature_request_id The id of the SignatureRequest to send a reminder for. - # @option opts [String] email_address The email address of the signer to send a reminder to. - # @option opts [Integer] ux_version sets the version of the signer page to use + # @option opts [String] signature_request_id Indicates the ID of the SignatureRequest to send a reminder. + # @option opts [String] email_address The email address of the signer who will receive a reminder. + # @option opts [String] name The name of the signer who will receive a reminder. (optional) # # @return [HelloSign::Resource::SignatureRequest] a SignatureRequest # @example # signature_request = @client.remind_signature_request :signature_request_id => '75cdf7dc8b323d43b347e4a3614d1f822bd09491', :email_address => 'john@example.com' # @@ -230,35 +273,35 @@ HelloSign::Resource::SignatureRequest.new post("/signature_request/remind/#{opts[:signature_request_id]}", :body => opts) end # # Cancels a SignatureRequest. - # @option opts [String] signature_request_id The id of the SignatureRequest to cancel. + # @option opts [String] signature_request_id The ID of the incomplete SignatureRequest to cancel. # # @example # @client.cancel_signature_request :signature_request_id => '75cdf7dc8b323d43b347e4a3614d1f822bd09491' def cancel_signature_request(opts) post("/signature_request/cancel/#{opts[:signature_request_id]}", :body => opts) end # # Removes your access to a completed a SignatureRequest. - # @option opts [String] signature_request_id The id of the SignatureRequest to remove. + # @option opts [String] signature_request_id The ID of the completed SignatureRequest to remove access. # # @example # @client.remove_signature_request :signature_request_id => '75cdf7dc8b323d43b347e4a3614d1f822bd09491' def remove_signature_request(opts) post("/signature_request/remove/#{opts[:signature_request_id]}", :body => opts) end # - # Download the PDF copy of the current documents specified by the signature_request_id parameter. - # @option opts [String] file_type Either 'pdf' or 'zip' depending on the file type desired. Defaults to pdf. - # @option opts [String] get_url 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. - # @option opts [String] signature_request_id The id of the SignatureRequest to retrieve. + # Download a copy of the SignatureRequest documents specified by the signature_request_id parameter. + # @option opts [String] signature_request_id The ID of the SignatureRequest to download. + # @option opts [String] file_type Determines the format of the file - either 'pdf' or 'zip' depending on the file type desired. Defaults to pdf. (optional) + # @option opts [Boolean] get_url 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) # - # @return a PDF + # @return a PDF or Zip # # @example # pdf = @client.signature_request_files :signature_request_id => '75cdf7dc8b323d43b347e4a3614d1f822bd09491' # def signature_request_files(opts) @@ -273,29 +316,38 @@ get(path) end # # 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. - # @option opts [Integer] test_mode (0) Whether this is a test, the signature request will not be legally binding if set to 1. - # @option opts [String] client_id Client id of the app you're using to create this embedded signature request. Visit our {https://app.hellosign.com/api/reference#Embedded embedded page} page to learn more about this parameter. + # If form_fields_per_document is not specified or use_text_tags is not enabled, a signature page will be affixed at the end + # and all signers will be required to add their signature there. + # Note that embedded signature requests can only be signed in embedded iFrames whereas normal signature requests can only be signed on HelloSign.com. + # See our Embedded Signing Walkthrough for more information on Embedded Signing: https://app.hellosign.com/api/embeddedSigningWalkthrough + # @option opts [Boolean] test_mode Indicates if this is a test SignatureRequest, it will not be legally binding if set to 1. A boolean value is also accepted. Defaults to 0. (optional) + # @option opts [String] client_id The API App Client ID associated with the this embedded SignatureRequest. # @option opts [Array<String>] files 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. # @option opts [Array<String>] file_urls 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. - # @option opts [String] title The title you want to assign to the SignatureRequest. - # @option opts [String] subject The subject in the email that will be sent to the signers. - # @option opts [String] message The custom message in the email that will be sent to the signers. - # @option opts [String] signing_redirect_url The URL you want the signer redirected to after they successfully sign. (optional) + # @option opts [String] title The title you want to assign to the SignatureRequest. (optional) + # @option opts [String] subject The subject in the email that will be sent to the signer(s). (optional) + # @option opts [String] message The custom message in the email that will be sent to the signer(s). (optional) # @option opts [Array<Hash>] signers 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. - # @option opts [Array<String>] cc_email_addresses The email addresses that should be CCed. - # @option opts [Array<Hash>] custom_fields An array of custom merge fields, representing those present on the document with Text Tags. - # @option opts [String] form_fields_per_document - # @option opts [Integer] ux_version sets the version of the signer page to use + # * :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) 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. (optional) + # @option opts [Array<Hash>] custom_fields 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) + # @option opts [Array<String>] cc_email_addresses The email addresses that should be CCed on the SignatureRequest. (optional) + # @option opts [Boolean] use_text_tags Indicates whether the SignatureRequest should have Text Tags enabled. Defaults to 0. (optional) + # @option opts [Boolean] hide_text_tags Indicates whether the Text Tags should be removed automatically. Note that this is not the preferred method. Defaults to 0. (optional) + # @option opts [Hash] metadata Key-value data attached to the SignatureRequest. (optional) + # @option opts [Boolean] allow_decline Allows signers to decline the SignatureRequest. Defaults to 0. (optional) + # @option opts [Boolean] allow_reassign Allows signers to reassign the SignatureRequest to another signer. Defaults to 0. (optional) + # @option opts [Array<Hash>] form_fields_per_document The fields that should appear on the document. (optional) # # @return [HelloSign::Resource::SignatureRequest] a SignatureRequest # @example # request = @client.create_embedded_signature_request( # :test_mode => 1, @@ -333,28 +385,33 @@ end # # 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. - # @option opts [Integer] test_mode (0) Whether this is a test, the signature request will not be legally binding if set to 1. - # @option opts [String] client_id Client id of the app you're using to create this embedded signature request. Visit our {https://app.hellosign.com/api/reference#Embedded embedded page} page to learn more about this parameter. - # @option opts [String] template_id The id of the Template to use when creating the SignatureRequest. - # @option opts [String] title The title you want to assign to the SignatureRequest. - # @option opts [String] subject The subject in the email that will be sent to the signers. - # @option opts [String] message The custom message in the email that will be sent to the signers. - # @option opts [String] signing_redirect_url The URL you want the signer redirected to after they successfully sign. (optional) - # @option opts [Integer] hide_text_tags Whether or not your text tags hidden after parsing - # @option opts [Integer] use_text_tags Whether or not your document contains parseable text-tags - # @option opts [Array<Hash>] signers 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. - # @option opts [Hash] ccs The email address of the CC filling the role of RoleName. Required when a CC role exists for the Template. - # @option opts [Hash] custom_fields (deprecated) The value to fill in for custom field with the name of CustomFieldName. - # @option opts [Array<Hash>] custom_fields 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) - # @option opts [Integer] ux_version sets the version of the signer page to use + # @option opts [Boolean] test_mode Indicates if this is a test SignatureRequest, it will not be legally binding if set to 1. A boolean value is also accepted. Defaults to 0. (optional) + # @option opts [String] client_id The API App Client ID associated with the this embedded SignatureRequest. + # @option opts [String] template_id The Template ID to use when creating the SignatureRequest. + # * Use template_ids[%i%] if using multiple templates, replacing %i% with an integer to indicate the order of the Templates + # @option opts [String] title The title you want to assign to the SignatureRequest. (optional) + # @option opts [String] subject The subject in the email that will be sent to the signer(s). (optional) + # @option opts [String] message The custom message in the email that will be sent to the signer(s). (optional) + # @option opts [Array<Hash>] signers List of signers + # * :role (String) The signer role indicated on the Template. Note that the role name is case sensitive. + # * :name (String) Signer's name + # * :email_address (String) Signer's email address + # * :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. (optional) + # @option opts [Array<Hash>] ccs 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 + # @option opts [Array<Hash>] custom_fields 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) + # @option opts [Hash] metadata Key-value data attached to the SignatureRequest. (optional) + # @option opts [Array<String>] files Use files to indicate the uploaded file(s) to append to the SignatureRequest. (optional) + # @option opts [Array<String>] file_urls Use file_urls to have HelloSign download the file(s) to append to the SignatureRequest. (optional) # # @return [HelloSign::Resource::SignatureRequest] a SignatureRequest # @example # request = @client.create_embedded_signature_request_with_template( # :test_mode => 1, @@ -395,9 +452,22 @@ prepare_custom_fields opts prepare_files opts HelloSign::Resource::SignatureRequest.new post('/signature_request/create_embedded_with_template', :body => opts) end + + # + # Updates the email address on a SignatureRequest. + # @option opts [String] signature_request_id The ID of the SignatureRequest to update. + # @option opts [String] signature_id The Signature ID of the recipient to update. + # @option opts [String] email_address The new email address of the recipient. + # + # @example + # @client.update_signature_request( + # :signature_request_id => '75cdf7dc8b323d43b347e4a3614d1f822bd09491', + # :signature_id => '5064ca698bde9581ad75f6d62450eb4b', + # :email_address => 'newEmail@example.com' + # ) 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)