This guide for API V2 customers outlines the migration process in order to access the latest version of our API. If you are an API V3 user, you already use the most up-to-date version of our API.

This guide covers the benefits of migrating to the API V3 and how to proceed with the migration process.

🤔 Which API version does my company use?

The base URL used in your API calls indicates the API version you currently use.

✨ What are the benefits of migrating to the API V3?

📘

The API V2 is still maintained, but many improvements come with the V3. It's worth checking out.

The main benefits of our new version are :

• The application and the signature experience have been completely revamped to provide a best-in-class experience, both to users and signers.
• You will benefit from the latest product improvements. Our API V2 will remain as it is today. Conversely, our teams are continuously working on improving the API V3 to provide you with the best eSignature product on the market.
• New features have been added such as Smart Anchors and Custom Experiences. Others, like Webhooks, have been completely revamped to make them easier to use.
• The iFraming system is more secure and benefits from an SDK to facilitate its integration.
• The API V3 response time is five times faster than the V2.
• The previous server stamp feature has been revamped and rebranded as Electronic seal (see Migrating from v2 server stamps to v3 electronic seals).

⚙️ How do I migrate from the API V2 to the V3?

Our teams have developed a simple, 4-step process to guide you through migration:

• 1️⃣ Contact your Customer Success Manager (CSM).
  Our team will answer any questions you may have and help determine a timeline for the next steps.

• 2️⃣ Log in to your V3 APP and API.
  We will open a V3 APP and API account for you (once you and your CSM have reached an agreement regarding migration). You will be able to access both the V2 and the V3 using the same authentication. Users and contacts will be copied as well. No manual work is required from you at this step.

• 3️⃣ Start the integration on the V3.
  When you are ready, you can create your first API Key on the V3 and start the integration in your codebase, using our Sandbox environment.

• 4️⃣ Go to production in the V3.
  Once you are ready to use the V3 in production, you can contact your CSM who will check with you if everything is in order, and activate the V3 production environment for you.

📘

Our team is here to assist you.

If you have any questions about the migration process, our team is here to help and guide you through the whole process.

💡 What are the main differences between the API V2 and the V3?

Overall, the concepts and objects that you will manipulate on the V3 are very similar to what you were used to on the V2. To help you through this process, we detailed the main differences.

Clearer wording

From V2 to V3, we change some concept names, find below their mapping:

Be careful, some concepts are not completely equivalent (because we improved them!) :

• Custom Experience is a new way to brand your signature experience
• Sandbox is a better way to test your integration

A better structural approach

Only one environment

On the V3, the staging environment doesn't exist anymore. There is only one application accessible through this URL. To test the API, you only need to use our test environment called "Sandbox". To do that, you just have to create an API key for the Sandbox environment and use it in your requests.

Efficient file upload

In V2, we use base64 upload, which works well but involves high CPU usage on both clients and server side and consumes 30% more bandwidth.
In V3, we use a binary base upload (multipart/form-data) that allows uploading the document in a more efficient way. It is also standard in the API market.

Improved customization

On the V3, we introduced Custom Experiences feature. It allows you to personalise all the aspects of a Signature Request, from the notifications to the User Interface. Once a Custom Experience is created, it can be used for many Signature Requests. All the details about the Custom Experience can be found here. The customization is now easier to manage and offers greater branded possibilities.

Easier Webhooks settings

On the V3, Webhooks can be managed through the APP or the API and are set up for all the Signature Requests. They are based on global events and relate to what is happening for all the Signature Requests.
On the V2, Webhooks have to be set for each Signature Request created. Setting Webhooks is easier on the V3. All details about migrating Webhooks from V2 to V3 can be found here.

Want to learn more about new features coming in V3?

Follow the latest news and upcoming features on our roadmap page.