hellosign-ruby-sdk 3.7.5 → 3.7.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (37) hide show
  1. checksums.yaml +5 -5
  2. data/README.md +2 -2
  3. data/lib/hello_sign.rb +7 -12
  4. data/lib/hello_sign/api.rb +1 -2
  5. data/lib/hello_sign/api/account.rb +17 -30
  6. data/lib/hello_sign/api/api_app.rb +27 -25
  7. data/lib/hello_sign/api/bulk_send_job.rb +62 -0
  8. data/lib/hello_sign/api/embedded.rb +17 -23
  9. data/lib/hello_sign/api/oauth.rb +26 -34
  10. data/lib/hello_sign/api/signature_request.rb +370 -261
  11. data/lib/hello_sign/api/team.rb +21 -26
  12. data/lib/hello_sign/api/template.rb +79 -70
  13. data/lib/hello_sign/api/unclaimed_draft.rb +193 -142
  14. data/lib/hello_sign/client.rb +58 -22
  15. data/lib/hello_sign/configuration.rb +3 -7
  16. data/lib/hello_sign/error.rb +2 -3
  17. data/lib/hello_sign/resource.rb +1 -2
  18. data/lib/hello_sign/resource/account.rb +3 -6
  19. data/lib/hello_sign/resource/api_app.rb +3 -6
  20. data/lib/hello_sign/resource/base_resource.rb +5 -9
  21. data/lib/hello_sign/resource/bulk_send_job.rb +43 -0
  22. data/lib/hello_sign/resource/embedded.rb +7 -10
  23. data/lib/hello_sign/resource/resource_array.rb +7 -10
  24. data/lib/hello_sign/resource/signature_request.rb +6 -9
  25. data/lib/hello_sign/resource/team.rb +3 -6
  26. data/lib/hello_sign/resource/template.rb +5 -8
  27. data/lib/hello_sign/resource/template_draft.rb +4 -7
  28. data/lib/hello_sign/resource/unclaimed_draft.rb +5 -10
  29. data/lib/hello_sign/version.rb +1 -3
  30. data/spec/fixtures/api_app.json +10 -10
  31. data/spec/fixtures/bulk_send_job.json +88 -0
  32. data/spec/fixtures/bulk_send_jobs.json +22 -0
  33. data/spec/hello_sign/api/account_spec.rb +1 -1
  34. data/spec/hello_sign/api/bulk_send_job_spec.rb +53 -0
  35. data/spec/hello_sign_spec.rb +2 -4
  36. data/spec/spec_helper.rb +0 -2
  37. metadata +11 -3
@@ -1,4 +1,3 @@
1
- #
2
1
  # The MIT License (MIT)
3
2
  #
4
3
  # Copyright (C) 2014 hellosign.com
@@ -20,48 +19,43 @@
20
19
  # LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
21
20
  # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
22
21
  # SOFTWARE.
23
- #
24
22
 
25
23
  module HelloSign
26
24
  module Api
27
-
28
- #
29
25
  # Contains all the API calls for the SignatureRequest resource.
30
- # Take a look at our API Documentation for sending Signature Requests (https://app.hellosign.com/api/reference#SignatureRequest)
26
+ # Take a look at our API Documentation on Signature Requests (https://app.hellosign.com/api/reference#SignatureRequest)
31
27
  # for more information about this.
32
28
  #
33
29
  # @author [hellosign]
34
- #
30
+
35
31
  module SignatureRequest
36
32
 
33
+ # Retrieves a SignatureRequest with the given ID.
34
+ # @option opts [String] signature_request_id The ID of the SignatureRequest to retrieve.
37
35
  #
38
- # Retrieves a Signature Request with the given ID.
39
- # @option opts [String] signature_request_id The id of the SignatureRequest to retrieve.
40
- #
41
- # @return [HelloSign::Resource::SignatureRequest] a SignatureRequest object
36
+ # @return [HelloSign::Resource::SignatureRequest] a SignatureRequest
42
37
  #
43
38
  # @example
44
- # signature_request = @client.get_signature_request :signature_request_id => 'fa5c8a0b0f492d768749333ad6fcc214c111e967'
45
- #
39
+ # signature_request = @client.get_signature_request signature_request_id: 'fa5c8a0b0f492d768749333ad6fcc214c111e967'
46
40
  def get_signature_request(opts)
47
- path = "/signature_request/#{opts[:signature_request_id]}"
48
- query = create_query_string(opts, [:ux_version])
49
- path += query
41
+ path = "/signature_request/#{opts[:signature_request_id]}"
42
+
50
43
  HelloSign::Resource::SignatureRequest.new get(path)
51
44
  end
52
45
 
53
- #
54
- # 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.
46
+ # Returns a list of send and received SignatureRequests that you can access. This does not include ones that you have been CC'd on.
55
47
  # @option opts [String] account_id Indicates which account to return SignatureRequests for. Defaults to your account. (optional)
56
48
  # @option opts [Integer] page Sets the page number of the list to return. Defaults to 1. (optional)
57
49
  # @option opts [Integer] page_size Determines the number of SignatureRequests returned per page. Defaults to 20. (optional)
58
- # @option opts [String] query Search terms and/or fields to filter the SignatureRequests. (optional)
50
+ # @option opts [String] query Filters the SignatureRequests based on the search parameters. (optional)
59
51
  #
60
52
  # @return [HelloSign::Resource::ResourceArray]
61
53
  #
62
54
  # @example
63
- # signature_requests = @client.get_signature_requests :page => 1
64
- #
55
+ # signature_requests = @client.get_signature_requests(
56
+ # page: 1,
57
+ # query: "to:jack@example.com+AND+client_id:b6b8e7deaf8f0b95c029dca049356d4a2cf9710a"
58
+ # )
65
59
  def get_signature_requests(opts={})
66
60
  path = '/signature_request/list'
67
61
  opts[:query] = create_search_string(opts[:query]) if opts[:query]
@@ -70,27 +64,29 @@ module HelloSign
70
64
  HelloSign::Resource::ResourceArray.new get(path, opts), 'signature_requests', HelloSign::Resource::SignatureRequest
71
65
  end
72
66
 
73
- #
74
67
  # Creates and sends a new SignatureRequest with the submitted documents.
75
- # If form_fields_per_document is not specified or use_text_tags is not enabled, a signature page will be affixed at the end
76
- # and all signers will be required to add their signature there.
77
- # @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)
78
- # @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.
79
- # @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.
80
- # @option opts [String] title The title you want to assign to the SignatureRequest. (optional)
81
- # @option opts [String] subject The subject in the email that will be sent to the signer(s). (optional)
82
- # @option opts [String] message The custom message in the email that will be sent to the signer(s). (optional)
83
- # @option opts [String] signing_redirect_url The URL you want the signer(s) redirected to after they successfully sign. (optional)
84
- # @option opts [Array<Hash>] signers List of signers, each item is a Hash with these keys:
85
- # * :name (String) Signer's name
86
- # * :email_address (String) Signer's email address
87
- # * :order (Integer) The order the signers are required to sign in (optional)
88
- # * :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)
68
+ # @option opts [Boolean] test_mode Indicates if this is a test SignatureRequest, it will not be legally binding if set to 1. Defaults to 0. (optional)
69
+ # @option opts [Array<String>] files Specifies the file path(s) to send for the SignatureRequest.
70
+ # @option opts [Array<String>] file_urls Specifies the URL(s) for the file(s) to send for the SignatureRequest.
71
+ # @option opts [String] title Assigns a title to the SignatureRequest. (optional)
72
+ # @option opts [String] subject Sets the subject in the email sent to the signer(s). (optional)
73
+ # @option opts [String] message Sets the message in the email sent to the signer(s). (optional)
74
+ # @option opts [String] signing_redirect_url Redirects the signer(s) to this URL after completing the SignatureRequest. (optional)
75
+ # @option opts [Array<Hash>] signers Sets a list of signers, each item is a Hash with these keys:
76
+ # * name (String) Signer's name
77
+ # * email_address (String) Signer's email address
78
+ # * order (Integer) The order the signers are required to sign in (optional)
79
+ # * pin (Integer) Secures the SignatureRequest using this 4-12 character access code. A business plan is required to use this feature. (optional)
80
+ # @option opts [Array<Hash>] attachments Sets a list of attachments signers can upload
81
+ # * name (String) Attachment name
82
+ # * instructions (String) Instructions for uploading the attachment. (optional)
83
+ # * signer_index (Integer) The signer's unique number.
84
+ # * required (Boolean) Determines if the signer is required to upload this attachment. Defaults to 0. (Optional)
89
85
  # @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)
90
- # * :name (String) Custom field name or "Field Label"
91
- # * :value (String) The value of the field. This data will appear on the SignatureRequest.
92
- # * :editor (String) The signer name indicated on the Text Tag or form_fields_per_document that can edit the value of the field. (optional)
93
- # * :required (Boolean) Determines if the field is required or not. (optional)
86
+ # * name (String) Custom field name or "Field Label"
87
+ # * value (String) The value of the field. This data will appear on the SignatureRequest.
88
+ # * editor (String) The signer name indicated on the Text Tag or form_fields_per_document that can edit the value of the field. (optional)
89
+ # * required (Boolean) Determines if the field is required or not. (optional)
94
90
  # @option opts [Array<String>] cc_email_addresses The email addresses that should be CCed on the SignatureRequest. (optional)
95
91
  # @option opts [Boolean] use_text_tags Indicates whether the SignatureRequest should have Text Tags enabled. Defaults to 0. (optional)
96
92
  # @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)
@@ -99,156 +95,157 @@ module HelloSign
99
95
  # @option opts [Boolean] allow_decline Allows signers to decline the SignatureRequest. Defaults to 0. (optional)
100
96
  # @option opts [Boolean] allow_reassign Allows signers to reassign the SignatureRequest to another signer. Defaults to 0. (optional)
101
97
  # @option opts [Array<Hash>] form_fields_per_document The fields that should appear on the document. (optional)
98
+ # @option opts [Hash] signing_options Specifies the types allowed for creating a signature. (optional)
102
99
  #
103
100
  # @return [HelloSign::Resource::SignatureRequest] a SignatureRequest
104
101
  #
105
102
  # @example
106
103
  # signature_request = @client.send_signature_request(
107
- # :test_mode => 1,
108
- # :allow_decline => 1,
109
- # :title => 'NDA with Acme Co.',
110
- # :subject => 'The NDA we talked about',
111
- # :message => 'Please sign this NDA and then we can discuss more. Let me know if you have any questions.',
112
- # :metadata => {
113
- # :client_id => '1234',
114
- # :custom_text => 'NDA #9'
104
+ # test_mode: 1,
105
+ # allow_decline: 1,
106
+ # title: 'NDA with Acme Co.',
107
+ # subject: 'The NDA we talked about',
108
+ # message: 'Please sign this NDA and then we can discuss more. Let me know if you have any questions.',
109
+ # metadata: {
110
+ # client_id: '1234',
111
+ # custom_text: 'NDA #9'
115
112
  # },
116
- # :signers => [{
117
- # :email_address => 'jack@example.com',
118
- # :name => 'Jack',
119
- # :order => 0,
120
- # },{
121
- # :email_address => 'jill@example.com',
122
- # :name => 'Jill',
123
- # :order => 1,
113
+ # signers: [{
114
+ # email_address: 'jack@example.com',
115
+ # name: 'Jack',
116
+ # order: 0,
117
+ # },
118
+ # {
119
+ # email_address: 'jill@example.com',
120
+ # name: 'Jill',
121
+ # order: 1,
122
+ # }],
123
+ # attachments: [{
124
+ # name: 'Passport',
125
+ # instructions: 'Upload your US Passport',
126
+ # signer_index: 0,
127
+ # required: true
128
+ # },
129
+ # {
130
+ # name: 'Driver's License',
131
+ # instructions: 'Upload your CA Driver's License',
132
+ # signer_index: 1,
133
+ # required: false
124
134
  # }
125
135
  # ],
126
- # :cc_email_addresses => ['lawyer@example.com', 'lawyer@example2.com'],
127
- # :files => ['NDA.pdf', 'AppendixA.pdf'],
128
- # :form_fields_per_document => [
129
- # [
130
- # {
131
- # "name": "address",
132
- # "type": "text",
133
- # "x": 160,
134
- # "y": 80,
135
- # "width": 206,
136
- # "height": 32,
137
- # "signer": 0
138
- # }
139
- # ],
140
- # [
141
- # {
142
- # "name": "phone",
143
- # "type": "text",
144
- # "x": 160,
145
- # "y": 150,
146
- # "width": 206,
147
- # "height": 32,
148
- # "signer": 1
149
- # }
150
- # ]
151
- # ]
152
- # )
153
- #
154
-
136
+ # cc_email_addresses: ['lawyer@example.com', 'lawyer@example2.com'],
137
+ # files: ['NDA.pdf', 'AppendixA.pdf'],
138
+ # form_fields_per_document: [
139
+ # [
140
+ # {
141
+ # name: 'address',
142
+ # type: 'text',
143
+ # x: 160,
144
+ # y: 80,
145
+ # width: 206,
146
+ # height: 32,
147
+ # signer: 0
148
+ # }
149
+ # ],
150
+ # [
151
+ # {
152
+ # name: 'phone',
153
+ # type: 'text',
154
+ # x: 160,
155
+ # y: 150,
156
+ # width: 206,
157
+ # height: 32,
158
+ # signer: 1
159
+ # }
160
+ # ]
161
+ # ],
162
+ # signing_options: {
163
+ # draw: true,
164
+ # type: true,
165
+ # upload: false,
166
+ # phone: true,
167
+ # default: 'phone'
168
+ # }
169
+ # )
155
170
  def send_signature_request(opts)
156
171
  prepare_files opts
157
172
  prepare_signers opts
158
173
  prepare_form_fields opts
159
174
  prepare_custom_fields opts
175
+ prepare_attachments opts
160
176
 
161
- request = HelloSign::Resource::SignatureRequest.new post('/signature_request/send', :body => opts)
177
+ request = HelloSign::Resource::SignatureRequest.new post('/signature_request/send', body: opts)
162
178
  end
163
179
 
164
- #
165
180
  # Creates and sends a new SignatureRequest based off of the Template specified with the template_id parameter.
166
- # @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)
181
+ # @option opts [Boolean] test_mode Indicates if this is a test SignatureRequest, it will not be legally binding if set to 1. Defaults to 0. (optional)
182
+ # @option opts [Boolean] allow_decline Allows signers to decline the SignatureRequest. Defaults to 0. (optional)
167
183
  # @option opts [String] template_id The Template ID to use when creating the SignatureRequest.
168
184
  # * Use template_ids[%i%] if using multiple templates, replacing %i% with an integer to indicate the order of the Templates
169
- # @option opts [String] title The title you want to assign to the SignatureRequest. (optional)
170
- # @option opts [String] subject The subject in the email that will be sent to the signer(s). (optional)
171
- # @option opts [String] message The custom message in the email that will be sent to the signer(s). (optional)
172
- # @option opts [String] signing_redirect_url The URL you want the signer(s) redirected to after they successfully sign. (optional)
173
- # @option opts [Array<Hash>] signers List of signers
174
- # * :role (String) The signer role indicated on the Template. Note that the role name is case sensitive.
175
- # * :name (String) Signer's name
176
- # * :email_address (String) Signer's email address
177
- # * :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)
185
+ # @option opts [String] title Assigns a title to the SignatureRequest. (optional)
186
+ # @option opts [String] subject Sets the subject in the email sent to the signer(s). (optional)
187
+ # @option opts [String] message Sets the message in the email sent to the signer(s). (optional)
188
+ # @option opts [String] signing_redirect_url Redirects the signer(s) to this URL after completing the SignatureRequest. (optional)
189
+ # @option opts [Array<Hash>] signer_file Sets a list of signers, each item is a Hash with these keys:
190
+ # * role (Integer) The signer role indicated on the Template.
191
+ # * name (String) Signer's name
192
+ # * email_address (String) Signer's email address
193
+ # * pin (Integer) Secures the SignatureRequest using this 4-12 character access code. A business plan is required to use this feature. (optional)
178
194
  # @option opts [Array<Hash>] ccs The individual(s) to be CC'd on the SignatureRequest. Required when a CC role exists for the Template.
179
- # * :role (String) The CC role indicated on the Template. Note that the role name is case sensitive.
180
- # * :email_address (String) CC Recipient's email address
181
- # @option opts [Array<Hash>] custom_fields An array of custom merge fields, representing those present in the Template. (optional)
182
- # * :name (String) Custom field name or "Field Label"
183
- # * :value (String) The value of the field. This data will appear on the SignatureRequest.
184
- # * :editor (String) The signer name indicated on the Text Tag or form_fields_per_document that can edit the value of the field. (optional)
185
- # * :required (Boolean) Determines if the field is required or not. (optional)
195
+ # * role (String) The CC role indicated on the Template. Note that the role name is case sensitive.
196
+ # * email_address (String) CC Recipient's email address
197
+ # @option opts [Array<Hash>] custom_fields An array of custom merge fields, representing those present on the Template. (optional)
198
+ # * name (String) Custom field name or "Field Label"
199
+ # * value (String) The value of the field. This data will appear on the SignatureRequest.
200
+ # * editor (String) The signer name indicated on the Text Tag or form_fields_per_document that can edit the value of the field. (optional)
201
+ # * required (Boolean) Determines if the field is required or not. (optional)
186
202
  # @option opts [Hash] metadata Key-value data attached to the SignatureRequest. (optional)
187
203
  # @option opts [String] client_id The API App Client ID associated with the SignatureRequest. (optional)
188
204
  # @option opts [Array<String>] files Use files to indicate the uploaded file(s) to append to the SignatureRequest. (optional)
189
205
  # @option opts [Array<String>] file_urls Use file_urls to have HelloSign download the file(s) to append to the SignatureRequest. (optional)
206
+ # @option opts [Hash] signing_options Specifies the types allowed for creating a signature. (optional)
207
+ #
190
208
  # @return [HelloSign::Resource::SignatureRequest] a SignatureRequest
209
+ #
191
210
  # @example
192
- # signature_request = @client.send_signature_request_with_template(
193
- # :test_mode => 1,
194
- # :allow_decline => 1,
195
- # :template_ids => [
196
- # 'c26b8a16784a872da37ea946b9ddec7c1e11dff6',
197
- # 'c7ab48e9a9ee7102dd6229dbbc719abc7d90ff9f'
198
- # ],
199
- # :title => 'Purchase Order',
200
- # :subject => 'Purchase Order',
201
- # :message => 'Glad we could come to an agreement.',
202
- # :metadata => {
203
- # :client_id => '1234',
204
- # :custom_text => 'NDA #9'
205
- # },
206
- # :signers => [
207
- # {
208
- # :email_address => 'george@example.com',
209
- # :name => 'George',
210
- # :role => 'Client'
211
- # },
212
- # {
213
- # :email_address => 'mary@example.com',
214
- # :name => 'Mary',
215
- # :role => 'Manager'
216
- # }
217
- # ]
218
- # )
219
- # @example
220
- # signature_request = @client.send_signature_request_with_template(
221
- # :test_mode => 1,
222
- # :allow_decline => 0,
223
- # :template_id => 'c26b8a16784a872da37ea946b9ddec7c1e11dff6',
224
- # :title => 'Purchase Order',
225
- # :subject => 'Purchase Order',
226
- # :message => 'Glad we could come to an agreement.',
227
- # :files => ['NDA.pdf', 'AppendixA.pdf'],
228
- # :metadata => {
229
- # :client_id => '1234',
230
- # :custom_text => 'NDA #9'
211
+ # signature_request = @client.send_signature_request_with_template(
212
+ # test_mode: 1,
213
+ # allow_decline: 0,
214
+ # template_id: 'c26b8a16784a872da37ea946b9ddec7c1e11dff6',
215
+ # title: 'Purchase Order',
216
+ # subject: 'Purchase Order',
217
+ # message: 'Glad we could come to an agreement.',
218
+ # files: ['NDA.pdf', 'AppendixA.pdf'],
219
+ # metadata: {
220
+ # client_id: '1234',
221
+ # custom_text: 'NDA #9'
231
222
  # },
232
- # :signers => [
233
- # {
234
- # :email_address => 'george@example.com',
235
- # :name => 'George',
236
- # :role => 'Client'
237
- # }
238
- # ],
239
- # :ccs => [
240
- # {
241
- # :email_address =>'accounting@example.com',
242
- # :role => "Accounting"
223
+ # signers: [
224
+ # {
225
+ # email_address: 'george@example.com',
226
+ # name: 'George',
227
+ # role: 'Client'
228
+ # }
229
+ # ],
230
+ # ccs: [
231
+ # {
232
+ # email_address: 'accounting@example.com',
233
+ # role: 'Accounting'
234
+ # }
235
+ # ],
236
+ # custom_fields: [
237
+ # {
238
+ # CustomFieldName: '$20,000'
239
+ # }
240
+ # ],
241
+ # signing_options: {
242
+ # draw: true,
243
+ # type: true,
244
+ # upload: false,
245
+ # phone: true,
246
+ # default: 'phone'
243
247
  # }
244
- # ],
245
- # :custom_fields => [
246
- # {
247
- # :CustomFieldName => '$20,000'
248
- # }
249
- # ]
250
- # )
251
- #
248
+ # )
252
249
  def send_signature_request_with_template(opts)
253
250
  prepare_signers opts
254
251
  prepare_ccs opts
@@ -256,45 +253,120 @@ module HelloSign
256
253
  prepare_custom_fields opts
257
254
  prepare_files opts
258
255
 
259
- HelloSign::Resource::SignatureRequest.new post('/signature_request/send_with_template', :body => opts)
256
+ HelloSign::Resource::SignatureRequest.new post('/signature_request/send_with_template', body: opts)
260
257
  end
261
258
 
259
+ # Creates a BulkSendJob based off of the Template specified with the template_id parameter.
260
+ # @option opts [Boolean] test_mode Indicates if this is a test BulkSendJob, its SignatureRequests will not be legally binding if set to 1. Defaults to 0. (optional)
261
+ # @option opts [String] template_id The Template ID to use when creating the SignatureRequest.
262
+ # * Use template_ids[%i%] if using multiple templates, replacing %i% with an integer to indicate the order of the Templates
263
+ # @option opts [String] title Assigns a title to the SignatureRequest. (optional)
264
+ # @option opts [String] subject Sets the subject in the email sent to the signer(s). (optional)
265
+ # @option opts [String] message Sets the message in the email sent to the signer(s). (optional)
266
+ # @option opts [String] signing_redirect_url Redirects the signer(s) to this URL after completing the SignatureRequest. (optional)
267
+ # @option opts [String] signer_file Uploads a CSV file defining values and options for signer fields. Required if signer_list is not used.
268
+ # @option opts [String] signer_list A JSON array defining values and options for signer fields. Required if signer_file is not used.
269
+ # @option opts [Array<Hash>] custom_fields An array of custom merge fields, representing those present on the Template. (optional)
270
+ # * name (String) Custom field name or "Field Label"
271
+ # * value (String) The value of the field. This data will appear on the SignatureRequest.
272
+ # * editor (String) The signer name indicated on the Text Tag or form_fields_per_document that can edit the value of the field. (optional)
273
+ # * required (Boolean) Determines if the field is required or not. (optional)
274
+ # @option opts [Array<Hash>] ccs The individual(s) to be CC'd on the SignatureRequest. Required when a CC role exists for the Template.
275
+ # * role (String) The CC role indicated on the Template. Note that the role name is case sensitive.
276
+ # * email_address (String) CC Recipient's email address
277
+ # @option opts [Hash] metadata Key-value data attached to the SignatureRequest. (optional)
278
+ # @option opts [String] client_id The API App Client ID associated with the SignatureRequest. (optional)
279
+ #
280
+ # @return [HelloSign::Resource::BulkSendJob] a BulkSendJob
262
281
  #
263
- # Sends an email to the signer reminding them to sign the signature request.
282
+ # @example
283
+ # signature_request = @client.bulk_send_with_template(
284
+ # test_mode: 1,
285
+ # allow_decline: 0,
286
+ # template_id: 'c26b8a16784a872da37ea946b9ddec7c1e11dff6',
287
+ # title: 'Purchase Order',
288
+ # subject: 'Purchase Order',
289
+ # message: 'Glad we could come to an agreement.',
290
+ # metadata: {
291
+ # client_id: '1234',
292
+ # custom_text: 'NDA #9'
293
+ # },
294
+ # signer_list: [
295
+ # {
296
+ # signers: {
297
+ # Client: {
298
+ # name: 'George',
299
+ # email_address: 'bulksend1@example.com'
300
+ # }
301
+ # },
302
+ # custom_fields: {
303
+ # address: '100 Grand'
304
+ # }
305
+ # },
306
+ # {
307
+ # signers: {
308
+ # Client: {
309
+ # name: 'Mary',
310
+ # email_address: 'bulksend2@example.com'
311
+ # }
312
+ # }
313
+ # }
314
+ # ],
315
+ # ccs: [
316
+ # {
317
+ # email_address: 'accounting@example.com',
318
+ # role: 'Accounting'
319
+ # }
320
+ # ]
321
+ # )
322
+ def bulk_send_with_template(opts)
323
+ prepare_bulk_signers opts
324
+ prepare_ccs opts
325
+ prepare_templates opts
326
+ prepare_custom_fields opts
327
+
328
+ HelloSign::Resource::BulkSendJob.new post('/signature_request/bulk_send_with_template', body: opts)
329
+ end
330
+
331
+ # Sends an email reminder to the signer about the SignatureRequest.
264
332
  # @option opts [String] signature_request_id Indicates the ID of the SignatureRequest to send a reminder.
265
333
  # @option opts [String] email_address The email address of the signer who will receive a reminder.
266
334
  # @option opts [String] name The name of the signer who will receive a reminder. (optional)
267
335
  #
268
336
  # @return [HelloSign::Resource::SignatureRequest] a SignatureRequest
269
- # @example
270
- # signature_request = @client.remind_signature_request :signature_request_id => '75cdf7dc8b323d43b347e4a3614d1f822bd09491', :email_address => 'john@example.com'
271
337
  #
338
+ # @example
339
+ # signature_request = @client.remind_signature_request(
340
+ # signature_request_id: '75cdf7dc8b323d43b347e4a3614d1f822bd09491',
341
+ # :email_address: 'john@example.com'
342
+ # )
272
343
  def remind_signature_request(opts)
273
- HelloSign::Resource::SignatureRequest.new post("/signature_request/remind/#{opts[:signature_request_id]}", :body => opts)
344
+ HelloSign::Resource::SignatureRequest.new post("/signature_request/remind/#{opts[:signature_request_id]}", body: opts)
274
345
  end
275
346
 
347
+ # Cancels an incomplete SignatureRequest.
348
+ # @option opts [String] signature_request_id The ID of SignatureRequest to cancel.
276
349
  #
277
- # Cancels a SignatureRequest.
278
- # @option opts [String] signature_request_id The ID of the incomplete SignatureRequest to cancel.
350
+ # @return [HTTP::Status] 200 OK
279
351
  #
280
352
  # @example
281
- # @client.cancel_signature_request :signature_request_id => '75cdf7dc8b323d43b347e4a3614d1f822bd09491'
353
+ # @client.cancel_signature_request signature_request_id: '75cdf7dc8b323d43b347e4a3614d1f822bd09491'
282
354
  def cancel_signature_request(opts)
283
- post("/signature_request/cancel/#{opts[:signature_request_id]}", :body => opts)
355
+ post("/signature_request/cancel/#{opts[:signature_request_id]}", body: opts)
284
356
  end
285
357
 
286
- #
287
358
  # Removes your access to a completed a SignatureRequest.
288
359
  # @option opts [String] signature_request_id The ID of the completed SignatureRequest to remove access.
289
360
  #
361
+ # @return [HTTP::Status] 200 OK
362
+ #
290
363
  # @example
291
- # @client.remove_signature_request :signature_request_id => '75cdf7dc8b323d43b347e4a3614d1f822bd09491'
364
+ # @client.remove_signature_request signature_request_id: '75cdf7dc8b323d43b347e4a3614d1f822bd09491'
292
365
  def remove_signature_request(opts)
293
- post("/signature_request/remove/#{opts[:signature_request_id]}", :body => opts)
366
+ post("/signature_request/remove/#{opts[:signature_request_id]}", body: opts)
294
367
  end
295
368
 
296
- #
297
- # Download a copy of the SignatureRequest documents specified by the signature_request_id parameter.
369
+ # Downloads a copy of the SignatureRequest documents.
298
370
  # @option opts [String] signature_request_id The ID of the SignatureRequest to download.
299
371
  # @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)
300
372
  # @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)
@@ -302,44 +374,49 @@ module HelloSign
302
374
  # @return a PDF or Zip
303
375
  #
304
376
  # @example
305
- # pdf = @client.signature_request_files :signature_request_id => '75cdf7dc8b323d43b347e4a3614d1f822bd09491'
306
- #
377
+ # pdf = @client.signature_request_files signature_request_id: '75cdf7dc8b323d43b347e4a3614d1f822bd09491'
307
378
  def signature_request_files(opts)
308
379
  path = "/signature_request/files/#{opts[:signature_request_id]}"
309
380
  if opts[:file_type]
310
381
  path = path + "?file_type=#{opts[:file_type]}"
311
382
  end
383
+
312
384
  if opts[:get_url]
313
385
  separator = opts[:file_type].nil? ? '?' : '&'
314
386
  path = path + "#{separator}get_url=#{opts[:get_url]}"
387
+ elsif opts[:get_data_uri]
388
+ separator = opts[:file_type].nil? ? '?' : '&'
389
+ path = path + "#{separator}get_data_uri=#{opts[:get_data_uri]}"
315
390
  end
316
391
 
317
392
  get(path)[:body]
318
393
  end
319
394
 
320
- #
321
395
  # Creates a new SignatureRequest with the submitted documents to be signed in an embedded iFrame.
322
- # If form_fields_per_document is not specified or use_text_tags is not enabled, a signature page will be affixed at the end
323
- # and all signers will be required to add their signature there.
324
- # Note that embedded signature requests can only be signed in embedded iFrames whereas normal signature requests can only be signed on HelloSign.com.
325
- # See our Embedded Signing Walkthrough for more information on Embedded Signing: https://app.hellosign.com/api/embeddedSigningWalkthrough
326
- # @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)
396
+ # If form_fields_per_document is not specified or use_text_tags is not enabled, a signature page will be affixed at the end.
397
+ # See our Embedded Signing Walkthrough for more information on Embedded Signing: https://app.hellosign.com/api/embeddedSigningWalkthrough.
398
+ # @option opts [Boolean] test_mode Indicates if this is a test SignatureRequest, it will not be legally binding if set to 1. Defaults to 0. (optional)
327
399
  # @option opts [String] client_id The API App Client ID associated with the this embedded SignatureRequest.
328
400
  # @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.
329
401
  # @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.
330
- # @option opts [String] title The title you want to assign to the SignatureRequest. (optional)
331
- # @option opts [String] subject The subject in the email that will be sent to the signer(s). (optional)
332
- # @option opts [String] message The custom message in the email that will be sent to the signer(s). (optional)
333
- # @option opts [Array<Hash>] signers List of signers, each item is a Hash with these keys:
334
- # * :name (String) Signer's name
335
- # * :email_address (String) Signer's email address
336
- # * :order (Integer) The order the signers are required to sign in (optional)
337
- # * :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)
402
+ # @option opts [String] title Assigns a title to the SignatureRequest. (optional)
403
+ # @option opts [String] subject Sets the subject in the email sent to the signer(s). (optional)
404
+ # @option opts [String] message Sets the message in the email sent to the signer(s). (optional)
405
+ # @option opts [Array<Hash>] signers Sets a list of signers, each item is a Hash with these keys:
406
+ # * name (String) Signer's name
407
+ # * email_address (String) Signer's email address
408
+ # * order (Integer) The order the signers are required to sign in (optional)
409
+ # * pin (Integer) Secures the SignatureRequest using this 4-12 character access code. A business plan is required to use this feature. (optional)
410
+ # @option opts [Array<Hash>] attachments Sets a list of attachments signers can upload
411
+ # * name (String) Attachment name
412
+ # * instructions (String) Instructions for uploading the attachment. (optional)
413
+ # * signer_index (Integer) The signer's unique number.
414
+ # * required (Boolean) Determines if the signer is required to upload this attachment. Defaults to 0. (Optional)
338
415
  # @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)
339
- # * :name (String) Custom field name or "Field Label"
340
- # * :value (String) The value of the field. This data will appear on the SignatureRequest
341
- # * :editor (String) The signer name indicated on the Text Tag or form_fields_per_document that can edit the value of the field. (optional)
342
- # * :required (Boolean) Determines if the field is required or not. (optional)
416
+ # * name (String) Custom field name or "Field Label"
417
+ # * value (String) The value of the field. This data will appear on the SignatureRequest.
418
+ # * editor (String) The signer name indicated on the Text Tag or form_fields_per_document that can edit the value of the field. (optional)
419
+ # * required (Boolean) Determines if the field is required or not. (optional)
343
420
  # @option opts [Array<String>] cc_email_addresses The email addresses that should be CCed on the SignatureRequest. (optional)
344
421
  # @option opts [Boolean] use_text_tags Indicates whether the SignatureRequest should have Text Tags enabled. Defaults to 0. (optional)
345
422
  # @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)
@@ -347,102 +424,134 @@ module HelloSign
347
424
  # @option opts [Boolean] allow_decline Allows signers to decline the SignatureRequest. Defaults to 0. (optional)
348
425
  # @option opts [Boolean] allow_reassign Allows signers to reassign the SignatureRequest to another signer. Defaults to 0. (optional)
349
426
  # @option opts [Array<Hash>] form_fields_per_document The fields that should appear on the document. (optional)
427
+ # @option opts [Hash] signing_options Specifies the types allowed for creating a signature. (optional)
350
428
  #
351
429
  # @return [HelloSign::Resource::SignatureRequest] a SignatureRequest
430
+ #
352
431
  # @example
353
432
  # request = @client.create_embedded_signature_request(
354
- # :test_mode => 1,
355
- # :allow_decline => 1,
356
- # :client_id => 'b6b8e7deaf8f0b95c029dca049356d4a2cf9710a',
357
- # :title => 'NDA with Acme Co.',
358
- # :subject => 'The NDA we talked about',
359
- # :message => 'Please sign this NDA and then we can discuss more. Let me know if you have any questions.',
360
- # :metadata => {
361
- # :client_id => '1234',
362
- # :custom_text => 'NDA #9'
433
+ # test_mode: 1,
434
+ # allow_decline: 1,
435
+ # client_id: 'b6b8e7deaf8f0b95c029dca049356d4a2cf9710a',
436
+ # title: 'NDA with Acme Co.',
437
+ # subject: 'The NDA we talked about',
438
+ # message: 'Please sign this NDA and then we can discuss more. Let me know if you have any questions.',
439
+ # metadata: {
440
+ # client_id: '1234',
441
+ # custom_text: 'NDA #9'
363
442
  # },
364
- # :signers => [{
365
- # :email_address => 'jack@example.com',
366
- # :name => 'Jack',
367
- # :order => 0,
368
- # },{
369
- # :email_address => 'jill@example.com',
370
- # :name => 'Jill',
371
- # :order => 1,
443
+ # signers: [
444
+ # {
445
+ # email_address: 'jack@example.com',
446
+ # name: 'Jack',
447
+ # order: 0,
448
+ # },
449
+ # {
450
+ # email_address: 'jill@example.com',
451
+ # name: 'Jill',
452
+ # order: 1,
453
+ # }
454
+ # ],
455
+ # attachments: [{
456
+ # name: 'Passport',
457
+ # instructions: 'Upload your US Passport',
458
+ # signer_index: 0,
459
+ # required: true
460
+ # },
461
+ # {
462
+ # name: 'Driver's License',
463
+ # instructions: 'Upload your CA Driver's License',
464
+ # signer_index: 1,
465
+ # required: false
372
466
  # }
373
467
  # ],
374
- # :cc_email_addresses => ['lawyer@example.com', 'lawyer@example2.com'],
375
- # :files => ['NDA.pdf', 'AppendixA.pdf']
468
+ # cc_email_addresses: ['lawyer@example.com', 'lawyer@example2.com'],
469
+ # files: ['NDA.pdf', 'AppendixA.pdf'],
470
+ # signing_options: {
471
+ # draw: true,
472
+ # type: true,
473
+ # upload: false,
474
+ # phone: true,
475
+ # default: 'phone'
476
+ # }
376
477
  # )
377
- #
378
478
  def create_embedded_signature_request(opts)
379
479
  opts[:client_id] ||= self.client_id
380
480
  prepare_files opts
381
481
  prepare_signers opts
382
482
  prepare_form_fields opts
383
483
  prepare_custom_fields opts
484
+ prepare_attachments opts
384
485
 
385
- HelloSign::Resource::SignatureRequest.new post('/signature_request/create_embedded', :body => opts)
486
+ HelloSign::Resource::SignatureRequest.new post('/signature_request/create_embedded', body: opts)
386
487
  end
387
488
 
388
- #
389
489
  # Creates a new SignatureRequest based on the given Template to be signed in an embedded iFrame.
390
- # Note that embedded signature requests can only be signed in embedded iFrames whereas normal signature requests can only be signed on HelloSign.
391
- # @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)
490
+ # See our Embedded Signing Walkthrough for more information on Embedded Signing: https://app.hellosign.com/api/embeddedSigningWalkthrough.
491
+ # @option opts [Boolean] test_mode Indicates if this is a test SignatureRequest, it will not be legally binding if set to 1. Defaults to 0. (optional)
392
492
  # @option opts [String] client_id The API App Client ID associated with the this embedded SignatureRequest.
393
493
  # @option opts [String] template_id The Template ID to use when creating the SignatureRequest.
394
494
  # * Use template_ids[%i%] if using multiple templates, replacing %i% with an integer to indicate the order of the Templates
395
- # @option opts [String] title The title you want to assign to the SignatureRequest. (optional)
396
- # @option opts [String] subject The subject in the email that will be sent to the signer(s). (optional)
397
- # @option opts [String] message The custom message in the email that will be sent to the signer(s). (optional)
398
- # @option opts [Array<Hash>] signers List of signers
399
- # * :role (String) The signer role indicated on the Template. Note that the role name is case sensitive.
400
- # * :name (String) Signer's name
401
- # * :email_address (String) Signer's email address
402
- # * :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)
495
+ # @option opts [String] title Assigns a title to the SignatureRequest. (optional)
496
+ # @option opts [String] subject Sets the subject in the email sent to the signer(s). (optional)
497
+ # @option opts [String] message Sets the message in the email sent to the signer(s). (optional)
498
+ # @option opts [Array<Hash>] signers Sets a list of signers, each item is a Hash with these keys:
499
+ # * name (String) Signer's name
500
+ # * email_address (String) Signer's email address
501
+ # * order (Integer) The order the signers are required to sign in (optional)
502
+ # * pin (Integer) Secures the SignatureRequest using this 4-12 character access code. A business plan is required to use this feature. (optional)
403
503
  # @option opts [Array<Hash>] ccs The individual(s) to be CC'd on the SignatureRequest. Required when a CC role exists for the Template.
404
- # * :role (String) The CC role indicated on the Template. Note that the role name is case sensitive.
405
- # * :email_address (String) CC Recipient's email address
504
+ # * role (String) The CC role indicated on the Template. Note that the role name is case sensitive.
505
+ # * email_address (String) CC Recipient's email address
406
506
  # @option opts [Array<Hash>] custom_fields An array of custom merge fields, representing those present in the Template. (optional)
407
- # * :name (String) Custom field name or "Field Label"
408
- # * :value (String) The value of the field. This data will appear on the SignatureRequest.
409
- # * :editor (String) The signer name indicated on the Text Tag or form_fields_per_document that can edit the value of the field. (optional)
410
- # * :required (Boolean) Determines if the field is required or not. (optional)
507
+ # * name (String) Custom field name or "Field Label"
508
+ # * value (String) The value of the field. This data will appear on the SignatureRequest.
509
+ # * editor (String) The signer name indicated on the Text Tag or form_fields_per_document that can edit the value of the field. (optional)
510
+ # * required (Boolean) Determines if the field is required or not. (optional)
411
511
  # @option opts [Hash] metadata Key-value data attached to the SignatureRequest. (optional)
412
512
  # @option opts [Array<String>] files Use files to indicate the uploaded file(s) to append to the SignatureRequest. (optional)
413
513
  # @option opts [Array<String>] file_urls Use file_urls to have HelloSign download the file(s) to append to the SignatureRequest. (optional)
514
+ # @option opts [Hash] signing_options Specifies the types allowed for creating a signature. (optional)
414
515
  #
415
516
  # @return [HelloSign::Resource::SignatureRequest] a SignatureRequest
517
+ #
416
518
  # @example
417
519
  # request = @client.create_embedded_signature_request_with_template(
418
- # :test_mode => 1,
419
- # :allow_decline => 1,
420
- # :client_id => 'b6b8e7deaf8f0b95c029dca049356d4a2cf9710a',
421
- # :template_id => 'c26b8a16784a872da37ea946b9ddec7c1e11dff6',
422
- # :title => 'Purchase Order',
423
- # :subject => 'Purchase Order',
424
- # :message => 'Glad we could come to an agreement.',
425
- # :files => ['NDA.pdf', 'AppendixA.pdf'],
426
- # :metadata => {
427
- # :client_id => '1234',
428
- # :custom_text => 'NDA #9'
520
+ # test_mode: 1,
521
+ # allow_decline: 1,
522
+ # client_id: 'b6b8e7deaf8f0b95c029dca049356d4a2cf9710a',
523
+ # template_id: 'c26b8a16784a872da37ea946b9ddec7c1e11dff6',
524
+ # title: 'Purchase Order',
525
+ # subject: 'Purchase Order',
526
+ # message: 'Glad we could come to an agreement.',
527
+ # files: ['NDA.pdf', 'AppendixA.pdf'],
528
+ # metadata: {
529
+ # client_id: '1234',
530
+ # custom_text: 'NDA #9'
429
531
  # },
430
- # :signers => [
532
+ # signers: [
431
533
  # {
432
- # :email_address => 'george@example.com',
433
- # :name => 'George',
434
- # :role => 'Client'
534
+ # email_address: 'george@example.com',
535
+ # name: 'George',
536
+ # role: 'Client'
435
537
  # }
436
538
  # ],
437
- # :ccs => [
539
+ # ccs: [
438
540
  # {
439
- # :email_address =>'accounting@example.com',
440
- # :role => "Accounting"
541
+ # email_address: 'accounting@example.com',
542
+ # role: 'Accounting'
441
543
  # }
442
544
  # ],
443
- # :custom_fields => {
444
- # :Cost => '$20,000'
445
- # }
545
+ # custom_fields: {
546
+ # Cost: '$20,000'
547
+ # },
548
+ # signing_options: {
549
+ # draw: true,
550
+ # type: true,
551
+ # upload: false,
552
+ # phone: true,
553
+ # default: 'phone'
554
+ # }
446
555
  # )
447
556
  #
448
557
  def create_embedded_signature_request_with_template(opts)
@@ -453,26 +562,26 @@ module HelloSign
453
562
  prepare_custom_fields opts
454
563
  prepare_files opts
455
564
 
456
- HelloSign::Resource::SignatureRequest.new post('/signature_request/create_embedded_with_template', :body => opts)
565
+ HelloSign::Resource::SignatureRequest.new post('/signature_request/create_embedded_with_template', body: opts)
457
566
  end
458
567
 
459
- #
460
568
  # Updates the email address on a SignatureRequest.
461
569
  # @option opts [String] signature_request_id The ID of the SignatureRequest to update.
462
570
  # @option opts [String] signature_id The Signature ID of the recipient to update.
463
571
  # @option opts [String] email_address The new email address of the recipient.
464
572
  #
573
+ # @return [HelloSign::Resource::SignatureRequest] a SignatureRequest
574
+ #
465
575
  # @example
466
576
  # @client.update_signature_request(
467
- # :signature_request_id => '75cdf7dc8b323d43b347e4a3614d1f822bd09491',
468
- # :signature_id => '5064ca698bde9581ad75f6d62450eb4b',
469
- # :email_address => 'newEmail@example.com'
577
+ # signature_request_id: '75cdf7dc8b323d43b347e4a3614d1f822bd09491',
578
+ # signature_id: '5064ca698bde9581ad75f6d62450eb4b',
579
+ # email_address: 'newEmail@example.com'
470
580
  # )
471
-
472
581
  def update_signature_request(opts)
473
582
  signature_request_id = opts.delete(:signature_request_id)
474
583
  path = "/signature_request/update/#{signature_request_id}"
475
- HelloSign::Resource::SignatureRequest.new post(path, :body => opts)
584
+ HelloSign::Resource::SignatureRequest.new post(path, body: opts)
476
585
  end
477
586
  end
478
587
  end