Overview

The User resource designates a collaborator with a Yousign app license. They are able to send Signature Requests, save Contacts, and use Templates and forms from the Yousign app of your organization. Their access rights depend on their role and the workspaces they are attached to.

Using the API, you can manage users within your organization:

• Read User information.
• Update User roles and statuses.
• Invite new Users.
• Delete User in the invited status.

You can manage Users from the app as well, see this article for more details.

🚧

Only a few user management endpoints are available in the sandbox environment. See this section for more details.

📖

Restrictions on owners

The following actions are not supported:

• Change the role of a User with the owner role.
• Assign the owner role to a User.
• Suspend a User with the owner role.

Please contact our customer support if you want to request a change of owner.

Get information about Users

List all the Users in your organization with the GET /users endpoint.

Retrieve a specific User by providing a User ID with the GET /users/{userId} endpoint.

Update a User

With the PATCH /users/{userId} endpoint, you can:

• Change a User’s role from admin to member or from member to admin with the role parameter.
  Note that you cannot change the role of a suspended user.
• Activate or suspend a User with the active parameter.

You can add and remove Users from Workspaces with the Workspaces endpoints. Learn more here.

Create a new User

📖

You can create a new User only if you meet the following conditions:

• You have at least one available license in the Organization. Learn more about licenses.
• There is no existing Yousign User with the same email address.
• There is no User Invitation with the same email address in the Organization.

By calling the POST /users endpoint, you will create two resources:

• A new User resource in status = invited and is_active = false
• A User Invitation resource associated to this new User. This will automatically trigger the sending of an invitation email. You can view the User Invitation details with dedicated endpoints (see User Invitation guide).

The User will remain in status = invited until they accept the Invitation. Once accepted, the User Invitation resource is deleted and the User becomes active.

Table summarising the invitation process:

🔔

You can listen to the user.completed webhook event to get notified in real time once the User status becomes completed .

📖

Different mechanism when the User is invited from the app

When inviting a new User from the app, only a User Invitation resource is created, and the latter is not associated to a User resource.

Once accepted, the User Invitation resource is deleted and a User resource is created with a status = signed_up.

Delete a User

Delete a User by calling the DELETE /users/{userId} endpoint. You can only delete a User in invited status. This will also delete its associated User Invitation.

🚧 Limitations in the sandbox environment

In the Sandbox environment, users can only be read but not created, modified, or deleted. User invitations aren’t accessible at all.