HelloSign

A Ruby interface to the HelloSign API.

Installation

gem install hello_sign

Configuration

HelloSign uses HTTP basic authentication to authenticate users.

Configure the client with credentials like this:

HelloSign.configure do |hs|
  hs.email_address = '[email protected]'
  hs.password      = 'space'
end

Those credentials then will be used for each request that requires authentication.

Thread safety

Applications that make requests on behalf of multiple HelloSign users should avoid global configuration. Instead, instantiate a client directly.

hs_client = HelloSign::Client.new(email_address: '[email protected]', password: 'password')

A client instantiated in this way responds to the same methods as the HelloSign constant.

Usage

All responses are returned as JSON.

Account

Create an account

Authentication is not required.

HelloSign.account.create(email_address: '[email protected]', password: 'space')

Fetch account settings

HelloSign.account.settings.show

Update account settings

HelloSign.account.settings.update(callback_url: 'http://callmemaybe.com')

Signature requests

Send a request

Values for :io must be Ruby IO objects (e.g. text_file_io and image_io below).

HelloSign.signature_request.deliver do |request|
  request.title   = 'Lease'
  request.subject = 'Sign this'
  request.message = 'You must sign this.'
  request.ccs     = ['[email protected]', '[email protected]']
  request.signers = [
    {name: 'Jack', email_address: '[email protected]'},
    {name: 'Jill', email_address: '[email protected]'}
  ]
  request.files   = [
    {name: 'test.txt', io: text_file_io, mime: 'text/plain'},
    {name: 'test.jpg', io: image_io,     mime: 'image/jpeg'}
  ]
end

Send a request using a reusable form

Values for :io must be Ruby IO objects (e.g. text_file_io and image_io below).

HelloSign.signature_request.deliver(:form => 'form_id') do |request|
  request.title         = 'Lease'
  request.subject       = 'Sign this'
  request.message       = 'You must sign this.'
  request.ccs           = [
    {email_address: '[email protected]', role: 'lawyer'},
    {email_address: '[email protected]', role: 'accountant'}
  ]
  request.signers       = [
    {name: 'Jack', email_address: '[email protected]', role: 'consultant'},
    {name: 'Jill', email_address: '[email protected]', role: 'client'}
  ]
  request.custom_fields = [
    {name: 'cost', value: '$20,000'},
    {name: 'time', value: 'two weeks'}
  ]
end

Fetch the status on a request

HelloSign.signature_request.status('33sdf3')

Fetch a list of all requests

Defaults to page 1 when no page number is provided.

HelloSign.signature_request.list
HelloSign.signature_request.list(page: 5)

Send a reminder

HelloSign.signature_request.remind('34k2j4', email_address: '[email protected]')

Cancel a request

HelloSign.signature_request.cancel('233rwer')

Fetch a final copy

HelloSign.signature_request.final_copy('233rwer')

Reusable forms

Fetch a list of all forms

Defaults to page 1 when no page number is provided.

HelloSign.reusable_form.list
HelloSign.reusable_form.list(page: 5)

Fetch details on a form

HelloSign.reusable_form.show('34343kdf')

Grant access to a form

HelloSign.reusable_form.grant_access('34343kdf', email_address: '[email protected]')
HelloSign.reusable_form.grant_access('34343kdf', account_id: '1543')

Revoke access to a form

HelloSign.reusable_form.revoke_access('34343kdf', email_address: '[email protected]')
HelloSign.reusable_form.revoke_access('34343kdf', account_id: '1543')

Teams

Create a team

HelloSign.team.create(name: 'The Browncoats')

Fetch team details

HelloSign.team.show

Update team details

HelloSign.team.update(name: 'The Other Guys')

Delete a team

HelloSign.team.destroy

Add a member to the team

HelloSign.team.add_member(email_address: '[email protected]')
HelloSign.team.add_member(account_id: '3432')

Remove a member from the team

HelloSign.team.remove_member(email_address: '[email protected]')
HelloSign.team.remove_member(account_id: '3323')

Unclaimed drafts

Create a draft

HelloSign.unclaimed_draft.create do |draft|
  draft.files = [
    {name: 'test.txt', io: text_io,  mime: 'text/plain'},
    {name: 'test.jpg', io: image_io, mime: 'image/jpeg'}
  ]
end

Supported Ruby interpreters

This gem officially supports and is tested against the following Ruby interpreters:

• MRI 1.9.2
• MRI 1.9.3
• MRI 2.0.0
• JRuby in 1.9 mode
• Rubinius in 1.9 mode

It should also work on Ruby 1.8.7 interpreters. However, since Ruby 1.8.7 will no longer be supported after June 2013, this gem will not be developed with 1.8.7 compatability as a goal.

Contributing

Pull requests are welcome, though consider asking for a feature or bug fix first through the issue tracker. When contributing code, please squash sloppy commits aggressively and follow Tim Pope's guidelines for commit messages.

Copyright

Copyright (c) 2013 Craig Little. See LICENSE for details.