Ruby Migration Guide

Migrating the Ruby SDK from `hellosign-ruby-sdk` to `dropbox-sign`

Welcome! Dropbox Sign's new Ruby SDK is generated from our officially maintained OpenAPI spec. In this release, we've made important updates that introduce new functionality and create feature parity between the Dropbox Sign API and the Ruby SDK. However, some of these changes are considered "breaking" in the sense that they'll require you to update your existing code in order to continue using the SDK.

In this migration guide, we'll cover core concepts in the new SDK, highlight differences from legacy versions, and provide example code showing how past implementations map to the new version's syntax. We'll link out to supporting documents that offer more context behind the breaking changes and why we made them. We apologize for any inconvenience these changes may cause, but are confident the new features will add value to your integration.

Remember that we are here to help if you have any questions or need assistance along the way. Thank you for using Dropbox Sign's Ruby SDK. We hope you enjoy the improvements!

Architecture and Tooling

As mentioned above, the new Ruby SDK (dropbox-sign) is generated from our OpenAPI Spec. Some of the architectural changes impact the tools and locations you use to interact with the SDK.

SDK Resources

Download -- using this new rubygems repo. New Ruby SDK versions will now be published here.
Development -- active development against the Ruby SDK happens here: hellosign-openapi/sdks/ruby.
SDK GitHub Repo -- dropbox-sign-ruby is updated based on changes to hellosign-openapi/sdks/ruby, but no active development work happens there.
Reference Docs -- the automatically generated Reference Docs are a great way to explore the SDK.
Examples -- our full suite of ready to use examples will help you get started quickly.
Engagement -- use the OpenAPI repo to submit Issues or Pull Requests for the Ruby SDK.

Core Concepts and Patterns

This section contains the core concepts and patterns of the new SDK and highlights differences from the legacy SDK.

Installation

First time installation

Install the dropbox-sign gem:
```
gem install dropbox-sign
```
Add the following to your Gemfile:
```
gem 'dropbox-sign', '~> 1.0.0'
```

Updating gem version

Modify the version on your Gemfile to point to the New Ruby SDK package specified on Ruby gems. Or, if using the Gem locally, point to the version specified on our Github repo:
```
gem 'dropbox-sign', '~> 1.0.0'
```
Run
```
bundle install
```

Importing the SDK

Legacy SDK - ImportingNew SDK - Importing

Copy

Copied

require "hello_sign"

Copy

Copied

require "dropbox-sign"

Authentication

The api_key parameter has been renamed to username, and it’s no longer possible to set the client_id on the configure block . The client_id must be set in each API call.

Legacy SDK - ConfigNew SDK - ConfigNew SDK - Full Config + Adding Client ID

Copy

Copied

require 'hello_sign'

HelloSign.configure do |config|
  config.api_key = 'api_key'
end

Copy

Copied

require "dropbox-sign"

Dropbox::Sign.configure do |config|
  # Configure HTTP basic authorization: api_key
  config.username = "YOUR_API_KEY"

  # or, configure Bearer (JWT) authorization: oauth2
  # config.access_token = "YOUR_ACCESS_TOKEN"
end

Copy

Copied

require "dropbox-sign"

Dropbox::Sign.configure do |config|
  # Configure HTTP basic authorization: api_key
  config.username = "YOUR_API_KEY"

  # or, configure Bearer (JWT) authorization: oauth2
  # config.access_token = "YOUR_ACCESS_TOKEN"
end

signature_request_api = Dropbox::Sign::SignatureRequestApi.new

signer_1 = Dropbox::Sign::SubSignatureRequestSigner.new
signer_1.email_address = "example@example.com"
signer_1.name = "Jack"
signer_1.order = 0

data = Dropbox::Sign::SignatureRequestCreateEmbeddedRequest.new

# Client ID added into the signature request here
data.client_id = "5435ebace29d38342cfc435da3c3b34e"
data.title = "NDA with Acme Co."
data.subject = "The NDA we talked about"
data.message = "Please sign this NDA and then we can discuss more"
data.signers = [signer_1]
data.files = [File.open(__dir__ + "/NDA.pdf")]
data.test_mode = true

begin
  result = signature_request_api.signature_request_create_embedded(data)
rescue Dropbox::Sign::ApiError => e
  puts "Exception when calling Dropbox Sign API: #{e}"
end

Endpoints Grouped into Classes

The New Ruby SDK no longer uses the Client class. New classes have been introduced to execute specific endpoints and you will now need to instantiate a model specific client to access the methods needed to make your API calls.

Class Name and Reference	API Reference
AccountApi	/account/* Endpoints
ApiAppApi	/api_app/* Endpoints
BulkSendJobApi	/bulk_send_job/* Endpoints
EmbeddedApi	/embedded/* Endpoints
OAuthApi	/oauth/* Endpoints
ReportApi	/report/* Endpoints
SignatureRequestApi	/signature_request/* Endpoints
TeamApi	/team/* Endpoints
TemplateApi	/template/* Endpoints
UnclaimedDraftApi	/unclaimed_draft/* Endpoints

Using Models to Pass Parameters

Models are used to define the structure and value of the parameters being passed. The fully assembled model is passed to the API endpoint method.

Legacy Ruby SDK	New Ruby SDK
Pass a hash of values directly to method	Pass an instance of the object related to that API request

New SDK Using Models to Pass Parameters

Copy

Copied

require "dropbox-sign"

Dropbox::Sign.configure do |config|
  config.username = "YOUR_API_KEY"
end

signature_request_api = Dropbox::Sign::SignatureRequestApi.new

signer_1 = Dropbox::Sign::SubSignatureRequestSigner.new
signer_1.email_address = "jack@dropboxsign.com"
signer_1.name = "Jack"
signer_1.order = 0

# Passing an instance of the object related to the request as data
obj = Dropbox::Sign::SignatureRequestSendRequest.new

obj.title = "NDA with Acme Co."
obj.subject = "The NDA we talked about"
obj.test_mode = true
obj.signers = [signer_1]
obj.files = [File.open(__dir__ + "/NDA.pdf")]

begin
  result = signature_request_api.signature_request_send(obj)
  p result
rescue Dropbox::Sign::ApiError => e
  puts "Exception when calling Dropbox Sign API: #{e}"
end

Path and Query Parameters

In the legacy SDK you would pass Path and Query parameters alongside any POST data to the API endpoint:

Legacy SDK - Path and Query Parameters

Copy

Copied

signature_request = @client.remind_signature_request(
  signature_request_id: '75cdf7dc8b323d43b347e4a3614d1f822bd09491',
  :email_address: 'john@example.com'
)

The new SDK now requires POST data be an object when calling any API endpoint. Path and Query parameters must be passed individually to these methods.

New SDK - Path and Query Parameters

Copy

Copied

require "dropbox-sign"

Dropbox::Sign.configure do |config|
  config.username = "YOUR_API_KEY"
end

signature_request_api = Dropbox::Sign::SignatureRequestApi.new

data = Dropbox::Sign::SignatureRequestRemindRequest.new
data.email_address = "john@example.com"

signature_request_id = "2f9781e1a8e2045224d808c153c2e1d3df6f8f2f"

begin
  result = signature_request_api.signature_request_remind(signature_request_id, data)
  p result
rescue Dropbox::Sign::ApiError => e
  puts "Exception when calling Dropbox Sign API: #{e}"
end

Error Handling and Warnings

The New SDK handles errors and warnings differently.

Error Handling

Errors are an instance of Dropbox::Sign::ApiError with its body method returning an instance of Dropbox::Sign::ErrorResponse class and should be handled using begin/rescue blocks.

New SDK - Error Handling

Copy

Copied

require "dropbox-sign"

Dropbox::Sign.configure do |config|
  config.username = "YOUR_API_KEY"
end

account_api = Dropbox::Sign::AccountApi.new

begin
  result = account_api.account_get({ email_address: "jack@example.com" })
  p result
rescue Dropbox::Sign::ApiError => e
  puts "Exception when calling Dropbox Sign API: #{e}"
end

Warnings

Warnings are a list of Dropbox::Sign::WarningResponse.

New SDK - Warnings

Copy

Copied

require "dropbox-sign"

Dropbox::Sign.configure do |config|
  config.username = "YOUR_API_KEY"
end

api = Dropbox::Sign::AccountApi.new

data = Dropbox::Sign::AccountCreateRequest.new
data.email_address = "newuser@dropboxsign.com"

begin
  result = api.account_create(data)
  p result

  # warning loop
  result.warnings.each do | warning |
    puts "Warning Name: #{warning.warning_name}"
    puts "Warning Message: #{warning.warning_msg}"
  end

rescue Dropbox::Sign::ApiError => e
  puts "Exception when calling Dropbox Sign API: #{e}"
end

Instantiating Objects From Data

There are three ways to instantiate an object.

You can instantiate a class directly and pass a hash of data
You can use setter methods
You can use the init() static method

New SDK - Using Constructor With Array of DataNew SDK - Using setter methodsNew SDK - Using init() Static Method

Copy

Copied

signer_1 = Dropbox::Sign::SubSignatureRequestSigner.new({
  :email_address => "jack@dropboxsign.com",
  :name          => "Jack",
  :order         => 0,
})

attachment1 = Dropbox::Sign::SubAttachment.new({
  :name         => "Attachment 1",
  :instructions => "Please download this file",
  :signer_index => 0,
  :required     => true,
})

Copy

Copied

signer_1 = Dropbox::Sign::SubSignatureRequestSigner.new
signer_1.email_address = "jack@dropboxsign.com"
signer_1.name = "Jack"
signer_1.order = 0

attachment1 = Dropbox::Sign::SubAttachment.new
attachment1.name = "Attachment 1"
attachment1.instructions = "Please download this file"
attachment1.signer_index = 0
attachment1.required = true

Copy

Copied

signer_1 = Dropbox::Sign::SubSignatureRequestSigner.init({
  :email_address => "jack@dropboxsign.com",
  :name          => "Jack",
  :order         => 0,
})

attachment1 = Dropbox::Sign::SubAttachment.init({
  :name         => "Attachment 1",
  :instructions => "Please download this file",
  :signer_index => 0,
  :required     => true,
})

Note

init() creates a full object using all the data you pass, including nested data to instantiate nested objects. Any parameters that you do not pass data for will be set to their default value (including null).

Event Callback Helper

A callback helper class is included in the New SDK repo to assist in verifying callbacks. The helper simplifies:

Checking event authenticity with built in event hash check
Displaying event types (account callback vs. app callback)
Displaying event messages

The EventCallbackHelper and EventCallbackRequest classes facilitate parsing of event data and assist in validating that a callback originated from Dropbox Sign.We will send event callback payloads to you as a multipart/form-data request with a single json formfield that contains your event callback as a JSON string.

Example Event Callback Request From US to YOU

Copy

Copied

curl -X POST 'https://example.com/YOUR_EVENT_CALLBACK_URL' \
  -F 'json={"event":{"event_type":"account_confirmed","event_time":"1669926463","event_hash":"ff8b03439122f9160500c3fb855bdee5a9ccba5fff27d3b258745d8f3074832f","event_metadata":{"related_signature_id":null,"reported_for_account_id":"6421d70b9bd45059fa207d03ab8d1b96515b472c","reported_for_app_id":null,"event_message":null}}}'

Example JSON Payload

Copy

Copied

{
  "event": {
    "event_type": "account_confirmed",
    "event_time": "1669926463",
    "event_hash": "ff8b03439122f9160500c3fb855bdee5a9ccba5fff27d3b258745d8f3074832f",
    "event_metadata": {
      "related_signature_id": null,
      "reported_for_account_id": "6421d70b9bd45059fa207d03ab8d1b96515b472c",
      "reported_for_app_id": null,
      "event_message": null
    }
  }
}

How to use the EventCallbackHelper

Copy

Copied

require "dropbox-sign"

# use your API key
api_key = "324e3b0840f065eb51f3fd63231d0d33daa35d4ed10d27718839e81737065782"

# callback_data represents data we send to you
callback_data = JSON.parse(req.POST.json, :symbolize_names => true)

callback_event = Dropbox::Sign::EventCallbackRequest.init(callback_data)

# verify that a callback came from HelloSign.com
if Dropbox::Sign::EventCallbackHelper.is_valid(api_key, callback_event)
  # one of "account_callback" or "api_app_callback"
  callback_type = Dropbox::Sign::EventCallbackHelper.get_callback_type(callback_event)

  # do your magic below!
end

Differences from Legacy SDK

This section highlights larger changes to be aware of when migrating to the new SDK.

Form Fields per Document

The Form Fields per Document parameter has changed from a two dimensional array, to a one dimensional array—allowing you to designate which file you to add the field to using document_index. You can learn more about this change here: Form Fields per Document.

Legacy SDK - Form Fields Per DocumentNew SDK - Form Fields per Document

Copy

Copied

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
      }
  ]
]

Copy

Copied

require "dropbox-sign"

Dropbox::Sign.configure do |config|
  config.username = "YOUR_API_KEY"
end

signature_request_api = Dropbox::Sign::SignatureRequestApi.new

signer_1 = Dropbox::Sign::SubSignatureRequestSigner.init({
  :email_address => "jack@dropboxsign.com",
  :name          => "Jack",
  :order         => 0,
})

form_field_1 = Dropbox::Sign::SubFormFieldsPerDocumentText.init({
  :document_index  => 0,
  :api_id          => "134asdf",
  :required        => true,
  :signer          => 0,
  :width           => 100,
  :height          => 16,
  :x               => 112,
  :y               => 700,
  :page            => 1,
  :placeholder     => "Full Name",
  :validation_type => "letters_only"
})

form_field_2 = Dropbox::Sign::SubFormFieldsPerDocumentTextMerge.init({
  :document_index => 0,
  :api_id         => "5678yuio",
  :name           => "Address",
  :required       => true,
  :signer         => 0,
  :width          => 100,
  :height         => 16,
  :x              => 222,
  :y              => 700,
  :page           => 1,
})

form_field_3 = Dropbox::Sign::SubFormFieldsPerDocumentSignature.init({
  :document_index => 0,
  :api_id         => "zxcvuip",
  :required       => true,
  :signer         => 1,
  :width          => 150,
  :height         => 30,
  :x              => 400,
  :y              => 715,
  :page           => 2,
})

data = Dropbox::Sign::SignatureRequestSendRequest.new
data.signers = [signer_1]
data.form_fields_per_document = [form_field_1, form_field_2, form_field_3]

begin
  result = signature_request_api.signature_request_send(data)
  p result
rescue Dropbox::Sign::ApiError => e
  puts "Exception when calling Dropbox Sign API: #{e}"
end

Instantiating the Correct Field Class

There are several different types of form fields you can define, identified by the value of the type field and a few ways to instantiate the correct object when making an API request.

The different classes for each type are:

Field Type	Class
checkbox	SubFormFieldsPerDocumentCheckbox
checkbox-merge	SubFormFieldsPerDocumentCheckboxMerge
date_signed	SubFormFieldsPerDocumentDateSigned
dropdown	SubFormFieldsPerDocumentDropdown
hyperlink	SubFormFieldsPerDocumentHyperlink
initials	SubFormFieldsPerDocumentInitials
radio	SubFormFieldsPerDocumentRadio
signature	SubFormFieldsPerDocumentSignature
text	SubFormFieldsPerDocumentText
text-merge	SubFormFieldsPerDocumentTextMerge

You can use ::init() on the base request class

Copy

Copied

# instantiates a new `SignatureRequestSendRequest` object
data = Dropbox::Sign::SignatureRequestSendRequest.init({
  title: "NDA with Acme Co.",
  subject: "The NDA we talked about",
  message: "Please sign this NDA and then we can discuss more.",
  signers: [
    {
      email_address: "jack@dropboxsign.com",
      name: "Jack",
      order: 0,
    },
  ],
  files: [File.open(__dir__ + "/pdf-sample.pdf")],
  form_fields_per_document: [
    {
      type: "signature",
      document_index: 0,
      api_id: "4688957689",
      name: "signature1",
      x: 5,
      y: 7,
      width: 60,
      height: 30,
      required: true,
      signer: 0,
      page: 1,
    },
  ],
})

You can use ::init() on the field class

Copy

Copied

form_field_1 = Dropbox::Sign::SubFormFieldsPerDocumentSignature.init({
  type: "signature",
  document_index: 0,
  api_id: "4688957689",
  name: "signature1",
  x: 5,
  y: 7,
  width: 60,
  height: 30,
  required: true,
  signer: 0,
  page: 1,
})

You can instantiate the class directly

Copy

Copied

form_field_1 = Dropbox::Sign::SubFormFieldsPerDocumentSignature.new
form_field_1.type = "signature"
form_field_1.document_index = 0
form_field_1.api_id = "4688957689"
form_field_1.name = "signature1"
form_field_1.x = 5
form_field_1.y = 7
form_field_1.width = 60
form_field_1.height = 30
form_field_1.required = true
form_field_1.signer = 0
form_field_1.page = 1

Form Fields per Document Examples using the new SDK:

SignatureInitialsDate SignedTextText MergeCheckboxCheckbox MergeDropdownHyperlinkRadio

Copy

Copied

form_field_1 = Dropbox::Sign::SubFormFieldsPerDocumentSignature.init({
  type: "signature",
  document_index: 0,
  api_id: "4688957689",
  name: "signature1",
  x: 5,
  y: 7,
  width: 60,
  height: 30,
  required: true,
  signer: 0,
  page: 1,
})

Copy

Copied

form_field_1 = Dropbox::Sign::SubFormFieldsPerDocumentInitials.init({
  document_index: 0,
  api_id: "4688957689",
  name: "initials1",
  x: 5,
  y: 7,
  width: 60,
  height: 30,
  required: true,
  signer: 0,
  page: 1,
})

Copy

Copied

form_field_1 = Dropbox::Sign::SubFormFieldsPerDocumentDateSigned.init({
  document_index: 0,
  api_id: "4688957689",
  name: "date_signed1",
  x: 5,
  y: 7,
  width: 60,
  height: 30,
  required: true,
  signer: 0,
  page: 1,
})

Copy

Copied

form_field_1 = Dropbox::Sign::SubFormFieldsPerDocumentText.init({
  document_index: 0,
  api_id: "4688957689",
  name: "text1",
  x: 5,
  y: 7,
  width: 60,
  height: 30,
  required: true,
  signer: 0,
  page: 1,
})

Copy

Copied

first_name = Dropbox::Sign::SubCustomField.init({
  name: "first_name",
  value: "John"
})

form_field_1 = Dropbox::Sign::SubFormFieldsPerDocumentTextMerge.init({
  document_index: 0,
  api_id: "4688957689",
  name: "first_name",
  x: 5,
  y: 7,
  width: 60,
  height: 30,
  required: true,
  signer: 0,
  page: 1,
})

Copy

Copied

form_field_1 = Dropbox::Sign::SubFormFieldsPerDocumentCheckbox.init({
  document_index: 0,
  api_id: "4688957689",
  name: "checkbox1",
  x: 5,
  y: 7,
  width: 60,
  height: 30,
  required: true,
  signer: 0,
  page: 1,
})

Copy

Copied

is_registered = Dropbox::Sign::SubCustomField.init({
  name: "is_registered",
  value: "1"
})

form_field_1 = Dropbox::Sign::SubFormFieldsPerDocumentCheckboxMerge.init({
  document_index: 0,
  api_id: "4688957689",
  name: "is_registered",
  x: 5,
  y: 7,
  width: 60,
  height: 30,
  required: true,
  signer: 0,
  page: 1,
})

Copy

Copied

form_field_1 = Dropbox::Sign::SubFormFieldsPerDocumentDropdown.init({
  document_index: 0,
  api_id: "4688957689",
  name: "dropdown1",
  x: 5,
  y: 7,
  width: 60,
  height: 30,
  required: true,
  signer: 0,
  page: 1,
  options: ["Option 1","Option 2"],
  content: "Option 2",
})

Copy

Copied

form_field_1 = Dropbox::Sign::SubFormFieldsPerDocumentHyperlink.init({
  document_index: 0,
  api_id: "4688957689",
  name: "hyperlink1",
  x: 5,
  y: 7,
  width: 60,
  height: 30,
  required: true,
  signer: "me_now",
  page: 1,
  content: "Click me!",
  content_url: "http://example.com",
})

Copy

Copied

form_field_1 = Dropbox::Sign::SubFormFieldsPerDocumentRadio.init({
  document_index: 0,
  api_id: "4688957689",
  name: "radio1",
  x: 5,
  y: 7,
  width: 60,
  height: 30,
  required: true,
  signer: 0,
  page: 1,
  group: "RadioItemGroup1",
  is_checked: true,
})

form_field_2 = Dropbox::Sign::SubFormFieldsPerDocumentRadio.init({
  document_index: 0,
  api_id: "46876587",
  name: "radio2",
  x: 5,
  y: 50,
  width: 60,
  height: 30,
  required: true,
  signer: 0,
  page: 1,
  group: "RadioItemGroup1",
  is_checked: false,
})

form_field_group_1 = Dropbox::Sign::SubFormFieldGroup.init({
  group_id: "RadioItemGroup1",
  group_label: "Radio Item Group 1",
  requirement: "require_0-1",
})

"role" Value in `signers` Object

In the Legacy SDK when making a Signature Request using a Template the signers property was an object with the role name as the key. In the new SDK the role value has been moved into the signer object itself.For example for the /signature_request/send_with_template endpoint the signers property could be represented as:

Legacy SDK - signers with RolesNew SDK - signers with Roles

Copy

Copied

{
  "signers": {
    "Client": {
      "name": "George",
      "email_address": "george@example.com"
    },
    "Manager": {
      "name": "Bob",
      "email_address": "bob@example.com"
    }
  }
}

Copy

Copied

{
  "signers": [
    {
      "role": "Client",
      "name": "George",
      "email_address": "george@example.com"
    },
    {
      "role": "Manager",
      "name": "Bob",
      "email_address": "bob@example.com"
    }
  ]
}

Using the new SDK you would now send this data as follows:

New SDK - signers with Roles Example #1New SDK - signers with Roles Example #2

Copy

Copied

require "dropbox-sign"

Dropbox::Sign.configure do |config|
  config.username = "YOUR_API_KEY"
end

signature_request_api = Dropbox::Sign::SignatureRequestApi.new

data = Dropbox::Sign::SignatureRequestSendWithTemplateRequest.init({
  template_ids: ["c26b8a16784a872da37ea946b9ddec7c1e11dff6"],
  subject: "Purchase Order",
  message: "Glad we could come to an agreement.",
  signers: [
    {
      role: "Client",
      email_address: "george@example.com",
      name: "George",
    },
    {
      role: "Manager",
      email_address: "bob@example.com",
      name: "Bob",
    }
  ],
})

begin
  result = signature_request_api.signature_request_send_with_template(data)
  p result
rescue Dropbox::Sign::ApiError => e
  puts "Exception when calling Dropbox Sign API: #{e}"
end

Copy

Copied

require "dropbox-sign"

Dropbox::Sign.configure do |config|
  config.username = "YOUR_API_KEY"
end

signature_request_api = Dropbox::Sign::SignatureRequestApi.new

signer_1 = Dropbox::Sign::SubSignatureRequestTemplateSigner.new
signer_1.role = "Client"
signer_1.email_address = "george@example.com"
signer_1.name = "George"

signer_2 = Dropbox::Sign::SubSignatureRequestTemplateSigner.new
signer_2.role = "Manager"
signer_2.email_address = "bob@example.com"
signer_2.name = "Bob"

data = Dropbox::Sign::SignatureRequestSendWithTemplateRequest.new
data.template_ids = ["c26b8a16784a872da37ea946b9ddec7c1e11dff6"]
data.subject = "Purchase Order"
data.message = "Glad we could come to an agreement."
data.signers = [signer_1, signer_2]

begin
  result = signature_request_api.signature_request_send_with_template(data)
  p result
rescue Dropbox::Sign::ApiError => e
  puts "Exception when calling Dropbox Sign API: #{e}"
end

"role" Value in `ccs` Property

In the Legacy SDK when making a Signature Request using a Template the ccs property was an object with the role name as the key. In the new SDK the role value has been moved into the cc object itself, alongside a new email_address property.For example for the /signature_request/send_with_template endpoint the ccs property could be represented as:

Legacy SDK - ccsNew SDK - ccs

Copy

Copied

{
  "ccs": {
    "Client": "george@example.com",
    "Manager": "bob@example.com"
  }
}

Copy

Copied

{
  "ccs": [
    {
      "role": "Client",
      "email_address": "george@example.com"
    },
    {
      "role": "Manager",
      "email_address": "bob@example.com"
    }
  ]
}

Using the new SDK you would now send this data as follows:

New SDK - ccs Example #1New SDK - ccs Example #2

Copy

Copied

require "dropbox-sign"

Dropbox::Sign.configure do |config|
  config.username = "YOUR_API_KEY"
end

signature_request_api = Dropbox::Sign::SignatureRequestApi.new

data = Dropbox::Sign::SignatureRequestSendWithTemplateRequest.init({
  template_ids: ["c26b8a16784a872da37ea946b9ddec7c1e11dff6"],
  subject: "Purchase Order",
  message: "Glad we could come to an agreement.",
  signers: [
    {
      role: "Client",
      email_address: "george@example.com",
      name: "George",
    },
    {
      role: "Manager",
      email_address: "bob@example.com",
      name: "Bob",
    }
  ],
  ccs: [
    {
      role: "Client",
      email_address: "george@example.com",
    },
    {
      role: "Manager",
      email_address: "bob@example.com",
    }
  ]
})

begin
  result = signature_request_api.signature_request_send_with_template(data)
  p result
rescue Dropbox::Sign::ApiError => e
  puts "Exception when calling Dropbox Sign API: #{e}"
end

Copy

Copied

require "dropbox-sign"

Dropbox::Sign.configure do |config|
  config.username = "YOUR_API_KEY"
end

signature_request_api = Dropbox::Sign::SignatureRequestApi.new

signer_1 = Dropbox::Sign::SubSignatureRequestTemplateSigner.new
signer_1.role = "Client"
signer_1.email_address = "george@example.com"
signer_1.name = "George"

signer_2 = Dropbox::Sign::SubSignatureRequestTemplateSigner.new
signer_2.role = "Manager"
signer_2.email_address = "bob@example.com"
signer_2.name = "Bob"

cc_1 = Dropbox::Sign::SubCC.new
cc_1.role = "Client"
cc_1.email_address = "george@example.com"

cc_2 = Dropbox::Sign::SubCC.new
cc_2.role = "Manager"
cc_2.email_address = "bob@example.com"

data = Dropbox::Sign::SignatureRequestSendWithTemplateRequest.new
data.template_ids = ["c26b8a16784a872da37ea946b9ddec7c1e11dff6"]
data.subject = "Purchase Order"
data.message = "Glad we could come to an agreement."
data.signers = [signer_1, signer_2]
data.ccs = [cc_1, cc_2]

begin
  result = signature_request_api.signature_request_send_with_template(data)
  p result
rescue Dropbox::Sign::ApiError => e
  puts "Exception when calling Dropbox Sign API: #{e}"
end

"name" Value in `custom_fields` Property

In the Legacy SDK when making a Signature Request with the custom_fields property it was an object with the name as the key. In the new SDK the name value has been moved into the custom_field object itself.For example for the /signature_request/send_with_template endpoint the custom_fields property could be represented as:

Legacy SDK - custom_fieldsNew SDK - custom_fields

Copy

Copied

{
  "custom_fields": {
    "company": {
      "value": "ABC Corp",
      "required": true
    }
  }
}

Copy

Copied

{
  "custom_fields": [
    {
      "name": "company",
      "value": "ABC Corp",
      "required": true
    }
  ]
}

Using the new SDK you would now send this data as follows:

New SDK - custom_fields Example #1New SDK - custom_fields Example #2

Copy

Copied

require "dropbox-sign"

Dropbox::Sign.configure do |config|
  config.username = "YOUR_API_KEY"
end

signature_request_api = Dropbox::Sign::SignatureRequestApi.new

data = Dropbox::Sign::SignatureRequestSendWithTemplateRequest.init({
  template_ids: ["c26b8a16784a872da37ea946b9ddec7c1e11dff6"],
  subject: "Purchase Order",
  message: "Glad we could come to an agreement.",
  signers: [
    {
      role: "Client",
      email_address: "george@example.com",
      name: "George",
    },
    {
      role: "Manager",
      email_address: "bob@example.com",
      name: "Bob",
    }
  ],
  custom_fields: [
    {
      name: "company",
      value: "ABC Corp",
      required: true,
    },
  ]
})

begin
  result = signature_request_api.signature_request_send_with_template(data)
  p result
rescue Dropbox::Sign::ApiError => e
  puts "Exception when calling Dropbox Sign API: #{e}"
end

Copy

Copied

require "dropbox-sign"

Dropbox::Sign.configure do |config|
  config.username = "YOUR_API_KEY"
end

signature_request_api = Dropbox::Sign::SignatureRequestApi.new

signer_1 = Dropbox::Sign::SubSignatureRequestTemplateSigner.new
signer_1.role = "Client"
signer_1.email_address = "george@example.com"
signer_1.name = "George"

signer_2 = Dropbox::Sign::SubSignatureRequestTemplateSigner.new
signer_2.role = "Manager"
signer_2.email_address = "bob@example.com"
signer_2.name = "Bob"

custom_field_1 = Dropbox::Sign::SubCustomField.new
custom_field_1.name = "company"
custom_field_1.value = "ABC Corp"
custom_field_1.required = true

data = Dropbox::Sign::SignatureRequestSendWithTemplateRequest.new
data.template_ids = ["c26b8a16784a872da37ea946b9ddec7c1e11dff6"]
data.subject = "Purchase Order"
data.message = "Glad we could come to an agreement."
data.signers = [signer_1, signer_2]
data.custom_fields = [custom_field_1]

begin
  result = signature_request_api.signature_request_send_with_template(data)
  p result
rescue Dropbox::Sign::ApiError => e
  puts "Exception when calling Dropbox Sign API: #{e}"
end

`template_id` to `template_ids`

The template_id parameter has been removed. You must now use template_ids.

Legacy SDK version	New SDK Version
Template ID (`template_id`) is passed as a singular string: `template_id : "1234567890"`	Template ID is passed as an array of strings (`template_ids`): `template_ids:["1234567890"]`

`file` to `files`

The file parameter has been renamed to files. Usage remains the same.Use .files([...]);

`file_url` to `file_urls`

The file_url parameter has been renamed to file_urls. Usage remains the same.Use .file_urls([...]);

Interacting with Files

The new SDK version introduces some new patterns around uploading and downloading files. You can read about them more in depth here: Interacting with Files.

Uploading Files

The file upload process changed with the newly-adopted OpenAPI-specification — it is no longer possible to pass file paths into file upload methods. You can learn more about this update here: New Patterns: Interacting with Files.

Legacy SDK

Supports passing filepath as a string

New Ruby SDK

Files needs to be instance of File
Construct instance of Fileusing either File.open or File.new

Legacy SDK - File UploadNew SDK - File Upload

Copy

Copied

client.send_signature_request(
  :test_mode => 1,
  :title => 'NDA',
  :files => ['/Users/NDA.pdf']
)

Copy

Copied

f1 = File.open(__dir__ + "/NDA.pdf")
f2 = File.open(__dir__ + "/Contract.pdf")

data = Dropbox::Sign::SignatureRequestSendRequest.new

data.title = "NDA with Acme Co."
data.signers = [signer_1]
data.files = [f1, f2]

Downloading Files

The file retrieval process changed with the newly-adopted OpenAPI-specification — one endpoint was branched off into three separate endpoints. You can learn more about this update here: New Patterns: Interacting with Files.

Legacy SDK

Returns different file formats depending on parameters used from a single endpoint.

New SDK

Original endpoint broken into 3 separate endpoints to return different file formats.

Legacy SDK - Download FilesNew SDK - Download FilesNew SDK - Download as Data UriNew SDK - File File Url

Copy

Copied

client = HelloSign::Client.new :api_key => 'SIGN_IN_AND_CREATE_API_KEY_FIRST'
file_bin = client.signature_request_files :signature_request_id => 'fa5c8a0b0f492d768749333ad6fcc214c111e967', :file_type => 'pdf'
open("files.pdf", "pdf") do |file|
    file.write(file_bin)
end

Copy

Copied

require "dropbox-sign"

Dropbox::Sign.configure do |config|
  config.username = "YOUR_API_KEY"
end

signature_request_api = Dropbox::Sign::SignatureRequestApi.new

signature_request_id = "fa5c8a0b0f492d768749333ad6fcc214c111e967"

begin
  file_bin = signature_request_api.signature_request_files(signature_request_id)
  FileUtils.cp(file_bin.path, "path/to/file.pdf")
rescue Dropbox::Sign::ApiError => e
  puts "Exception when calling Dropbox Sign API: #{e}"
end

Copy

Copied

require "dropbox-sign"

Dropbox::Sign.configure do |config|
  config.username = "YOUR_API_KEY"
end

signature_request_api = Dropbox::Sign::SignatureRequestApi.new

signature_request_id = "fa5c8a0b0f492d768749333ad6fcc214c111e967"

begin
  result = signature_request_api.signature_request_files_as_data_uri(signature_request_id)
  p result
rescue Dropbox::Sign::ApiError => e
  puts "Exception when calling Dropbox Sign API: #{e}"
end

Copy

Copied

require "dropbox-sign"

Dropbox::Sign.configure do |config|
  config.username = "YOUR_API_KEY"
end

signature_request_api = Dropbox::Sign::SignatureRequestApi.new

signature_request_id = "fa5c8a0b0f492d768749333ad6fcc214c111e967"

begin
  result = signature_request_api.signature_request_files_as_file_url(signature_request_id)
  p result
rescue Dropbox::Sign::ApiError => e
  puts "Exception when calling Dropbox Sign API: #{e}"
end

Downloading Templates

Legacy SDK - Get Template FilesNew SDK - Download Template FilesNew SDK - Template File as Data UriNew SDK - Template File as File Url

Copy

Copied

client = HelloSign::Client.new :api_key => 'SIGN_IN_AND_CREATE_API_KEY_FIRST'
file_bin = client.get_template_files :template_id => 'fa5c8a0b0f492d768749333ad6fcc214c111e967', :file_type => 'pdf'
open("files.pdf", "pdf") do |file|
    file.write(file_bin)
end

Copy

Copied

require "dropbox-sign"

Dropbox::Sign.configure do |config|
  # Configure HTTP basic authorization: api_key
  config.username = "YOUR_API_KEY"

  # or, configure Bearer (JWT) authorization: oauth2
  # config.access_token = "YOUR_ACCESS_TOKEN"
end

template_api = Dropbox::Sign::TemplateApi.new

template_id = "5de8179668f2033afac48da1868d0093bf133266"

begin
  file_bin = template_api.template_files(template_id)
  FileUtils.cp(file_bin.path, "path/to/file.pdf")
rescue Dropbox::Sign::ApiError => e
  puts "Exception when calling Dropbox Sign API: #{e}"
end

Copy

Copied

require "dropbox-sign"

Dropbox::Sign.configure do |config|
  # Configure HTTP basic authorization: api_key
  config.username = "YOUR_API_KEY"

  # or, configure Bearer (JWT) authorization: oauth2
  # config.access_token = "YOUR_ACCESS_TOKEN"
end

template_api = Dropbox::Sign::TemplateApi.new

template_id = "5de8179668f2033afac48da1868d0093bf133266"

begin
  result = template_api.template_files_as_data_uri(template_id)
  p result
rescue Dropbox::Sign::ApiError => e
  puts "Exception when calling Dropbox Sign API: #{e}"
end

Copy

Copied

require "dropbox-sign"

Dropbox::Sign.configure do |config|
  # Configure HTTP basic authorization: api_key
  config.username = "YOUR_API_KEY"

  # or, configure Bearer (JWT) authorization: oauth2
  # config.access_token = "YOUR_ACCESS_TOKEN"
end

template_api = Dropbox::Sign::TemplateApi.new

template_id = "5de8179668f2033afac48da1868d0093bf133266"

begin
  result = template_api.template_files_as_file_url(template_id)
  p result
rescue Dropbox::Sign::ApiError => e
  puts "Exception when calling Dropbox Sign API: #{e}"
end

Endpoint Mapping

This section shows you how endpoints in the legacy SDK map to the new SDK. It doesn't cover all endpoints, but gives you an idea of mapping implementations between the two SDKs. Please reach out if you think we're missing an important example.

Non-Embedded Signature Request
Embedded Signature Request
Send Signature Request with Template
Get Signature Request
List Signature Request
Download Files
Get Account

Non-Embedded Signature Request

Legacy SDK - Non-Embedded Sig RequestNew SDK - Non-Embedded Sig Request

Copy

Copied

client = HelloSign::Client.new
  client.send_signature_request(
    :test_mode => 1,
    :title => 'NDA',
    :subject => 'Please sign this NDA',
    :message => 'Please sign this NDA and then we can discuss more. Let me know if you have any
    questions.',
    :signers => [
      {
        :email_address => 'example@example.com',
        :name => 'Jack',
        :order => 0,
      },
      {
        :email_address => 'example+1@example.com',
        :name => 'Jack 2',
        :order => 1,
      }
    ],
    :files => ['path_to_file']
  )
end

Copy

Copied

require "dropbox-sign"

Dropbox::Sign.configure do |config|
  config.username = "YOUR_API_KEY"
end

signature_request_api = Dropbox::Sign::SignatureRequestApi.new

signer_1 = Dropbox::Sign::SubSignatureRequestSigner.new
signer_1.email_address = "example@example.com"
signer_1.name = "Jack"
signer_1.order = 0

signer_2 = Dropbox::Sign::SubSignatureRequestSigner.new
signer_2.email_address = "jack2@example.com"
signer_2.name = "Jack2"
signer_2.order = 0

data = Dropbox::Sign::SignatureRequestSendRequest.new
data.signers = [signer_1, signer_2]
data.files = [File.open(__dir__ + "/NDA.pdf")]
data.test_mode = 1
data.title = "NDA"
data.subject = "Please sign this NDA"
data.message = "Please sign this NDA and then we can discuss more"

begin
  result = signature_request_api.signature_request_send(data)
  p result
rescue Dropbox::Sign::ApiError => e
  puts "Exception when calling Dropbox Sign API: #{e}"
end

Embedded Signature Request

Legacy SDK - Embedded Sig ReqNew SDK - Embedded Sig Req

Copy

Copied

client.create_embedded_signature_request(
  :test_mode => 1,
  :client_id => 'b6b8e7deaf8f0b95c029dca049356d4a2cf9710a',
  :title => 'NDA with Acme Co.',
  :subject => 'The NDA we talked about',
  :message => 'Please sign this NDA and then we can discuss more. Let me know if you have any
  questions.',
  :signers => [
    {
      :email_address => 'jack@example.com',
      :name => 'Jack',
      :order => 0,
    },{
      :email_address => 'jill@example.com',
      :name => 'Jill',
      :order => 1,
    }
  ],
  :files => ['NDA.pdf', 'AppendixA.pdf']

Copy

Copied

require "dropbox-sign"

Dropbox::Sign.configure do |config|
  config.username = "YOUR_API_KEY"
end

signature_request_api = Dropbox::Sign::SignatureRequestApi.new

signer_1 = Dropbox::Sign::SubSignatureRequestSigner.new
signer_1.email_address = "example@example.com"
signer_1.name = "Jack"
signer_1.order = 0

data = Dropbox::Sign::SignatureRequestCreateEmbeddedRequest.new
data.client_id = "5435ebace29d38342cfc435da3c3b34e"
data.title = "NDA with Acme Co."
data.subject = "The NDA we talked about"
data.message = "Please sign this NDA and then we can discuss more"
data.signers = [signer_1]
data.files = [File.open(__dir__ + "/NDA.pdf")]
data.test_mode = true

begin
  result = signature_request_api.signature_request_create_embedded(data)
  p result
rescue Dropbox::Sign::ApiError => e
  puts "Exception when calling Dropbox Sign API: #{e}"
end

Send Signature Request with Template

Legacy SDK - Sig Req with TemplateNew SDK - Sig Req with Template

Copy

Copied

client = HelloSign::Client.new :api_key => 'SIGN_IN_AND_CREATE_API_KEY_FIRST'
client.send_signature_request_with_template(
  :test_mode => 1,
  :template_id => 'c26b8a16784a872da37ea946b9ddec7c1e11dff6',
  :subject => 'Purchase Order',
  :message => 'Glad we could come to an agreement.',
  :signers => [
    {
      :email_address => 'george@example.com',
      :name => 'George',
      :role => 'Client'
    }
  ],
  :ccs => [
    {
      :email_address =>'accounting@example.com',
      :role => "Accounting"
    }
  ],
  :custom_fields => [
    {
      :name => 'Cost',
      :value => '$20,000'
    }
  ]
)

Copy

Copied

require "dropbox-sign"

Dropbox::Sign.configure do |config|
  config.username = "YOUR_API_KEY"
end

signature_request_api = Dropbox::Sign::SignatureRequestApi.new

signer_1 = Dropbox::Sign::SubSignatureRequestTemplateSigner.new
signer_1.role = "Client"
signer_1.email_address = "dropboxsign@example.com"
signer_1.name = "George"

custom_field_1 = Dropbox::Sign::SubCustomField.new
custom_field_1.name = "Cost"
custom_field_1.value = "$20,000"
custom_field_1.editor = "Client"
custom_field_1.required = true

data = Dropbox::Sign::SignatureRequestSendWithTemplateRequest.new
data.template_ids = ["b7fee29dd746ebab9d8cdfcb7cdbdd0c5a2bc67a"]
data.subject = "Purchase Order"
data.message = "Glad we could come to an agreement."
data.signers = [signer_1]
data.custom_fields = [custom_field_1]
data.signing_options = signing_options
data.test_mode = true

begin
  result = signature_request_api.signature_request_send_with_template(data)
  p result
rescue Dropbox::Sign::ApiError => e
  puts "Exception when calling Dropbox Sign API: #{e}"
end

Get Signature Request

Legacy SDK - Get Sig ReqNew SDK - Get Sig Req

Copy

Copied

client.get_signature_request :signature_request_id => 'fa5c8a0b0f492d768749333ad6fcc214c111e967'

Copy

Copied

require "dropbox-sign"

Dropbox::Sign.configure do |config|
  config.username = "YOUR_API_KEY"
end

signature_request_api = Dropbox::Sign::SignatureRequestApi.new

signature_request_id = "fa5c8a0b0f492d768749333ad6fcc214c111e967"

begin
  result = signature_request_api.signature_request_get(signature_request_id)
  p result
rescue Dropbox::Sign::ApiError => e
  puts "Exception when calling Dropbox Sign API: #{e}"
end

List Signature Request

Legacy SDK - List Sig ReqNew SDK - List Sig Req

Copy

Copied

client.get_signature_requests :page => 1

Copy

Copied

require "dropbox-sign"

Dropbox::Sign.configure do |config|
  config.username = "YOUR_API_KEY"
end

signature_request_api = Dropbox::Sign::SignatureRequestApi.new

account_id = null
page = 1

begin
  result = signature_request_api.signature_request_list({account_id: account_id, page: page})
  p result
rescue Dropbox::Sign::ApiError => e
  puts "Exception when calling Dropbox Sign API: #{e}"
end

Download Files

Legacy SDK - Download FilesNew SDK - Download Files

Copy

Copied

client = HelloSign::Client.new :api_key => 'SIGN_IN_AND_CREATE_API_KEY_FIRST'
file_bin = client.signature_request_files :signature_request_id => 'fa5c8a0b0f492d768749333ad6fcc214c111e967', :file_type => 'pdf'
open("files.pdf", "pdf") do |file|
    file.write(file_bin)
end

Copy

Copied

require "dropbox-sign"

Dropbox::Sign.configure do |config|
  config.username = "YOUR_API_KEY"
end

signature_request_api = Dropbox::Sign::SignatureRequestApi.new

signature_request_id = "c8239739332753028ee193cfde54b6e8141281f3"

begin
  file_bin = signature_request_api.signature_request_files(signature_request_id)
  FileUtils.cp(file_bin.path, "path/to/file.pdf")
rescue Dropbox::Sign::ApiError => e
  puts "Exception when calling Dropbox Sign API: #{e}"
end

Get Account

Legacy SDK - Get AccountNew SDK - Get Account

Copy

Copied

client = HelloSign::Client.new :api_key => 'SIGN_IN_AND_CREATE_API_KEY_FIRST'
client.get_account

Copy

Copied

require "dropbox-sign"

Dropbox::Sign.configure do |config|
  config.username = "YOUR_API_KEY"
end

account_api = Dropbox::Sign::AccountApi.new

begin
  result = account_api.account_get
  p result
rescue Dropbox::Sign::ApiError => e
  puts "Exception when calling Dropbox API: #{e}"
end

Supporting Legacy SDKs

Following the official release of the new SDK version, we'll be preparing to deprecate all legacy versions of the Ruby SDK for one year after launch. That means, once fully launched, we'll only support critical vulnerabilities and bug fixes for legacy SDK versions 3.7.7 for 12 months. After that, legacy versions are considered officially deprecated and are no longer supported. You can find more information in our SDK Versioning Policy.

We encourage you to start migrating (or planning to migrate) to the new SDK as soon as possible. Please don't hesitate to reach out if you have questions or need assistance.

Feedback and Assistance

We know that dealing with "breaking" changes is inconvenient for those of you currently using the legacy SDK, but believe the new SDK offers a better experience while providing access to more features. If you need help or get stuck, please reach out to API support: Submit a Ticket

We warmly welcome your feedback, feature requests, and bug reports in our OpenAPI repo. All of the engineering work on the Ruby SDK happens in the Ruby folder of the repo.

Ruby Migration Guide

Migrating the Ruby SDK from hellosign-ruby-sdk to dropbox-sign

Architecture and Tooling

SDK Resources

Core Concepts and Patterns

Installation

First time installation

Updating gem version

Importing the SDK

Authentication

Endpoints Grouped into Classes

Using Models to Pass Parameters

Path and Query Parameters

Error Handling and Warnings

Error Handling

Warnings

Instantiating Objects From Data

Note

Event Callback Helper

Differences from Legacy SDK

Form Fields per Document

Instantiating the Correct Field Class

"role" Value in signers Object

"role" Value in ccs Property

"name" Value in custom_fields Property

template_id to template_ids

file to files

file_url to file_urls

Interacting with Files

Uploading Files

Legacy SDK

New Ruby SDK

Downloading Files

Legacy SDK

New SDK

Endpoint Mapping

Non-Embedded Signature Request

Embedded Signature Request

Send Signature Request with Template

Get Signature Request

List Signature Request

Download Files

Get Account

Supporting Legacy SDKs

Feedback and Assistance

Migrating the Ruby SDK from `hellosign-ruby-sdk` to `dropbox-sign`

"role" Value in `signers` Object

"role" Value in `ccs` Property

"name" Value in `custom_fields` Property

`template_id` to `template_ids`

`file` to `files`

`file_url` to `file_urls`