Yousign

Your electronic signature requests — to get an emailed attachment signed, follow its progress and collect the signed document and its audit trail.

A Yousign connection lets the Yousign node get an emailed attachment signed: create a signature request, upload the document, add signers and approvers, activate the request, follow it, then download the signed document and its audit trail. The same connection feeds the Yousign — event trigger, which starts a workflow when Yousign reports an event such as a request signed by everyone.

The connection holds a Yousign API key, an environment and, optionally, a webhook signing key. The secrets are encrypted at rest, applied by the server at call time, and never appear in a workflow. Yousign is being renamed Youtrust; its API, headers and domains still say “Yousign”.

At a glance

• Identifier: yousign
• Family: Service
• Set up by: A member (personal) or an administrator (shared with the organisation)
• Authentication: API key or token
• Credential type: service:yousign
• Official API documentation: https://developers.youtrust.com/docs/introduction-new
• Environments: Sandbox (sandbox) — https://api-sandbox.yousign.app/v3 ; Production (production) — https://api.yousign.app/v3
• Rate limit applied by Mankomail: 30 requests per minute and per connection; up to 3 attempts on a 429 or a 5xx
• Webhook signature: x-yousign-signature-256 header, HMAC-SHA256 of the raw body
• Connection test: Yes

Step by step

The same steps are shown in the connection form of the app.

1. Pick the environment: “Sandbox” to try things out (no legal value, watermarked documents, nothing is billed), “Production” to sign for real.
2. Open Yousign, then the right-hand panel → “API” section → “API keys” page. You need the Admin or Owner role: a plain member cannot see that screen.
3. Create a key with the SAME environment as the one picked above, the “organization” scope and the “full-access” permission — “read-only” cannot send a signature request.
4. Copy the key shown and paste it below: Yousign will never show it again. A key from the wrong environment fails the test with a 401.
5. The signing key is only needed if you wire the “Yousign — event” trigger. It is shown under “API > Webhooks” when the subscription is created; leave it empty otherwise.

Connection fields

Field	Kind	Required	Notes
Environment (environment)	Choice	Yes	The two worlds are sealed off from each other: a request created in one cannot be found in the other, and a key only reaches its own. sandbox (Sandbox), production (Production) Default: sandbox
API key (apiKey)	Secret — never shown again	Yes	It acts on behalf of your Yousign organisation, with the permissions chosen when it was created.
Webhook signing key (webhookSecret)	Secret — never shown again	No	Optional. It is the webhook subscription’s “secret key”, visible in the Yousign app or returned when the subscription is created.

Before you start

• You need the Admin or Owner role in the Yousign organisation: a plain member cannot see the API keys page.
• Pick the environment first, then create the key in that same environment. A sandbox key does not work in production, and the other way round.
• Sandbox is for trying things out: no legal value, watermarked documents, nothing billed. Production signs for real, and every activation is billed: Yousign counts one credit per invited signer, at activation, whether they sign or not.
• To create a webhook subscription through the API, you need a production key, even to listen to the sandbox, and Yousign does not allow it during the trial period. Subscriptions can also be created by hand in the Yousign app (API > Webhooks).

Permissions

When you create the key in Yousign, choose:

Setting	Value	Why
Environment	The same as the connection	A key only reaches its own environment.
Scope	organization	The key acts on behalf of the whole Yousign organisation: requests, templates, contacts, users and workspaces.
Permission	full-access	Required to create, activate, cancel or delete a request, add signers, upload documents and manage webhook subscriptions. A read-only key passes the connection test (it only reads) but fails at the first write.

The node covers ten resources: Signature request (create a draft, create from a template, get, list, activate, cancel, reactivate an expired request, delete), Document (upload an email attachment, list, download the signed document, download the audit trail), Signer (add, get, list, remind), Approver, Follower, Template, Contact, User, Workspace and Webhook (list, create, delete a subscription). Activate sends the emails and triggers billing; it asks for an explicit confirmation.

Environments

The connection carries the environment, never the node, so that a workflow copied from one client to another cannot sign for real because a field was left at its default value.

• The form proposes Sandbox by default.
• If the stored value is missing or unknown, the connection falls back to the first declared environment, the sandbox: a damaged connection never leads to production.
• The two worlds are sealed off: a request created in one cannot be found in the other. A valid id from one side answers 404 on the other.
• To work in both, create two connections (for example “Yousign — sandbox” and “Yousign — production”). The environment shows as a badge on each connection, Production highlighted. Changing the environment of an existing connection without re-entering the key is not saved: create a new connection instead.

Add the connection

1. Open Connections. In the Third-party services section, find the Yousign card and click Connect.
2. Give the connection a Name, choose the Scope — Personal (only you) or Organisation (the whole organisation; only an administrator can create one) — then the Environment.
3. Paste the API key. Leave the Webhook signing key empty unless you use the Yousign — event trigger. Click Create the connection.
4. Back in the list, click Configure on the new connection, then Test the connection.

The test calls GET /signature_requests?limit=1, which validates the key in the chosen environment, then GET /workspaces?limit=1 to display the name of a workspace. If the second call fails, the test still passes, without a name. A key from the wrong environment fails with “the service rejects the key”.

In a node, pick the connection in Yousign connection. Documents and signers are listed inside the chosen signature request. The request list includes requests created in the Yousign app as well as through the API. Delete is refused while a published workflow uses the connection.

Webhooks

The Yousign — event trigger receives Yousign’s webhooks on the workflow’s URL:

<PUBLIC_BASE_URL>/hooks/wf/<token>

• Getting the URL. The token is generated at the workflow’s first publication and returned only once. You can generate a new one with POST /api/v1/workflows/{id}/webhook (see the API): the response gives webhook.url, to prefix with <PUBLIC_BASE_URL>. A new URL invalidates the previous one.
• Subscribing. Either with the Yousign node, resource Webhook, operation Create a subscription (production key required; Listen to the sandbox, not the connection, decides which environment is listened to; leave Automatic retry on), or by hand in the Yousign app under API > Webhooks. The URL must be public HTTPS.
• Signing key. Copy the subscription’s secret key from the Yousign app (the node never returns it) and paste it in the connection’s Webhook signing key field. Without it, every delivery is refused.
• Signature. Yousign sends x-yousign-signature-256: sha256=<hex>, an HMAC-SHA256 of the raw body. Mankomail checks it in constant time before creating anything. A missing or wrong signature gets the same 404 as an unknown URL; the reason is only written to the server logs.
• Filtering. A subscription to all events receives dozens of event types, and one request with three signers produces about ten. Mankomail reads event_name and creates a run only for the Events ticked on the trigger (default: Request signed by everyone); nothing ticked means everything. Ignored events are acknowledged with 202.
• Deduplication. Yousign retries failed deliveries for about four days with the same event_id. Mankomail uses it as the deduplication key: a replayed delivery is acknowledged with 202 and creates no second run.
• Payload. The body arrives under data.yousign: {{ data.yousign.event_name }}, {{ data.yousign.data.signature_request.id }}, {{ data.yousign.data.signature_request.external_id }} — the correlation key you set at creation. The run has no triggering email.
• The Subscription (diagnostics) field is informational: it helps check that a subscription points to this workflow’s URL, in the right environment.

Common errors

Message or code	Cause	What to do
Test: “the service rejects the key” (integration.unauthorized)	Wrong key, revoked key, or a key from the other environment.	Check the Environment; create a key in that environment, or a new connection for the other one.
Test: “the service quota is exceeded” (integration.rate_limited)	Yousign answered 429.	The key is fine: try again in a moment.
integration.unauthorized during a run	401, or 403 for a read-only key on a write.	Create a full-access key and replace it.
integration.not_found	404: the request, document or signer does not exist in this environment.	Check the ids and the connection’s environment.
integration.rejected	400 or 422: Yousign refused the request body or the request is not allowed in its current state.	Read the detail in the step’s error, then fix the node settings. Webhook subscriptions need a production key and are not available during the trial.
integration.rate_limited	429 after retries. Mankomail sends at most 30 requests per minute per connection (the sandbox limit) and retries up to 3 times, honouring Retry-After. Yousign also has an hourly ceiling.	Transient: the engine resumes the step later.
integration.unavailable	5xx, 409 or network failure, after retries.	Transient: the engine resumes the step later.
integration.connection_unusable	The connection was deleted, is not active, is out of your scope, or belongs to another service.	Pick a valid connection in the node.
Webhook deliveries never start the workflow	Workflow not published, signing key missing or from another subscription, event not ticked, or subscription pointing to an old URL or to the other environment.	Publish, paste the subscription’s secret key, review Events, and check the subscription with List subscriptions.

Webhook events

The events offered by the trigger. An event the provider adds later is still accepted when no event is ticked.

Event	Label
signature_request.done	Request signed by everyone
signature_request.activated	Request sent
signature_request.declined	Request declined by a signer
signature_request.rejected	Request rejected by an approver
signature_request.approved	Request approved
signature_request.expired	Request expired
signature_request.canceled	Request cancelled
signature_request.reminder_executed	Reminder sent
signer.done	A signer has signed
signer.link_opened	A signer opened their link
signer.declined	A signer declined
signer.notified	A signer was notified
signer.notification_delivery_failed	A signer’s email did not arrive
signer.error	Error on a signer
approver.approved	An approver approved
approver.rejected	An approver rejected
contact.created	Contact created

Nodes that use this connection

• Yousign — event — trigger.yousign
• Yousign — yousign.api