PHP Migration Guide

Migrating the PHP SDK from `hellosign/hellosign-php-sdk` to `dropbox/sign`

Welcome! Dropbox Sign's new PHP 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 PHP 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 PHP SDK. We hope you enjoy the improvements!

Architecture and Tooling

As mentioned above, the new PHP 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 packagist repo. New PHP SDK versions will now be published here.
Development -- active development against the PHP SDK happens here: hellosign-openapi/sdks/php.
SDK GitHub Repo -- dropbox-sign-php is updated based on changes to hellosign-openapi/sdks/php, 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 PHP 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

There are two methods for installing the new SDK:

Install from Packagist

To install from Packagist run:
```
composer require dropbox/sign
```

Build from Source

Download the package ZIP
Move the downloaded file (dropbox-sign-php-main.zip or similar) to your project directory

In the respositories array of your composer.json file, add

{ "type": "artifact", "url": "./PATH_TO_DIRECTORY_WITH_ZIP_FILE" }

Run composer install

Importing the SDK

Use Composer to autoload the package when needed.

Legacy SDK

Use require statement to bring in the entire Dropbox Sign SDK.

New SDK

Use import statement to add the entire SDK or only the pieces you need.

Legacy SDK - importNew SDK - import

Copy

Copied

<?php

require_once __DIR__ . "/vendor/autoload.php";

use HelloSign;

$client = new HelloSign\Client($apikey);

Copy

Copied

<?php

require_once __DIR__ . "/vendor/autoload.php";

// import the entire SDK

use Dropbox;

$signatureApi = new Dropbox\Sign\Api\SignatureRequestApi();

// import the entire SDK and create an alias
use Dropbox\Sign as DropboxSign;

$signatureApi = new DropboxSign\Api\SignatureRequestApi();

// or add only what you need
use Dropbox\Sign\Api\SignatureRequestApi;

$signatureApi = new SignatureRequestApi();

Authentication

Legacy SDK	New SDK
The API key, Email/Password combination or access token was needed to instantiate a `Client` object.	The API key or access token are utilized to configure HTTP basic auth or Bearer auth, respectively. Subsequently, this configuration object is used for the instantiation of API group endpoint classes within the SDK.

Legacy SDK - ConfigurationNew SDK - Configuration

Copy

Copied

<?php

require_once 'vendor/autoload.php';

// API Key config
$client = new HelloSign\Client($apikey);

// Email/Password config
$client = new HelloSign\Client($email_address, $password);

// OAuth config
$client = new HelloSign\Client($access_token); //instance of HelloSign\OAuthToken

Copy

Copied

<?php

require_once __DIR__ . "/vendor/autoload.php";

$config = Dropbox\Sign\Configuration::getDefaultConfiguration();

// Configure HTTP basic authorization: api_key
$config->setUsername("YOUR_API_KEY");

// or, configure Bearer authorization: oauth2
// $config->setAccessToken("YOUR_ACCESS_TOKEN");

// Configuration object passed to Signature Request object instantiation
$embeddedSignature = new Dropbox\Sign\Api\SignatureRequestApi($config);

Endpoints Grouped into Classes

The new SDK divides endpoints across unique Classes:

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.

New SDK Using Models to Pass Parameters

Copy

Copied

<?php

require_once __DIR__ . "/vendor/autoload.php";

$config = Dropbox\Sign\Configuration::getDefaultConfiguration();

$config->setUsername("YOUR_API_KEY");

$apiAppApi = new Dropbox\Sign\Api\ApiAppApi($config);

$oauth = new Dropbox\Sign\Model\SubOAuth();
$oauth->setCallbackUrl("https://example.com/oauth")
    ->setScopes([
        Dropbox\Sign\Model\SubOAuth::SCOPES_BASIC_ACCOUNT_INFO,
        Dropbox\Sign\Model\SubOAuth::SCOPES_REQUEST_SIGNATURE,
    ]);

$whiteLabelingOptions = new Dropbox\Sign\Model\SubWhiteLabelingOptions();
$whiteLabelingOptions->setPrimaryButtonColor("#00b3e6")
    ->setPrimaryButtonTextColor("#ffffff");

$customLogoFile = new SplFileObject(__DIR__ . "/CustomLogoFile.png");

$data = new Dropbox\Sign\Model\ApiAppCreateRequest();
$data->setName("My Production App")
    ->setDomains(["example.com"])
    ->setOauth($oauth)
    ->setWhiteLabelingOptions($whiteLabelingOptions)
    ->setCustomLogoFile($customLogoFile);

try {
    $result = $apiAppApi->apiAppCreate($data);
    print_r($result);
} catch (Dropbox\Sign\ApiException $e) {
    $error = $e->getResponseObject();
    echo "Exception when calling Dropbox Sign API: "
        . print_r($error->getError());
}

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

<?php

require_once 'vendor/autoload.php';

$client = new HelloSign\Client($apikey);

$emailAddress = "john@example.com";
$signatureRequestId = "2f9781e1a8e2045224d808c153c2e1d3df6f8f2f";

$response = $client->requestEmailReminder($signatureRequestId, $emailAddress);
print_r($response);

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

<?php

require_once __DIR__ . "/vendor/autoload.php";

$config = Dropbox\Sign\Configuration::getDefaultConfiguration();

$config->setUsername("YOUR_API_KEY");

$signatureRequestApi = new Dropbox\Sign\Api\SignatureRequestApi($config);

$data = new Dropbox\Sign\Model\SignatureRequestRemindRequest();
$data->setEmailAddress("john@example.com");

$signatureRequestId = "2f9781e1a8e2045224d808c153c2e1d3df6f8f2f";

try {
    $result = $signatureRequestApi->signatureRequestRemind($signatureRequestId, $data);
    print_r($result);
} catch (Dropbox\Sign\ApiException $e) {
    $error = $e->getResponseObject();
    echo "Exception when calling Dropbox Sign API: "
        . print_r($error->getError());
}

Error Handling and Warnings

The New SDK handles errors and warnings differently.

Error Handling

Errors are an instance of Dropbox\Sign\ApiException with its getResponseObject() method returning an instance of Dropbox\Sign\Model\ErrorResponse class and should be handled using Try/Catch blocks.

New SDK - Error Handling

Copy

Copied

<?php

require_once __DIR__ . "/vendor/autoload.php";

$config = Dropbox\Sign\Configuration::getDefaultConfiguration();

$config->setUsername("YOUR_API_KEY");

$accountApi = new Dropbox\Sign\Api\AccountApi($config);

try {
    $result = $accountApi->accountGet(null, 'jack@example.com');
    print_r($result);
} catch (Dropbox\Sign\ApiException $e) {
    $error = $e->getResponseObject();
    echo "Exception when calling Dropbox Sign API: "
        . print_r($error->getError());
}

Warnings

Warnings are a list of Dropbox\Sign\Model\WarningResponse.

New SDK - Warnings

Copy

Copied

<?php

require_once __DIR__ . "/vendor/autoload.php";

$config = Dropbox\Sign\Configuration::getDefaultConfiguration();

$config->setUsername("YOUR_API_KEY");

$api = new Dropbox\Sign\Api\AccountApi($config);

$data = new Dropbox\Sign\Model\AccountCreateRequest();
$data->setEmailAddress("newuser@dropboxsign.com");

try {
    $result = $api->accountCreate($data);
    print_r($result);

    // warning loop
    foreach ($result->getWarnings() as $warning) {
        print_r("Warning Name: {$warning->getWarningName()}");
        print_r("Warning Message: {$warning->getWarningMsg()}");
    }
} catch (Dropbox\Sign\ApiException $e) {
    $error = $e->getResponseObject();
    echo "Exception when calling Dropbox Sign API: "
        . print_r($error->getError());
}

Instantiating Objects From Data

There are three ways to instantiate an object.

You can instantiate a class directly and pass an array 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

$signer1 = new Dropbox\Sign\Model\SubSignatureRequestSigner([
    "email_address" => "jack@example.com",
    "name"          => "Jack",
    "order"         => 0,
]);

$attachment1 = new Dropbox\Sign\Model\SubAttachment([
    "name"         => "Attachment 1",
    "instructions" => "Please download this file",
    "signer_index" => 0,
    "required"     => true,
]);

Copy

Copied

$signer1 = new Dropbox\Sign\Model\SubSignatureRequestSigner();
$signer1->setEmailAddress("jack@example.com")
    ->setName("Jack")
    ->setOrder(0);

$attachment1 = new Dropbox\Sign\Model\SubAttachment();
$attachment1->setName("Attachment 1")
    ->setInstructions("Please download this file")
    ->setSignerIndex(0)
    ->setRequired(true);

Copy

Copied

$signer1 = Dropbox\Sign\Model\SubSignatureRequestSigner::init([
    "email_address" => "jack@example.com",
    "name"          => "Jack",
    "order"         => 0,
]);

$attachment1 = Dropbox\Sign\Model\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

<?php

require_once __DIR__ . "/vendor/autoload.php";

// use your API key
$api_key = "324e3b0840f065eb51f3fd63231d0d33daa35d4ed10d27718839e81737065782";

// $callback_data represents data we send to you
$callback_data = json_decode($_POST["json"] ?? [], true);

$callback_event = Dropbox\Sign\Model\EventCallbackRequest::init($callback_data);

// verify that a callback came from HelloSign.com
if (Dropbox\Sign\EventCallbackHelper::isValid($api_key, $callback_event)) {
    // one of "account_callback" or "api_app_callback"
    $callback_type = Dropbox\Sign\EventCallbackHelper::getCallbackType($callback_event);

    // do your magic below!
}

HTTP Header Info

All methods include a WithHttpInfo() variant. This method ensures HTTP header information and status code will be included in the response received from the API.

WithHttpInfo Variant RequestWithHttpInfo Variant Response

Copy

Copied

<?php

require_once __DIR__ . "/vendor/autoload.php";

$config = Dropbox\Sign\Configuration::getDefaultConfiguration();

$config->setUsername("YOUR_API_KEY");

$signatureRequestApi = new Dropbox\Sign\Api\SignatureRequestApi($config);

$data = new Dropbox\Sign\Model\SignatureRequestRemindRequest();
$data->setEmailAddress("john@example.com");

$signatureRequestId = "2f9781e1a8e2045224d808c153c2e1d3df6f8f2f";

try {
    // No HTTP headers included:
    // $result = $signatureRequestApi->signatureRequestGet($signatureRequestId);

    $result = $signatureRequestApi->signatureRequestGetWithHttpInfo($signatureRequestId);
    print_r($result);
} catch (Dropbox\Sign\ApiException $e) {
    $error = $e->getResponseObject();
    echo "Exception when calling Dropbox Sign API: "
        . print_r($error->getError());
}

Copy

Copied

[0] => Dropbox\Sign\Model\SignatureRequestGetResponse Object
  (...)
[1] => 200
[2] => Array(
  // ...
  [X-Ratelimit-Limit] => Array(
    [0] => 100
  )
  [X-Ratelimit-Limit-Remaining] => Array(
    [0] => 99
  )
  [X-Ratelimit-Reset] => Array(
    [0] => 1667941374
  )
  // ...
)

Note

You can also get the last response object that includes body, status code, and headers, using the ::getResponse() method against an API object: $response = $signatureRequestApi->getResponse();

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

$request->setFormFieldsPerDocument(
    [
        [ //document 1
            [ //field 1
                "api_id"   => $random_prefix . "_1",
                "name"     => "",
                "type"     => "text",
                "x"        => 112,
                "y"        => 328,
                "width"    => 100,
                "height"   => 16,
                "required" => true,
                "signer"   => 0
            ],
            [ //field 2
                "api_id"   => $random_prefix . "_2",
                "name"     => "",
                "type"     => "signature",
                "x"        => 530,
                "y"        => 415,
                "width"    => 150,
                "height"   => 30,
                "required" => true,
                "signer"   => 1
            ],
        ],
    ],
);

Copy

Copied

<?php

require_once __DIR__ . "/vendor/autoload.php";

$config = Dropbox\Sign\Configuration::getDefaultConfiguration();

$config->setUsername("YOUR_API_KEY");

$signatureRequestApi = new Dropbox\Sign\Api\SignatureRequestApi($config);

$data = new Dropbox\Sign\Model\SignatureRequestSendRequest();
$data->setFormFieldsPerDocument([
    Dropbox\Sign\Model\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"
    ]),
    Dropbox\Sign\Model\SubFormFieldsPerDocumentTextMerge::init([
        "document_index" => 0,
        "api_id"         => "5678yuio",
        "name"           => "Address",
        "required"       => true,
        "signer"         => 0,
        "width"          => 100,
        "height"         => 16,
        "x"              => 222,
        "y"              => 700,
        "page"           => 1,
    ]),
    Dropbox\Sign\Model\SubFormFieldsPerDocumentSignature::init([
        "document_index" => 0,
        "api_id"         => "zxcvuip",
        "required"       => true,
        "signer"         => 1,
        "width"          => 150,
        "height"         => 30,
        "x"              => 400,
        "y"              => 715,
        "page"           => 2,
    ]),
]);

try {
    $result = $signatureRequestApi->signatureRequestSend($data);

    print_r($result);
} catch (Dropbox\Sign\ApiException $e) {
    $error = $e->getResponseObject();
    echo "Exception when calling Dropbox Sign API: "
        . print_r($error->getError());
}

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\Model\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" => "jill@example.com",
            "name" => "Jill",
            "order" => 1,
        ],
    ],
    "files"                    => [new SplFileObject(__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\Model\SubFormFieldsPerDocumentSignature::init([
    "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 = new Dropbox\Sign\Model\SubFormFieldsPerDocumentSignature();
$form_field_1->setDocumentIndex(0)
    ->setApiId("4688957689")
    ->setName("signature1")
    ->setX(5)
    ->setY(7)
    ->setWidth(60)
    ->setHeight(30)
    ->setRequired(true)
    ->setSigner(0)
    ->setPage(1);

Form Fields per Document Examples using the new SDK:

SignatureInitialsDate SignedTextText MergeCheckboxCheckbox MergeDropdownHyperlinkRadio

Copy

Copied

$form_field_1 = Dropbox\Sign\Model\SubFormFieldsPerDocumentSignature::init([
    "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\Model\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\Model\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\Model\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\Model\SubCustomField::init([
    "name"  => "first_name",
    "value" => "John"
]);

$form_field_1 = Dropbox\Sign\Model\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\Model\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\Model\SubCustomField::init([
    "name"  => "is_registered",
    "value" => "1"
]);

$form_field_1 = Dropbox\Sign\Model\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\Model\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\Model\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\Model\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\Model\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\Model\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

<?php

require_once __DIR__ . "/vendor/autoload.php";

$config = Dropbox\Sign\Configuration::getDefaultConfiguration();

$config->setUsername("YOUR_API_KEY");

$signatureRequestApi = new Dropbox\Sign\Api\SignatureRequestApi($config);

$data = new Dropbox\Sign\Model\SignatureRequestSendWithTemplateRequest();
$data->setTemplateIds(["c26b8a16784a872da37ea946b9ddec7c1e11dff6"])
    ->setSubject("Purchase Order")
    ->setMessage("Glad we could come to an agreement.")
    ->setSigners([
        Dropbox\Sign\Model\SubSignatureRequestTemplateSigner::init([
            "role"          => "Client",
            "name"          => "George",
            "email_address" => "george@example.com",
        ]),
        Dropbox\Sign\Model\SubSignatureRequestTemplateSigner::init([
            "role"          => "Manager",
            "name"          => "Bob",
            "email_address" => "bob@example.com",
        ]),
    ]);

try {
    $result = $signatureRequestApi->signatureRequestSendWithTemplate($data);
    print_r($result);
} catch (Dropbox\Sign\ApiException $e) {
    $error = $e->getResponseObject();
    echo "Exception when calling Dropbox Sign API: "
        . print_r($error->getError());
}

Copy

Copied

<?php

require_once __DIR__ . "/vendor/autoload.php";

$config = Dropbox\Sign\Configuration::getDefaultConfiguration();

$config->setUsername("YOUR_API_KEY");

$signatureRequestApi = new Dropbox\Sign\Api\SignatureRequestApi($config);

$signer1 = new Dropbox\Sign\Model\SubSignatureRequestTemplateSigner();
$signer1->setRole("Client")
    ->setEmailAddress("george@example.com")
    ->setName("George");

$signer2 = new Dropbox\Sign\Model\SubSignatureRequestTemplateSigner();
$signer2->setRole("Manager")
    ->setEmailAddress("bob@example.com")
    ->setName("Bob");

$data = new Dropbox\Sign\Model\SignatureRequestSendWithTemplateRequest();
$data->setTemplateIds(["c26b8a16784a872da37ea946b9ddec7c1e11dff6"])
    ->setSubject("Purchase Order")
    ->setMessage("Glad we could come to an agreement.")
    ->setSigners([$signer1, $signer2]);

try {
    $result = $signatureRequestApi->signatureRequestSendWithTemplate($data);
    print_r($result);
} catch (Dropbox\Sign\ApiException $e) {
    $error = $e->getResponseObject();
    echo "Exception when calling Dropbox Sign API: "
        . print_r($error->getError());
}

"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

<?php

require_once __DIR__ . "/vendor/autoload.php";

$config = Dropbox\Sign\Configuration::getDefaultConfiguration();

$config->setUsername("YOUR_API_KEY");

$signatureRequestApi = new Dropbox\Sign\Api\SignatureRequestApi($config);

$data = new Dropbox\Sign\Model\SignatureRequestSendWithTemplateRequest();
$data->setTemplateIds(["c26b8a16784a872da37ea946b9ddec7c1e11dff6"])
    ->setSubject("Purchase Order")
    ->setMessage("Glad we could come to an agreement.")
    ->setSigners([
        Dropbox\Sign\Model\SubSignatureRequestTemplateSigner::init([
            "role"          => "Client",
            "name"          => "George",
            "email_address" => "george@example.com",
        ]),
        Dropbox\Sign\Model\SubSignatureRequestTemplateSigner::init([
            "role"          => "Manager",
            "name"          => "Bob",
            "email_address" => "bob@example.com",
        ]),
    ])
    ->setCcs([
        Dropbox\Sign\Model\SubCC::init([
            "role"          => "Client",
            "email_address" => "george@example.com",
        ]),
        Dropbox\Sign\Model\SubCC::init([
            "role"          => "Manager",
            "email_address" => "bob@example.com",
        ]),
    ]);

try {
    $result = $signatureRequestApi->signatureRequestSendWithTemplate($data);
    print_r($result);
} catch (Dropbox\Sign\ApiException $e) {
    $error = $e->getResponseObject();
    echo "Exception when calling Dropbox Sign API: "
        . print_r($error->getError());
}

Copy

Copied

<?php

require_once __DIR__ . "/vendor/autoload.php";

$config = Dropbox\Sign\Configuration::getDefaultConfiguration();

$config->setUsername("YOUR_API_KEY");

$signatureRequestApi = new Dropbox\Sign\Api\SignatureRequestApi($config);

$signer1 = new Dropbox\Sign\Model\SubSignatureRequestTemplateSigner();
$signer1->setRole("Client")
    ->setEmailAddress("george@example.com")
    ->setName("George");

$signer2 = new Dropbox\Sign\Model\SubSignatureRequestTemplateSigner();
$signer2->setRole("Manager")
    ->setEmailAddress("bob@example.com")
    ->setName("Bob");

$cc1 = Dropbox\Sign\Model\SubCC::init([
    "role"          => "Client",
    "email_address" => "george@example.com",
]);

$cc2 = Dropbox\Sign\Model\SubCC::init([
    "role"          => "Manager",
    "email_address" => "bob@example.com",
]);

$data = new Dropbox\Sign\Model\SignatureRequestSendWithTemplateRequest();
$data->setTemplateIds(["c26b8a16784a872da37ea946b9ddec7c1e11dff6"])
    ->setSubject("Purchase Order")
    ->setMessage("Glad we could come to an agreement.")
    ->setSigners([$signer1, $signer2])
    ->setCCs([$cc1, $cc2]);

try {
    $result = $signatureRequestApi->signatureRequestSendWithTemplate($data);
    print_r($result);
} catch (Dropbox\Sign\ApiException $e) {
    $error = $e->getResponseObject();
    echo "Exception when calling Dropbox Sign API: "
        . print_r($error->getError());
}

"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

<?php

require_once __DIR__ . "/vendor/autoload.php";

$config = Dropbox\Sign\Configuration::getDefaultConfiguration();

$config->setUsername("YOUR_API_KEY");

$signatureRequestApi = new Dropbox\Sign\Api\SignatureRequestApi($config);

$data = new Dropbox\Sign\Model\SignatureRequestSendWithTemplateRequest();
$data->setTemplateIds(["c26b8a16784a872da37ea946b9ddec7c1e11dff6"])
    ->setSubject("Purchase Order")
    ->setMessage("Glad we could come to an agreement.")
    ->setSigners([
        Dropbox\Sign\Model\SubSignatureRequestTemplateSigner::init([
            "role"          => "Client",
            "name"          => "George",
            "email_address" => "george@example.com",
        ]),
        Dropbox\Sign\Model\SubSignatureRequestTemplateSigner::init([
            "role"          => "Manager",
            "name"          => "Bob",
            "email_address" => "bob@example.com",
        ]),
    ])
    ->setCustomFields([
        Dropbox\Sign\Model\SubCustomField::init([
            "name"     => "company",
            "value"    => "ABC Corp",
            "required" => true,
        ]),
    ]);

try {
    $result = $signatureRequestApi->signatureRequestSendWithTemplate($data);
    print_r($result);
} catch (Dropbox\Sign\ApiException $e) {
    $error = $e->getResponseObject();
    echo "Exception when calling Dropbox Sign API: "
        . print_r($error->getError());
}

Copy

Copied

<?php

require_once __DIR__ . "/vendor/autoload.php";

$config = Dropbox\Sign\Configuration::getDefaultConfiguration();

$config->setUsername("YOUR_API_KEY");

$signatureRequestApi = new Dropbox\Sign\Api\SignatureRequestApi($config);

$signer1 = new Dropbox\Sign\Model\SubSignatureRequestTemplateSigner();
$signer1->setRole("Client")
    ->setEmailAddress("george@example.com")
    ->setName("George");

$signer2 = new Dropbox\Sign\Model\SubSignatureRequestTemplateSigner();
$signer2->setRole("Manager")
    ->setEmailAddress("bob@example.com")
    ->setName("Bob");


$custom_field_1 = Dropbox\Sign\Model\SubCustomField::init([
    "name"     => "company",
    "value"    => "ABC Corp",
    "required" => true,
]);

$data = new Dropbox\Sign\Model\SignatureRequestSendWithTemplateRequest();
$data->setTemplateIds(["c26b8a16784a872da37ea946b9ddec7c1e11dff6"])
    ->setSubject("Purchase Order")
    ->setMessage("Glad we could come to an agreement.")
    ->setSigners([$signer1, $signer2])
    ->setCustomFields([$custom_field_1]);

try {
    $result = $signatureRequestApi->signatureRequestSendWithTemplate($data);
    print_r($result);
} catch (Dropbox\Sign\ApiException $e) {
    $error = $e->getResponseObject();
    echo "Exception when calling Dropbox Sign API: "
        . print_r($error->getError());
}

`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 ->setFiles([...]);

`file_url` to `file_urls`

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

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 version	New SDK Version
A file path was passed into the `addFile()` and `setLogo()` methods.	An `SplFileObject` object must be created and then passed into the `setFiles()` or `setCustomLogoFile()` methods.

Legacy SDK - File UploadsNew SDK - File Uploads

Copy

Copied

// Signature request
$request->addFile('nda.pdf'); // Adding file from local;

// API app request
$request->setLogo('logo_file.png'); // Adding file from local;

Copy

Copied

// Signature request
...
->setFiles([new SplFileObject(__DIR__ . "/nda.pdf")])
...

// API app request
...
->setCustomLogoFile(new SplFileObject(__DIR__ . "/logo_file.png"))
...

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	New SDK
A single method (`getFiles()`) would be called to retrieve files. If a local destination path and a file type (PDF or ZIP) were passed into the method, a binary stream would be returned to save locally. If no local destination path nor file type were passed, an auto-generated URL would be returned.	Three separate methods are introduced to retrieve files as either a binary stream, an auto-generated URL or as a `base64` string: `signatureRequestFiles()` `signatureRequestFilesAsFileUrl()` `signatureRequestFilesAsDataUri()`

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

Copy

Copied

// Binary stream
$client->getFiles(
    $signature_request_id,
    "{$dest_file_path}/{$title}.zip",
    HelloSign\SignatureRequest::FILE_TYPE_ZIP
);

// Auto-generated URL
$client->getFiles($signature_request_id);

Copy

Copied

<?php

require_once __DIR__ . "/vendor/autoload.php";

$config = Dropbox\Sign\Configuration::getDefaultConfiguration();

$config->setUsername("YOUR_API_KEY");

$signatureRequestApi = new Dropbox\Sign\Api\SignatureRequestApi($config);

$signatureRequestId = "fa5c8a0b0f492d768749333ad6fcc214c111e967";
$fileType = "pdf";

try {
    $result = $signatureRequestApi->signatureRequestFiles($signatureRequestId, $fileType);
    copy($result->getRealPath(), __DIR__ . '/file_response.pdf');
} catch (Dropbox\Sign\ApiException $e) {
    $error = $e->getResponseObject();
    echo "Exception when calling Dropbox Sign API: "
        . print_r($error->getError());
}

Copy

Copied

<?php

require_once __DIR__ . "/vendor/autoload.php";

$config = Dropbox\Sign\Configuration::getDefaultConfiguration();

$config->setUsername("YOUR_API_KEY");

$signatureRequestApi = new Dropbox\Sign\Api\SignatureRequestApi($config);

$signatureRequestId = "fa5c8a0b0f492d768749333ad6fcc214c111e967";

try {
    $result = $signatureRequestApi->signatureRequestFilesAsDataUri($signatureRequestId);
    print_r($result);
} catch (Dropbox\Sign\ApiException $e) {
    $error = $e->getResponseObject();
    echo "Exception when calling Dropbox Sign API: "
        . print_r($error->getError());
}

Copy

Copied

<?php

require_once __DIR__ . "/vendor/autoload.php";

$config = Dropbox\Sign\Configuration::getDefaultConfiguration();

$config->setUsername("YOUR_API_KEY");

$signatureRequestApi = new Dropbox\Sign\Api\SignatureRequestApi($config);

$signatureRequestId = "fa5c8a0b0f492d768749333ad6fcc214c111e967";

try {
    $result = $signatureRequestApi->signatureRequestFilesAsFileUrl($signatureRequestId);
    print_r($result);
} catch (Dropbox\Sign\ApiException $e) {
    $error = $e->getResponseObject();
    echo "Exception when calling Dropbox Sign API: "
        . print_r($error->getError());
}

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->getTemplateFiles(
    $tenokate_id,
    "{$dest_file_path}/{$title}.zip",
    "pdf"
);

Copy

Copied

<?php

require_once __DIR__ . "/vendor/autoload.php";

$config = Dropbox\Sign\Configuration::getDefaultConfiguration();

$config->setUsername("YOUR_API_KEY");

$templateApi = new Dropbox\Sign\Api\TemplateApi($config);

$templateId = "5de8179668f2033afac48da1868d0093bf133266";
$fileType = "pdf";

try {
    $result = $templateApi->templateFiles($templateId, $fileType);
    copy($result->getRealPath(), __DIR__ . '/file_response.pdf');
} catch (Dropbox\Sign\ApiException $e) {
    $error = $e->getResponseObject();
    echo "Exception when calling Dropbox Sign API: "
        . print_r($error->getError());
}

Copy

Copied

<?php

require_once __DIR__ . "/vendor/autoload.php";

$config = Dropbox\Sign\Configuration::getDefaultConfiguration();

$config->setUsername("YOUR_API_KEY");

$templateApi = new Dropbox\Sign\Api\TemplateApi($config);

$templateId = "5de8179668f2033afac48da1868d0093bf133266";

try {
    $result = $templateApi->templateFilesAsDataUri($templateId);
    print_r($result);
} catch (Dropbox\Sign\ApiException $e) {
    $error = $e->getResponseObject();
    echo "Exception when calling Dropbox Sign API: "
        . print_r($error->getError());
}

Copy

Copied

<?php

require_once __DIR__ . "/vendor/autoload.php";

$config = Dropbox\Sign\Configuration::getDefaultConfiguration();

$config->setUsername("YOUR_API_KEY");

$templateApi = new Dropbox\Sign\Api\TemplateApi($config);

$templateId = "5de8179668f2033afac48da1868d0093bf133266";

try {
    $result = $templateApi->templateFilesAsFileUrl($templateId);
    print_r($result);
} catch (Dropbox\Sign\ApiException $e) {
    $error = $e->getResponseObject();
    echo "Exception when calling Dropbox Sign API: "
        . print_r($error->getError());
}

Endpoint Classes

Legacy SDK	New SDK
Requests to the API were made by calling methods within the `Client` object.	Each endpoint group has its own class. Within each class, there are specific methods for calls to every single API endpoint.

Legacy SDK - Endpoint ClassesNew SDK - Endpoint Classes

Copy

Copied

$client->createEmbeddedSignatureRequest($embedded_request);

$client->sendSignatureRequest($request);

$client->getSignatureRequest($signature_request_id);

$client->getAccount();

$client->getTemplate($templateId);

Copy

Copied

$config = Dropbox\Sign\Configuration::getDefaultConfiguration();
$config->setUsername("YOUR_API_KEY");

$embeddedSignatureRequest = new Dropbox\Sign\Api\SignatureRequestApi($config);
$data = new Dropbox\Sign\Model\SignatureRequestCreateEmbeddedRequest;
$embeddedSignatureRequest->signatureRequestCreateEmbedded($data);

$signatureRequestId = "SIGNATURE_REQUEST_ID";
$signatureRequest = new Dropbox\Sign\Api\SignatureRequestApi($config);
$signatureRequest->signatureRequestGet($signatureRequestId);

$signatureId = "SIGNATURE_ID";
$embeddedSignUrl = new Dropbox\Sign\Api\EmbeddedApi($config);
$embeddedSignUrl->embeddedSignUrl($signatureId);

$templateId = "TEMPLATE_ID";
$template = new Dropbox\Sign\Api\TemplateApi($config);
$template->templateGet($templateId);

$account = new Dropbox\Sign\Api\AccountApi($config);
$account->accountGet();

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.

Update API App with White Labeling Options

Legacy SDK - Update API AppNew SDK - Update API App

Copy

Copied

<?php

require_once 'vendor/autoload.php';

$client = new HelloSign\Client($apikey);

$clientId = "7deab03c18acf4097fb675f2a566d49f";

$apiApp = new ApiApp();
$apiApp->setName('Updating Name')
->setWhiteLabeling([
  "primary_button_color" => "#00B3E6",
  "primary_button_text_color" => "#FFFFFF"
])
->setLogo('my_company_logo.png');

$response = $client->updateApiApp($clientId, $apiApp);
print_r($response);

Copy

Copied

<?php

require_once __DIR__ . "/vendor/autoload.php";

$config = Dropbox\Sign\Configuration::getDefaultConfiguration();

$config->setUsername("YOUR_API_KEY");

// Create an API App object
$apiApp = new Dropbox\Sign\Api\ApiAppApi($config);

// Set the client ID of the app that will be getting updated
$clientId = "6dc20f9a710251b8bb6795ae8bf16";

// Set or update the custom logo
$customLogo = new SplFileObject(__DIR__ . "/my_company_logo.png");

// Create a white labeling object with the new or updated white labeling choices
$whiteLabelingOptions = new Dropbox\Sign\Model\SubWhiteLabelingOptions();
$whiteLabelingOptions->setPrimaryButtonColor("#00B3E6")
    ->setPrimaryButtonTextColor("#FFFFFF");

// Create an API App Update request object with the information for the request
$data = new Dropbox\Sign\Model\ApiAppUpdateRequest();
$data->setName("New Name")
    ->setWhiteLabelingOptions($whiteLabelingOptions)
    ->setCustomLogoFile($customLogo);

try {
    // Send the request to Dropbox Sign
    $result = $apiApp->apiAppUpdate($clientId, $data);
    print_r($result);
} catch (Dropbox\Sign\ApiException $e) {
    $error = $e->getResponseObject();
    echo "Exception when calling Dropbox Sign API: " . print_r($error->getError());
}

Embedded Signature Request and Get Sign URL

Legacy SDK - Embedded Signature RequestNew SDK - Embedded Signature RequestNew SDK - Embed Sig Req using init()

Copy

Copied

<?php
require_once 'vendor/autoload.php';

$client = new HelloSign\Client($apikey);

// Create the SignatureRequest object
$request = new HelloSign\SignatureRequest;
$request->enableTestMode();
$request->setTitle('NDA with Acme Co.');
$request->setSubject('The NDA we talked about');
$request->setMessage('Please sign this NDA and let\'s discuss.');
$request->addSigner('jack@example.com', 'Jack');
$request->addSigner('jill@example.com', 'Jill');
$request->addCC('lawyer@example.com');
$request->addFile('nda.pdf'); //Adding file from local

// Turn it into an embedded request
$embedded_request = new HelloSign\EmbeddedSignatureRequest($request, $client_id);

// Send it to HelloSign
$response = $client->createEmbeddedSignatureRequest($embedded_request);

// Grab the signature ID for the signature page that will be embedded in the
// page (for the demo, we'll just use the first one)
$signatures   = $response->getSignatures();
$signature_id = $signatures[0]->getId();

// Retrieve the URL to sign the document
$response = $client->getEmbeddedSignUrl($signature_id);

// Store it to use with the embedded.js HelloSign.open() call
$sign_url = $response->getSignUrl();

Copy

Copied

<?php

require_once __DIR__ . "/vendor/autoload.php";

$config = Dropbox\Sign\Configuration::getDefaultConfiguration();

$config->setUsername("YOUR_API_KEY");

// Create a Signature Request object and an Embedded Object
$embeddedSignatureRequest = new Dropbox\Sign\Api\SignatureRequestApi($config);
$embeddedSignUrl = new Dropbox\Sign\Api\EmbeddedApi($config);

// Create the signer(s) object(s)
$signer1 = new Dropbox\Sign\Model\SubSignatureRequestSigner();
$signer1->setEmailAddress("jack@example.com")
    ->setName("Jack")
    ->setOrder(0);

$signer2 = new Dropbox\Sign\Model\SubSignatureRequestSigner();
$signer2->setEmailAddress("jill@example.com")
    ->setName("Jill")
    ->setOrder(1);

// Create a form fields per document object (optional)
$signatureField4 = new Dropbox\Sign\Model\SubFormFieldsPerDocumentSignature();
$signatureField4->setApiId("n0ug4r07")
    ->setHeight(16)
    ->setWidth(100)
    ->setRequired(true)
    ->setSigner(2)
    ->setX(200)
    ->setY(715)
    ->setPage(1)
    ->setDocumentIndex(0);

// Create an Embedded Signature Request object with the information for the request
$data = new Dropbox\Sign\Model\SignatureRequestCreateEmbeddedRequest();
$data->setClientId("YOUR_CLIENT_ID")
    ->setTitle("NDA with Acme Co.")
    ->setSubject("The NDA we talked about")
    ->setMessage("Please sign this NDA and then we can discuss more. Let me know if you have any questions.")
    ->setSigners([$signer1, $signer2]) // Signer objects
    ->setFileUrls(["https://app.hellosign.com/docs/example_signature_request.pdf"])
    // Adding file from local
    //    ->setFiles([new SplFileObject(__DIR__ . "/Mutual-Non-Disclosure-Agreement.pdf")])
    ->setMetadata(["key1" => "metadata1", "key2" => "metadata2"])
    ->setFormFieldsPerDocument([
        // field 1
        Dropbox\Sign\Model\SubFormFieldsPerDocumentText::init([
            "document_index"  => 0,
            "api_id"          => "4lyx",
            "required"        => true,
            "signer"          => 0,
            "width"           => 100,
            "height"          => 16,
            "x"               => 112,
            "y"               => 700,
            "page"            => 1,
            "placeholder"     => "Full Name",
            "validation_type" => "letters_only"
        ]),
        // field 2
        Dropbox\Sign\Model\SubFormFieldsPerDocumentTextMerge::init([
            "document_index" => 0,
            "api_id"         => "pupp37",
            "name"           => "Address",
            "required"       => true,
            "signer"         => 0,
            "width"          => 100,
            "height"         => 16,
            "x"              => 222,
            "y"              => 700,
            "page"           => 1,
        ]),
        // field 3
        Dropbox\Sign\Model\SubFormFieldsPerDocumentSignature::init([
            "document_index" => 0,
            "api_id"         => "s0n4",
            "required"       => true,
            "signer"         => 1,
            "width"          => 150,
            "height"         => 30,
            "x"              => 400,
            "y"              => 715,
            "page"           => 2,
        ]),
        // field 4
        $signatureField4 // Object created above
    ])
    ->setCustomFields([
        Dropbox\Sign\Model\SubCustomField::init([
            "name"  => "Address",
            "value" => "123 Happy Ln.",
        ])
    ])
    ->setTestMode(true);

try {
    // Send the request to Dropbox Sign
    $result = $embeddedSignatureRequest->signatureRequestCreateEmbedded($data);

    // Signature information is an array of objects
    foreach ($result->getSignatureRequest()->getSignatures() as $signature) {
        // Retrieve each signers' signature ID
        $signatureId = $signature->getSignatureId();

        // Retrieve each signers' sign_url
        try {
            $embeddedSignUrlResponse = $embeddedSignUrl->embeddedSignUrl($signatureId);

            $signUrl = $embeddedSignUrlResponse->getEmbedded()->getSignUrl();

            print_r("\n{$signUrl}\n");
        } catch (Dropbox\Sign\ApiException $e) {
            $error = $e->getResponseObject();
            echo "Exception when calling Dropbox Sign API: "
                . print_r($error->getError());
        }
    }
} catch (Dropbox\Sign\ApiException $e) {
    $error = $e->getResponseObject();
    echo "Exception when calling Dropbox Sign API: "
        . print_r($error->getError());
}

Copy

Copied

<?php

require_once __DIR__ . "/vendor/autoload.php";

$config = Dropbox\Sign\Configuration::getDefaultConfiguration();

$config->setUsername("YOUR_API_KEY");

// Create a Signature Request object and an Embedded Object
$embeddedSignature = new Dropbox\Sign\Api\SignatureRequestApi($config);
$embeddedSignUrl = new Dropbox\Sign\API\EmbeddedApi($config);

// Create an Embedded Signature Request object with the information for the request
$data = Dropbox\Sign\Model\SignatureRequestCreateEmbeddedRequest::init([
    "title"     => "NDA with Acme Co.",
    "signers"   => [
        [
            "name"          => "Jack",
            "email_address" => "jack@example.com"
        ],
        [
            "name"          => "Jill",
            "email_address" => "jill@example.com"
        ]
    ],
    "file"      => [
        new SplFileObject(__DIR__ . "/file.pdf")
    ],
    "client_id" => "YOUR_CLIENT_ID"
]);

try {
    // Send the request to Dropbox Sign
    $result = $embeddedSignature->signatureRequestCreateEmbedded($data);

    // Signature information is an array of objects
    foreach ($result->getSignatureRequest()->getSignatures() as $signature) {
        // Retrieve each signers' signature ID
        $signatureId = $signature->getSignatureId();

        // Retrieve each signers' sign_url
        try {
            $embeddedSignUrlResponse = $embeddedSignUrl->embeddedSignUrl($signatureId);

            $signUrl = $embeddedSignUrlResponse->getEmbedded()->getSignUrl();

            print_r("\n{$signUrl}\n");
        } catch (Dropbox\Sign\ApiException $e) {
            $error = $e->getResponseObject();
            echo "Exception when calling Dropbox Sign API: "
                . print_r($error->getError());
        }
    }
} catch (Dropbox\Sign\ApiException $e) {
    $error = $e->getResponseObject();
    echo "Exception when calling Dropbox Sign API: "
        . print_r($error->getError());
}

Get Signature Request

Legacy SDK - Get Signature RequestNew SDK - Get Signature Request

Copy

Copied

<?php

require_once 'vendor/autoload.php';

$client = new HelloSign\Client($apikey);

$response = $client->getSignatureRequest($signature_request_id);
print_r($response);

Copy

Copied

<?php

require_once __DIR__ . "/vendor/autoload.php";

$config = Dropbox\Sign\Configuration::getDefaultConfiguration();

$config->setUsername("YOUR_API_KEY");

// Create a Signature Request object
$signatureRequest = new Dropbox\Sign\Api\SignatureRequestApi($config);

$signatureRequestId = "fa5c8a0b0f492d768749333ad6fcc214c111e967";

try {
    $result = $signatureRequest->signatureRequestGet($signatureRequestId);
    // or WithHttpInfo() to include HTTP info in the response:
    // $result = $signatureRequest->signatureRequestGetWithHttpInfo($signatureRequestId);
    print_r($result);
} catch (Dropbox\Sign\ApiException $e) {
    $error = $e->getResponseObject();
    echo "Exception when calling Dropbox Sign API: "
        . print_r($error->getError());
}

Get Template

Legacy SDK - Get TemplateNew SDK - Get Template

Copy

Copied

<?php
require_once 'vendor/autoload.php';

$client = new HelloSign\Client($apikey);

$templateId = '11b77b90f5e7156d961d4bbe26b872ca04edddbb';

$response = $client->getTemplate($templateId);

print_r($response);
print_r($response->getTitle());
print_r($response->getSignerRoles());

Copy

Copied

<?php

require_once __DIR__ . "/vendor/autoload.php";

$config = Dropbox\Sign\Configuration::getDefaultConfiguration();

$config->setUsername("YOUR_API_KEY");

// Create a Template object
$template = new Dropbox\Sign\Api\TemplateApi($config);

$templateId = "f57db65d3f933b5316d398057a36176831451a35";

try {
    // Send the request to Dropbox Sign
    $result = $template->templateGet($templateId);

    // Store the template object from the response
    $templateObj = $result->getTemplate();
    // Retrieve the Template's title from the template object
    $templateTitle = $templateObj->getTitle();
    // Retrieve the Template's metadata (if any) from the template object
    $templateMetadata = json_encode($templateObj->getMetadata());
    // Retrieve the signer role(s) from the template object
    $templateSignerRoles = json_encode($templateObj->getSignerRoles());

    print_r("
        Template Title: {$templateTitle}\n
        Template Metadata: {$templateMetadata}\n
        Template Signer Roles: {$templateSignerRoles}\n
    ");
} catch (Dropbox\Sign\ApiException $e) {
    $error = $e->getResponseObject();
    echo "Exception when calling Dropbox Sign API: "
        . print_r($error->getError());
}

Send Signature Request with Template

Legacy SDK - Send Signature Request with TemplateNew SDK - Send Signature Request with Template

Copy

Copied

$request = new HelloSign\TemplateSignatureRequest;
$request->enableTestMode();
$request->setTemplateId($template->getId());
$request->setSubject('Purchase Order');
$request->setMessage('Glad we could come to an agreement.');
$request->setSigner('Client', 'george@example.com', 'George');
$request->setCC('Accounting', 'accounting@example.com');
$request->setCustomFieldValue('Cost', '$20,000');

$response = $client->sendTemplateSignatureRequest($request);

Copy

Copied

<?php

require_once __DIR__ . "/vendor/autoload.php";

$config = Dropbox\Sign\Configuration::getDefaultConfiguration();

$config->setUsername("YOUR_API_KEY");

$signatureRequest = new Dropbox\Sign\Api\SignatureRequestApi($config);

$templateId = "7e29568acd78c947b81afa2876ff07e245b";

// Create the signer(s) objects
$signer1 = new Dropbox\Sign\Model\SubSignatureRequestTemplateSigner();
$signer1->setRole("Role1")
    ->setEmailAddress("jill@example.com")
    ->setName("Jill");

$signer2 = new Dropbox\Sign\Model\SubSignatureRequestTemplateSigner();
$signer2->setRole("Role2")
    ->setEmailAddress("jack@example.com")
    ->setName("Jack");

// Create a custom_fields object
$customFields = new Dropbox\Sign\Model\SubCustomField();
$customFields->setName("Cost")
    ->setValue("$20,000");

// Create an Signature Request with Template object with the information for the request
$data = new Dropbox\Sign\Model\SignatureRequestSendWithTemplateRequest();
$data->setTemplateIds([$templateId])
    ->setTitle("Purchase Order")
    ->setMessage("Glad we could come to an agreement.")
    ->setSigners([$signer1, $signer2])
    ->setCustomFields([
        $customFields
    ])
    ->setTestMode(true);

try {
    // Send the request to Dropbox Sign
    $result = $signatureRequest->signatureRequestSendWithTemplate($data);
    print_r($result);
} catch (Dropbox\Sign\ApiException $e) {
    $error = $e->getResponseObject();
    echo "Exception when calling Dropbox Sign API: " . print_r($error->getError());
}

Get Account

Legacy SDK - Get AccountNew SDK - Get Account

Copy

Copied

<?php
require_once 'vendor/autoload.php';

$client = new HelloSign\Client($apikey);

$account = $client->getAccount();

print_r($account->toArray());

Copy

Copied

<?php

require_once __DIR__ . "/vendor/autoload.php";

$config = Dropbox\Sign\Configuration::getDefaultConfiguration();

$config->setUsername("YOUR_API_KEY");

// Create an Account object
$account = new Dropbox\Sign\Api\AccountApi($config);

try {
    // Send the request to Dropbox Sign
    $result = $account->accountGet();

    // Store the account response object
    $accountObj = $result->getAccount();
    // Retrieve the account ID from the account object
    $accountId = $accountObj->getAccountId();
    // Retrieve the account's email address from the account object
    $accountEmailAddress = $accountObj->getEmailAddress();

    print_r($accountObj);
    print_r("
        Account ID: {$accountId} \n
        Account Email Address: {$accountEmailAddress}
    ");
} catch (Dropbox\Sign\ApiException $e) {
    $error = $e->getResponseObject();
    echo "Exception when calling Dropbox Sign API: "
        . print_r($error->getError());
}

Download Files

Legacy SDK - Download FilesNew SDK - Binary StreamNew SDK - Auto-generated URLNew SDK - Base64 String

Copy

Copied

<?php

require_once 'vendor/autoload.php';

$client = new HelloSign\Client($apikey);

$signature_request_id = "e541d3d8df85c8e944f0793c8530e915d750";

// Retrieve the signature request object
$response = $client->getSignatureRequest($signature_request_id);

// Set the destination path for the file
$dest_file_path = 'Signature Request Files';
// Retrieve the title from the signature request object
$title = $response->getTitle();

// Save the file locally
$client->getFiles(
    $signature_request_id,
    "{$dest_file_path}/{$title}.zip",
    HelloSign\SignatureRequest::FILE_TYPE_ZIP
);

// Or

// Retrieve an auto-generated URL
$client->getFiles($signature_request_id);

Copy

Copied

<?php

require_once __DIR__ . "/vendor/autoload.php";

$config = Dropbox\Sign\Configuration::getDefaultConfiguration();

$config->setUsername("YOUR_API_KEY");

// Create a Signature Request object
$signatureRequest = new Dropbox\Sign\Api\SignatureRequestApi($config);

$signatureRequestId = "fa5c8a0b0f492d768749333ad6fcc214c111e967";

try {
    // Create a Signature Request object containing the data for the signature request (optional)
    $sigReqObj = $signatureRequest->signatureRequestGet($signatureRequestId);
    // Save the title for later use to save file (optional)
    $title = $sigReqObj->getSignatureRequest()
        ->getTitle();

    // Send the request to Dropbox Sign
    $result = $signatureRequest->signatureRequestFiles($signatureRequestId);

    // For a ZIP file:
    // $result = $signatureRequest->signatureRequestFiles($signatureRequestId, "zip");

    // Save the file
    copy($result->getRealPath(), __DIR__ . '/file_response.pdf');

    // For a ZIP file:
    // copy($result->getRealPath(), __DIR__ . '/file_response.zip');

} catch (Dropbox\Sign\ApiException $e) {
    $error = $e->getResponseObject();
    echo "Exception when calling Dropbox Sign API: "
        . print_r($error->getError());
}

Copy

Copied

<?php

require_once __DIR__ . "/vendor/autoload.php";

$config = Dropbox\Sign\Configuration::getDefaultConfiguration();

$config->setUsername("YOUR_API_KEY");

// Create a Signature Request object
$signatureRequest = new Dropbox\Sign\Api\SignatureRequestApi($config);

$signatureRequestId = "fa5c8a0b0f492d768749333ad6fcc214c111e967";

try {
    // Send the request to Dropbox Sign
    $result = $signatureRequest->signatureRequestFilesAsFileUrl($signatureRequestId);
    print_r($result);
} catch (Dropbox\Sign\ApiException $e) {
    $error = $e->getResponseObject();
    echo "Exception when calling Dropbox Sign API: "
        . print_r($error->getError());
}

Copy

Copied

<?php

require_once __DIR__ . "/vendor/autoload.php";

$config = Dropbox\Sign\Configuration::getDefaultConfiguration();

$config->setUsername("YOUR_API_KEY");

// Create a Signature Request object
$signatureRequest = new Dropbox\Sign\Api\SignatureRequestApi($config);

$signatureRequestId = "fa5c8a0b0f492d768749333ad6fcc214c111e967";

try {
    // Send the request to Dropbox Sign
    $result = $signatureRequest->signatureRequestFilesAsDataUri($signatureRequestId);
    print_r($result);
} catch (Dropbox\Sign\ApiException $e) {
    $error = $e->getResponseObject();
    echo "Exception when calling Dropbox Sign API: "
        . print_r($error->getError());
}

Supporting Legacy SDKs

Following the official release of the new SDK version, we'll be preparing to deprecate all legacy versions of the PHP 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.8.0 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 PHP SDK happens in the PHP folder of the repo.

PHP Migration Guide

Migrating the PHP SDK from hellosign/hellosign-php-sdk to dropbox/sign

Architecture and Tooling

SDK Resources

Core Concepts and Patterns

Installation

Install from Packagist

Build from Source

Importing the SDK

Legacy SDK

New 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

HTTP Header Info

Note

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

Downloading Files

Endpoint Classes

Endpoint Mapping

Update API App with White Labeling Options

Embedded Signature Request and Get Sign URL

Get Signature Request

Get Template

Send Signature Request with Template

Get Account

Download Files

Supporting Legacy SDKs

Feedback and Assistance

Migrating the PHP SDK from `hellosign/hellosign-php-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`