ISV Embed Implementation Plan

ISV Embed accounts, which are used by the ISV’s end customers, are limited to using only the ISV’s application. Additionally, these customers can only access the Docusign web application to view envelopes.

To develop an application, ISV Embed partners use two developer accounts and an organization:

• Create two developer accounts by selecting Developer Account at the top of any Developer Center page, then choose Create Account. You can also use the button below.

  Create account

• The email addresses used to create each account must be different (you can later add the first email address to the second account if you wish.) If your email system supports it, you can use + addressing to differentiate the two email addresses while receiving all of the emails in one inbox. For example, by using developer+1@example.com and developer+2@example.com.

The first developer account will be your primary account for developing and testing your application’s integration with Docusign. The Docusign partner team will modify it to become an ISV Embed account. Request this process by contacting the partner team.

• After your first account has been updated to be an ISV Embed account, Create an organization for the account. You do not need to Claim your domain, but it is recommended to do so. Note that claiming a domain in the developer environment does not also claim it for the production environment.
• After your organization has been created, contact the Partner Team again to authorize your demo organization for Account cloning. You will clone your account to provision each end customer.

The second developer account will be used only when you want to send envelopes from the Docusign web app for testing purposes.

Docusign developer accounts enable you to develop and test your app in an developer environment that’s isolated from the production environment. It’s also referred to as the demo environment or a demo account.

Developer accounts:

• Do not expire
• Do not incur subscription costs
• Can be enabled with full ISV Embed features (with a few exceptions)

You can create and work with any number of API integrations within your developer account. Each API integration is identified by an integration key (IK). Integration Keys are also called Client IDs per the OAuth specifications.

To create and configure integration keys for your accounts:

• Create an Integration Key (client ID) in your ISV Embed account (account 1.) Your integration key is configured with values used for OAuth 2.0 authentication:

  • Either a secret key or RSA key pair, depending on the OAuth flow used
  • A redirect URI that is used when obtaining consent and during some initial authentication steps

• If you don’t know which style of OAuth you’ll be using, accept the defaults and you can update the settings later.

When your application uses the Integration Key, users in Account 1 or 2 (or any other account on demo) can use your integration. However, users in Account 1, and users in other accounts that you create in Account 1’s organization can only use your application.

See Integration Keys Explained: A Practical Guide for ISVs for details and in-depth guidelines for working with Integration Keys as an ISV partner.

Review the key concepts and objects used on the Docusign eSignature platform, including:

• Envelopes
• Documents
• Recipients
• Tabs
• Templates
• Webhook status callbacks

Learn about key eSignature features you should consider supporting, key eSignature design options, and best practices for supporting Go-Live, Docusign Connect (webhooks), and installation.

Choose a Docusign plan that supports the features you need

Different ISV Embed plans include different product features. All of your end customers will use the same plan. Discuss your needs with your Partner Team contact.

Note that ISV Embed applications can notify agreement signers and other participants via email, they are not required to use Embedded signing nor embedded sending with their applications.

End Customer Configuration

Each of your end customers will have the same configuration:

• Each end customer will have their own eSignature account within your organization. This account’s users will only be able to use the Docusign web app to view envelopes; to send an agreement, they must use your application.
• The end customer’s account can be configured with the end customer’s corporate logo and branding colors.
• Each of the end customer employees who send out agreements for signature will have their own credentials (email/password) in the eSignature account, and can set their own profile photo.
• ISVs can also create “departmental” credentials for their customers that they can use for sending out agreements for signature. For example, “HR” with a departmental hr@end_customer.com email address.
• End customers may have additional Docusign accounts for their email/pw credentials. Do not assume that a default account is the one your application should use.

Design to support development

Prospective end customers will often like to try your application or its Docusign integration before purchasing. To support this, enable your production application to use either the Docusign production or developer (demo) site integration key. This enables your application (in a development environment) to send Docusign agreements at no charge.

To separate your use of the Docusign environments between development and sales demonstrations, you can create a third account in the developer environment with its own organization.

Join the Docusign Partner Program, if you haven’t already done so.

Becoming a partner grants you access to partner services and, as an ISV, must be completed before you move your integration into a production environment.

When embedding Docusign eSignature for your customers, there are constraints imposed on the integration. In the ISV Embed model, the ISV agrees to purchase an envelope subscription in order to embed Docusign eSignature functionality into their product as a service they provide to their end customers. The ISV Embed agreement limits use of Docusign to those use cases provided by the ISV’s application.

There are two key areas where ISV Embed integrations differ from other ISV integrations:

• The terms of accounts and users:

  • When an ISV’s end customer is using the ISV’s application, the end customers will be consuming the ISV’s envelopes, even if the customer is also a Docusign customer.
  • The ISV Embed Docusign accounts are not related to the end customer’s other Docusign accounts (if any).
  • The ISV owns the accounts in its Docusign organization and is responsible for controlling how the envelopes are used.

• The terms of data and privacy rights management

Guidance for creating accounts for Docusign ISV Embed products:

• An eSignature account in production is created for the ISV. This is the ISV’s primary account.
• The ISV creates an organization that includes the primary account.
• The ISV’s production-environment integration key must be managed by the primary account.
• The ISV creates a new eSignature account in the organization for each end customer by using the account cloning feature.
• Each end customer employee who sends agreements will have their own user membership in the account created for the end customer.

Note: the Docusign ISV Embed product was updated in October 2024 for new customers. This page is for new ISV partners. Existing ISV Embed partners should contact the partner team to discuss migration options.

Provisioning

The ISV will create and provision an eSignature account for each of their end customers.

As an ISV, you will provision each new end customer by:

1. Using the Account cloning feature to create a new account in the organization for the exclusive use of the new end customer. The account must be created in the end customer’s geographic region, such as, the US, the UK, etc.

   A new account must be created for each end customer, even if the end customer is only a single person.

   If the ISV’s billing agreement with Docusign is Pay as you go, then the organization can only be used if the new end customer is in the same geographic region as the ISV’s primary account. To create an account for a new end customer in a different geographic region, the ISV must create a new billing account, primary account, and organization for the new geographic region and its end customers. Contact the Partner team for more information.

   As an ISV, you can also optionally provision the new account programmatically by using the Admin API’s account clone method.

2. Creating an administrator user member in the new account with an email/password that is exclusively controlled by the ISV.

   • The same email/password can be used with multiple end customer accounts.
   • The admin account is used by the ISV’s customer service staff to solve problems. The application can also use it to look up end user information in the account programmatically.

3. Adding one or more user members to the new account for the agreement senders, representing the end customer’s employees who will send out agreements for signature.

   • The end customer employees’ real email addresses are used.
   • The end customer employees must be able access the specified email addresses.

4. Recording and associatinge the email, Docusign account’s account ID, and the base path for each of the users with the user’s data in the ISV application itself.

   • This data can be obtained from Docusign manually or programmatically.
   • ISVs must not assume that an end customer’s default eSignature account is the account to be used.

5. If your ISV application uses the OAuth JWT flow:

   • Obtain and record the user’s Docusign user ID (a guid value) along with the user’s record in the ISV application as mentioned above. The user ID can be obtained manually or programmatically.
   • Instruct the user to grant consent to the ISV’s application. For each end user, this is a one-time operation.

End customer users

As discussed above, each of the ISV’s end customers will have their own eSignature account and it will belong to the ISV’s organization.

Each of the end customer’s users who send out agreements will have their own eSignature email/password credentials. When the user logs into the Docusign web app with the account created by the ISV, they will not be able to send envelopes from the account. Instead, they can only send via the ISV’s application itself.

If the end customer’s user has another account purchased directly from Docusign, the user can send envelopes from that account.

Note: the ISV must not assume that a user’s default account is the account the ISV created. If the user has a second account purchased directly from Docusign, often that account will be the user’s default account.

Departmental users

Depending on the ISV’s application use case, some end customers may prefer to have their agreements sent from a departmental email address, such as hr@end_customer.com. To enable this, create a user membership in the end customer’s account with the desired departmental email address. This user membership will have its own password, and the end customer must have access to the departmental email account.

Personalization

Docusign recommends that the end customer accounts be personalized with the logo and color branding of the end customer. User members should be personalized by uploading a photo to Docusign. Docusign’s statistics show that agreements are completed faster when the sender’s account is personalized.

Data Protection

As an ISV, you are responsible for protecting the end customers’ data. You should implement processes and controls to ensure that ISV employees with access to either admin or system user credentials protect those credentials, and that access is properly revoked when employee assignments are changed. This should include closing admin users, adding new admin users, and updating system user passwords.

Sending envelopes

The following example steps show the process to send an envelope on behalf of an ISV application’s end customer “Newco” by end user “Pat Johnson”:

1. The ISV application looks up the end customer “Newco” in its database to retrieve the eSignature account ID, and base path.
2. If the ISV application uses the OAuth Authorization Code with Docusign, then the application prompts the end user to login to Docusign (if they haven’t previously) to obtain a Docusign access token for the end user. If the ISV application uses the JWT flow, it looks up the user ID for Pat Johnson from its database, then uses the JWT flow to obtain an access token representing the end user.
3. The ISV application creates and sends the envelope using the access token, account ID, and base path from the previous steps.

General Data Privacy

As an ISV providing Docusign eSign services to your Partner customers, you are responsible for providing data security and privacy through your business application interfaces. Ensuring data separation between your different Partner customers is essential. Leverage Docusign accounts and system users to maintain that separation for your business app users.

Because you, as an ISV, are providing services to the Partner customer, you are also responsible for handling data rights management requests as they relate to personally identifiable information (PII) data held in the Partner customer’s envelope transactions. Ensure that there is an accessible process for your Partner customers to handle such requests coming from their signers.

Data and Documents Handling

The ISV’s application can use Docusign as an archive system for completed agreements, or it can download the agreements to the application’s data store. Using Docusign as an archive system enables Docusign’s tools for managing and searching completed agreements to be used. There is no additional cost when completed documents are archived on Docusign.

Signer’s Rights

Signers and other recipients may have differing data privacy rights depending on the legal jurisdiction of the business transaction. These data subjects can exercise their data rights by contacting the business entity that holds and uses their data, the ISV Partner customer. The ISV should consider:

• How to facilitate the correct routing of the submitted data subject inquiries.
• Communicating procedures to signers via custom messaging in the email body or footers, footer links to the Partner customer support channel, and other clear ISV marketing and support mechanisms.
• How to ensure direct requests to the ISV Partner’s own support organization are handled properly.

Tools and Controls

As an ISV, you can use data rights management tools in the Docusign Settings to act on requests to remove privacy data. These are administrative tools and will require you to coordinate with the ISV Partner customer to determine the scope of envelopes to be addressed.

• **Purging Documents and Redaction:**An ISV account administrator can use the tools as described in Purging Envelopes to delete the envelope documents and metadata, and redact personally identifiable information from an envelope.
• **Retention Policy:**An ISV account administrator can use the account Retention Policy feature to automate a scheduled document and data purge for all envelopes as they reach a specific status. This can be aligned to a general privacy protection policy. It is essential that the Retention Policy only be used in conjunction with data and document export into the Business Application, as Docusign will not retain original copies.

End of Relationship

As an ISV, you should consider the envelope documents and data transacted through your Business Application as an extension of that application’s data. As such, you should create a data management plan for whether to or where to archive this data, including:

• Plans for when the system users representing the Partner customer are closed (to prevent further access).
• How the Partner customer is provided with their data for retention purposes and whether the ISV will exercise a purge of envelope documents, data, and redaction of PII.

The Docusign eSignature API offers three primary models for envelope creation. As a partner, you should use the composite template option that is appropriate for your one to many style integration. You can read more about composite templates in Step B.

• From a composite template, which allows for a combination of documents and templates
• With documents, recipients, and tabs.
• From a template.

Tab placement strategyYou can add documents to an envelope directly or by using a Docusign template. If your integration adds documents directly from your application, you have a few ways of assigning tabs to envelope recipients.

• Auto-place (anchor tagging)
• Account-level/server-side anchor tagging
• Fixed positioning
• PDF form field transformation

If you do not implement one of our tagging strategies, you should include our Sender View as part of your envelope creation and sending workflow. Failing to assign tags in your envelope, will result in a rejection during your Application Review prior to go-live.

Guidance on recipientsEvery envelope must have one or more recipients.

When working with recipients:

• Do not use the email address as the value for your recipient’s name.

Also, review each of the defined recipient types. Ignore the In Person type. If you have a reason for an In Person scenario, switch to Embedded signing instead.

Not all recipient types are available to all customers If you still have questions, check with Partner support to further understand which features/recipients are available in which commercial plans and subscriptions to determine exactly what you need in order to accommodate your workflows and use cases.

Recipient use case considerations When working with recipients, consider how you will address the following:

• Localization support: While signers can toggle the language used in the signing UI, the sender can influence the language used by default, as well as change the language used in the email, on a per-recipient basis. See emailNotification for details.
• Recipient authentication: If your use case or customers are in regulated industries, we strongly recommend adding additional recipient authentication options such as ID verification, phone authentication, or knowledge-based authentication.
• Docusign Standards-Based Signatures: If your signers are in regions that require a digital signature.
• Signing Group: You should give strong consideration to supporting this.
• Supplemental documents: If the use cases supported by your business application include sending supplementary or informational documents such as terms & conditions, disclosures, or non-actionable documents.

Sending an envelope

ISV Embed applications have two options for sending envelopes:

• Send via the API: Use the Envelopes:create API call to send the envelope. The ISV application can use templates to place the signing tabs (fields) and other types of tabs on the documents. The TemplateViews : createEdit embedded view can be used to present a template editing UX to the user. See the other sections of this guide for additional options.
• Create a draft envelope, then use the embedded sender view: Use the Envelopes:create API call to create a draft envelope. It is recommended to at a minimum, use the API to set the envelope’s documents, recipients, and meta-data. Then use the embedded sender view to enable the user to place the signing and other tabs on the document. Or the application can create the tabs on the document, and then the embedded sender view is used to position the tabs. Configure the sender view to only show the tagger page and to not allow the user to change the documents or recipients. See Embed the Sender and Correct views for details.

Composite templates are the most flexible and extensible of the ways that Docusign enables you to create envelopes. Building around the composite template model prevents having to do more work later in response to changing conditions and requirements.

For details on composite templates and how to use them, see the following resources.

• Composite templates
• How to request a signature using a composite template
• Why You Should Be Using the Composite Template Model
• Pro tips for working with composite templates, Part I
• Pro tips for working with composite templates, Part II
• Pro tips for working with composite templates, Part III
• From the Trenches: Composite templates
• Composite Templates: Custom Forms with Shared Signature Document in the MyAPICalls sample app

Your settings for creating envelopes determine what your users’ signing experience will be. Consider implementing the following features into your envelope creation workflow.

• Templates: One of Docusign’s most beloved and important features. While you may think at first that you’re not going to use templates, Docusign customers (especially if they are long time customers) frequently request them. Remember to include a roleName for your templates; it may look optional, but it’s important to add.
• Responsive signing: Can greatly improve your signing experience. When using responsive signing, remember that the document is a responsive signable HTML document.
• Auto Navigation: Can guide signers through the signing process.
• Consider allowing Signer reassign.
• Consider allowing Comments, unless you are using embedded signing. Comments facilitate collaboration between senders and signers, creating more successful transactions.
• Consider implementing access code authentication. Docusign offers many ways to authenticate a signer; access code is the only free type of recipient authentication. Save your team some time and include access code as an option.

Choose to use either remote signing or embedded signing. Where will your signers view and sign documents?

• If your signers are present and ready to sign immediately in the presence of your application, your integration can use embedded signing to have them sign directly within your workflow.
• Otherwise, you can use the default mode of remote signing, where the signer receives envelope notifications asynchronously from Docusign via email, SMS, or WhatsApp.

If your recipients are signing remotely, email is the default delivery mechanism. You should also consider supporting SMS delivery or WhatsApp.

Note: Envelopes can have a mix of embedded and remote signers if your workflow requires it.

For in-app signing, see the embedded signing overview.

Guidelines for embedded signing:

• In embedded signing, your integration’s app controls signer access. Because Docusign is not generating and sending email notifications with a unique link, Docusign is not validating that your specified recipient (name and email) has access to the email address. This means that it is your responsibility to provide some means of identifying the correct recipient for an envelope.
• In addition to your application’s authentication process, you can use Docusign authentication services via an embedded signing ceremony. For example, ask Docusign to request a pre-shared secret (an access code), or to send a code via SMS to the signer. Note that not all Docusign authentication options are available on all types of embedded signing ceremonies.
• You can record integration application authentication into the envelope record using the authenticationMethod, authenticationInstant, assertionId, and securityDomain properties. The provided values will be included in the envelope record and on the envelope’s Certificate of Completion, connecting integration application user authentication with the Docusign embedded signing session.
• authenticationMethod: Specifies how your app authenticated the embedded signing user. The value must be one of an enumerated value list of strings. This is a required element.
• authenticationInstant: Holds the date/time instant when the user was authenticated by the integration application. This is distinct from and should occur earlier than when the signing view methods are invoked.
• assertionId: Provides additional data for retrieving original authentication information.
• securityDomain: Specifies a location for authentication. This can be a URL, a subdomain, an office ID, a kiosk ID, or other identifier.

Important: Due to potential problems fitting an iframe into limited screen space, do not use iframes for embedded signing with the classic signing ceremony on mobile devices. Instead, use a new browser tab, a WkWebView for iOS devices, or a WebView for Android devices. The new Focused View signing ceremony can be used with a limited amount of GUI chrome provided by your application.

Example application authentication records

• This record holds data for an in-office visit where the signer’s identity was authenticated via their driver license, the time the ID was entered into the app by an advisor, and includes an office identifier.

• This record holds data for an online user login, specifying an authentication log archive ID, date-time instant, and sub-domain for archive lookup.

These four elements enable you to verify the signer entry, indicate how authentication took place, and record details for auditing.

If your integration needs to act or display status as your envelopes are viewed, signed, and completed, set up a Webhooks listener to receive updates when these events occur. To support all Docusign account types (including customer plans purchased from the website), use envelope-level webhooks and our Connect 2.0 event model.

For Docusign Connect, use the JSON SIM event model. Unlike messages in the previous supported formats, the JSON SIM message format is event-focused rather than envelope-focused. This means that:

• By default, rather than getting a summary of the envelope in each message, the message contains data about the triggering event. This means that each message is much smaller, more focused on the data you request, more customizable, and easier to process. Depending on the event type, you may choose to include the envelope summary as well.
• You can track and subscribe to more types of events.

As a security best practice, partners with one main account who must manage multiple client connect accounts, should configure your client accounts to be integrator managed, enabling you to use your main account’s OAuth for Connect settings for each client. This lets you configure and enforce using OAuth security for each client Connect account without having to set up each one manually. See Managing OAuth credentials for multiple accounts for details.

Once an envelope has been sent to your signer(s), your integration users should be able to continue to monitor and manage it through your app. Common scenarios include:

• Providing envelope status and progress
• Alerting to errors (rejected email address, signer failed recipient authentication, and more)
• A way to cancel a sent envelope (API)
• A way to correct a sent envelope (recipient name/email and other properties via API)
• Automated retrieval of envelope documents

For some of these events, you can use the Connect service to notify your app. Connect provides timely status notifications for your envelopes, triggered by recipient and envelope events.

• While polling via API can be used within limits, using the Connect service rather than consuming API calls is the best practice.
• For ISV integrations, you should use the eventNotification element to register for Connect directly rather than use an account-level configuration.

Best practices for envelope status notifications

• Get recipient/envelope status: Employ the Connect notification service to receive timely updates on envelope progress.
• Recipient issues (invalid email address, failed access): Use the Recipient Delivery Failed and Recipient Authentication Failure triggering event options in Connect.
• Void: Envelopes may need to be voided for a number of reasons. You can void envelopes with the Envelopes:update API method. If possible, correct or update the envelope rather than void it; this will save on envelope usage and reduce potential costs for your customers.
• Correct: If there is an error in a sent envelope, you can correct rather than void it. An integration can offer various forms of correction. A simple correction, such as changing an email address, resetting recipient authentication, or changing expiration and reminder frequency, can be done via a simple Envelopes:updateNotificationSettings API call. For more complex corrections, you can use the Correction view. If you choose to perform a complex correction directly via the API, you may want to obtain an envelope lock before making your API calls, then release it when you’re done.

See Envelopes:update for more information.

Your integration should be able to manage transaction records to retrieve or purge documents.

• Document Retrieval: Simply sending documents for signature is rarely sufficient for real-world apps. In most cases, you should return the completed documents (and perhaps the Certificate of Completion) to the integrated application. This improves your integrated app’s ease of use and reinforces it as the system of record. Your integrated application can use the Connect service to be notified about the final status of an envelope and use the API to retrieve the documents in your desired form (combined contiguous PDF, individual documents, or selective single documents). Note: You should consider retrieving the Certificate of Completion in cases where the envelope was voided or declined, as well as completed. See EnvelopeDocuments:get for details on retrieving documents.
• Purge: Depending on your location and requirements, your app may need to be able to purge records to support GDPR regulations or legal rights to be forgotten.