Upgrading from v1.x to v3

📘

Goodbye to v1.x: Embrace the Advanced v3 Version!

We want to thank you for being a valued user of the Signeasy API v1.x. However, as part of our ongoing efforts to upgrade and enhance our core platform, we have made the decision to deprecate the use of v1.x versions of the API.

We are excited to introduce you to the more advanced and powerful v3 version of the Signeasy API.
This migration guide will walk you through the process of transitioning from v1.x to v3, ensuring a seamless and enhanced experience.

What's new in 3.0?

Authentication & Authorization

With the new Signeasy API 3.0, you can leverage on and the existing to simplify your authorization flow based on the type of integration you are trying to develop.

What’s New in v3

The Signeasy API v3 brings a wealth of new features and improvements that empower your integrations and enhance your experience. Here are some highlights of what’s new in v3:

Developer Dashboard:

A new developer dashboard is available, providing you with a centralized hub to manage your applications and webhooks. This streamlined interface offers improved control and visibility over your integrations.

Improved Security:

We have implemented enhanced security measures in v3. Long-lived access tokens, which pose security risks, have been replaced with shorter expiry times. Access tokens now expire after 30 days for Client Credentials Flow and 1 hour for Authorization Code Flow. After expiration, tokens must be regenerated and refreshed based on the corresponding authorization flow.

Application-Level Webhooks:

With v3, you can create and manage application-level webhooks directly from the developer dashboard. This allows you to receive real-time notifications and streamline your workflow automation.

Test and Production Environment Management:

The developer portal now enables you to manage applications for both test and production environments within a single portal. This convenient feature facilitates efficient application configuration and deployment across different environments.

Now that you are familiar with the new features and improvements in v3, let's proceed with the migration process.

Migrate from v1.x to v3

Step 1: Accessing the Developer Portal

To facilitate a seamless migration, we have launched a new developer portal that puts you in full control of your applications and usage. To access the developer portal for testing, you can signup for a trial account with an email not already associated with Signeasy. We will migrate your current production account to v3 upon your confirmation of the testing.

Step 2: Migrating to the New Plan

We are introducing a new prepaid billing system. It automates usage tracking, simplifies billing, and ensures seamless API access. Purchase envelopes in advance based on your needs, eliminating surprises and allowing plan customization. Our team will assist you in transitioning to the new prepaid plan.

Step 3: Creating New Test and Live Applications

Once you have access to the developer portal, you can create test and live applications based on your specific requirements and scope. The developer portal allows you to manage your applications effectively and configure application-level webhooks. Refer to the documentation on creating applications for detailed instructions on setting up your applications within the portal.

Step 4: Revising and Implementing Client Credential Flow

With v3.0, the Signeasy API offers two types of authorization flows for improved flexibility and security. Reviewing your existing Client Credentials Flow and determining if any modifications are required to align with the new specifications is essential. The documentation on authentication and authorization provides detailed information on the available flows and their implementation.

Step 5: Modifying Endpoint URLs

To accommodate the changes introduced in the Signeasy API v3, you will need to update the endpoint URLs in your existing workflows. The new documentation provides the updated endpoint URLs for different functionalities. Please note that the create envelope endpoint for templates and original documents is now combined, and changes have been made to the download endpoint and the endpoint to fetch the status. Make the necessary modifications to ensure compatibility with the new API version.

The creation of an envelope using a template and originals can be done using the same endpoint now.

Step 6: Testing and Verification

After completing the migration steps outlined above, it is crucial to thoroughly test and verify your workflows. Ensure that all integrations are functioning as expected and validate the interactions with the Signeasy API v3. This testing phase will help identify and address any potential issues, ensuring a seamless transition to the new version.

Step 7: Migrating Production Account

Once you have successfully tested and verified your workflows, reach out to our team to initiate the migration of your current production account to the v3, after which you will get access to your production v3 tokens, which you can update in the workflows.