Qodex.ai

API V2 Documentation | Yousign Developers

Number of APIs: 47

API V2 documentation (Not the latest version)

This documentation is only intended for our current API v2 customers.

If it’s the first time you integrate Yousign’s API, please use the v3 instead of the v2 to benefit from all its additional features.

How do I know which version I'm using?
The best option to know which version you have is to have a look at the base URL used for your API calls:

API V3 documentation (NEW)

To start integrating our new API product (v3) for free, please refer to this API v3 documentation.

If you're already an API v2 customer and would like to migrate to our new Yousign API version, discover the many benefits in this video:

For more details on this migration, read our dedicated guide for migrating from Yousign's API V2 to Yousign's API V3.

Welcome on Yousign for Developers!

Build the best experience of digital signature through your own platform. Increase your conversion rates, leverage your data and reduce your costs with Yousign API.

If you're already an API v2 customer, you'll find the rest of the documentation below.

Yousign provides an API that allows you to optimize and automate your signature process directly through your own application. Please find below the full documentation which explains how to integrate our API step by step with concrete examples, use cases as well as source code.

By using this service, you will enjoy all features of Yousign's application and even more.

API pricing

Click here for information on our API pricing.
On production environment, each API plan includes 1 user account for our Yousign application.

We are here to support you!

Our priority is to ensure that you never feel abandoned. For more information, you can visit our help center. If you have any technical or commercial questions or suggestions, feel free to contact us by email.

Environments

In order to offer the most flexible integration, we provide developers with a completely free and unlimited test environment (our sandbox is named Staging).

To approach and take control of our API, developers will be able to build POC (Proof Of Concept) up to the end to end qualification stage without any constraint. This means that it's not necessary to contract and start paying to carry out the full development stage.

EnvironmentAPI Base URLWeb App URL
Staginghttps://staging-api.yousign.comhttps://staging-app.yousign.com
Productionhttps://api.yousign.comhttps://webapp.yousign.com

Notes: All signed documents on staging environment are NOT legally signed. The certificate used as part of these signatures will NOT comply with legal expectations and NO .txt proof file will be generated for your tests.

It is important to underline that both environments are completely independent and there is no link between them. This means that you will have one login / password and API keys for staging environment and another login / password and API keys for production environment. There is no native way to switch from test to live environment. Just use the appropriate API key and appropriate URL to perform a test or live procedure.

For more details on the transition to production, you should refer to the following section: Go live.

Libraries

Currently, we don’t provide libraries or packages for specific programming languages. However, our API and webhooks use JSON. This format is widespread in the web ecosystem and you can easily find a parser for your favorite language.

Feel free to contact us if you built an open-source library for our API and want to share it with our developer community! Of course, Yousign will not maintain the provided libraries, but our team will be happy to simplify your integration even further.

Here is the list of libraries provided by the community:

Many thanks to Thomas Bruyelle, Olivier and Laurent H.!

Getting started

The Yousign API is a RESTful interface, providing access to a wide range of the data in the system and especially to create signature procedures.

The API accepts JSON content in requests and returns JSON content in all of its responses. This format is also forced by the Header Content-Type.

The HTTP method (like GET, POST, PUT, DELETE) determines the operation type on the resource (users, files, …). The resource is identified by the URL which is targeted by the method.

Example: GET https://staging-api.yousign.com/users will list all the details of users related to your organization.

To learn more about how the API works, you can consult the following links to understand how HTTP status, pagination, filters and data formats work.

In addition, each identifier used to target a resource in our API is formatted from the following standard: UUID (UUID v4). This format is systematically composed as follows:
XXXXXXXXXX-XXXX-XXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXXXX. Finally, given the number of characters and therefore the number of possibilities, this random identifier format is secured and unpredictable.

Before implementing it in your platform, you can use software (Qodex for example) to send JSON requests and receive responses without writing any line of source code. It could be very helpful at the beginning to understand what will be the request format and simulate the workflow on your side with inputs / outputs.

To further facilitate the development of your Yousign API integration, we provide you a Swagger through Swagger-UI and swagger.json.

Now let's see how to create your API key to start sending your first request!

Step 1 - Create your account

First of all, you have to create your own free and unlimited account to access our application on our staging environment (sandbox). Let's start by clicking on one of the following links:

After having entered your email address, you will receive a confirmation email allowing you to validate your account.

Notes: It is mentioned “Free 14-day trial. No credit card required.” on the signup page but there is no limit in time to use this service on the test environment.

On this environment, you will be able to create up to 10 users on your organization. Therefore, if you are a team of developers working on this wonderful project, you will all have access to the same information including sharing the API keys.

It's important to underline that on the production environment, each user account will be billed according to the selected plan (except the first user that will be included in your API plan).

Step 2 - Create your API key

Once you have access to our application, then you have to create an API key to access our routes (menu: Admin > API keys > Create).

  1. Logon on Yousign app: https://staging-app.yousign.com
  2. Create your first API key here: https://staging-app.yousign.com/admin/apikeys

Your API keys carry many privileges, so be sure to keep them secure! With these tokens, anyone can access to all information stored for your organization (users, files, ...). Do not share your secret API keys in publicly accessible areas.

On our application, only users with administrator privileges will access to API keys.

If you don't see any access to Admin menu or API key tabs, please contact your organization administrator or our technical support.

Step 3 - Authentication

Once your API key generated, you will be able to send and receive HTTP requests from our server.

Access to the API is performed via Bearer Authentication that involves security tokens called bearer tokens (so this is the API key).

Your request has to include Authorization header with your API key to be authenticated:

Authorization: Bearer [YOUR_API_KEY_HERE]

For security reasons, you can only use our API through HTTPS protocol. Calls made over plain HTTP will fail. You have to authenticate for all requests with Bearer authentication.

Notes: The API keys are different for your test site and your live site.

  1. Advanced features-Subscriber - /procedures POST {{base-api-url}}/procedures

  2. Procedure creation-Advanced mode - /files POST {{base-api-url}}/files

  3. Procedure creation-Advanced mode - /procedures/{id} PUT {{base-api-url}}/procedures/{id}

  4. Making your first call - /users GET {{base-api-url}}/users

  5. Advanced features-Attachment file - /files POST {{base-api-url}}/files

  6. Advanced features-User-Add a member - /procedures (add external member) POST {{base-api-url}}/procedures

  7. Advanced features-User-Create a user - /users POST {{base-api-url}}/users

  8. Advanced features-Validator - /members POST {{base-api-url}}/members

  9. Advanced features-Expiration date - /procedures POST {{base-api-url}}/procedures

  10. Advanced features-Procedure's template - /files POST {{base-api-url}}/files