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

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

Updating gem version

  1. 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'
  2. 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 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 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 ReferenceAPI 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 SDKNew Ruby SDK
Pass a hash of values directly to methodPass 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:

  1. Checking event authenticity with built in event hash check
  2. Displaying event types (account callback vs. app callback)
  3. 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 TypeClass
checkboxSubFormFieldsPerDocumentCheckbox
checkbox-mergeSubFormFieldsPerDocumentCheckboxMerge
date_signedSubFormFieldsPerDocumentDateSigned
dropdownSubFormFieldsPerDocumentDropdown
hyperlinkSubFormFieldsPerDocumentHyperlink
initialsSubFormFieldsPerDocumentInitials
radioSubFormFieldsPerDocumentRadio
signatureSubFormFieldsPerDocumentSignature
textSubFormFieldsPerDocumentText
text-mergeSubFormFieldsPerDocumentTextMerge

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 versionNew 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 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 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 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

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.