API integration for Yousign
We build your Yousign connector
We build the Yousign v3 connector to the Yousign v3 API to create Signature Requests, set the right eIDAS level and bring the signed status back into your file.
- Senior product team
- signature connectors in production
- from scoping to monitoring
What does the Yousign integration provide and why choose a European signature solution?
Yousign is a French eIDAS-compliant electronic signature publisher offering simple, advanced and qualified levels. Its integration lets your application send a document for signature with the required proof level, track each signer's status in real time, and receive the signature proof in your file upon closure. You choose Yousign for its native European compliance, hosting in France and French-language support: important criteria for regulated sectors such as real estate, HR and legal.
What our clients plug into Yousign
Quotes and T&Cs in SES, iframe
The French SaaS sends the request, email OTP, iframe allowed. Sales sees status in the file, not in the Yousign app.
Employment contracts in AES
ID document plus SMS OTP. HR software advances on signer.done. AES is off by default: support enablement is part of scoping.
Deeds in QES, outside the iframe
Share transfers, some mandates: video plus human review, sequential signers, 30 minutes after identification. Redirect URLs replace the iframe.
Seal on issued invoices
The document is issued by the company, not signed by a person. Simple, advanced or qualified, distinct from the contract Signature Request.
What this changes in your journey
Engineering in service of a measurable outcome: the right signature level, visible KYC, status in the file.
The eIDAS level is a journey choice
Simple, advanced or qualified: we set it per document type. You do not open a parallel legal project for every template.
Approval stays in the flow
The approver role blocks signature until everyone has validated. Sales no longer opens a second tool to validate before send.
KYC is a product status
You know why a signer is blocked (failure, expiry…), without opening the Yousign console.
Each customer has their space
For a multi-tenant ISV, files are partitioned. An incident on one does not expose another's documents.
How we ship your Yousign connector
Scoping
Which documents, which signature_level, iframe or redirect, AES and QES already open on the account. We list edge cases before writing a line of code.
Development
Signature Request, activation, HMAC x-yousign-signature-256, 2xx in under a second, processing in a queue. Client sized for 60 / min.
Testing
Sandbox for manual development only: signatures not legally binding, watermarked documents. Automated tests are mocked. QES outside the iframe.
Monitoring
x-ratelimit-* headers, Ratelimit-Reset, x-yousign-retry. Alert before 1,200 / h. You know a flow is broken before your customers do.
What the Yousign API allows
- Signature Request
- Create, documents (PDF 50 MB, 50 per request), signers (100, 5 in sandbox trial), fields, activation. Metadata and custom properties to bind the deal id.
- Three eIDAS levels per signer
- electronic_signature, advanced_electronic_signature, qualified_electronic_signature. SES: no_otp, otp_email, otp_sms, iframe OK. AES: otp_sms, ID, iframe OK. QES: no OTP, no iframe.
- Identification webhooks
- signature_request.done, signer.done, signer.identification_succeeded / failed / blocked / expired. Header x-yousign-signature-256 = sha256= + HMAC of the raw body.
- Electronic seal
- POST /electronic_seals: document issued by the legal person, simple, advanced or qualified levels, distinct from signing a contract.
Yousign API vocabulary
- signature_level
- electronic_signature (SES), advanced_electronic_signature (AES), qualified_electronic_signature (QES). You can mix SES and AES; in QES all signers share the same level and are ordered.
- Youtrust
- Product name in the 2026 documentation. URLs, the x-yousign-signature-256 header and *.yousign.app hosts remain Yousign. A page that ignores this gap looks out of date.
- x-yousign-signature-256
- HMAC-SHA256 header of the raw body, sha256= prefix. Plus x-yousign-retry and x-yousign-issued-at. Constant-time compare, deduplicate on event_id.
- 1-second webhook timeout
- First attempt: 1 s. Retries: 10 s, up to 8 times if auto_retry (2 min, 6 min, 30 min, 1 h, 5 h, 18 h, 1 d, 2 d). Return 2xx and process in a queue, or you drop events.
- QES 30-minute window
- After successful identification, 30 minutes to sign. After that: signer.identification_expired. No iframe, no custom UI, signature_authentication_mode = null.
- Approver
- Role that blocks signing until all approvers have validated. The business circuit stays in Yousign, triggered from your product.
The real constraints of the Yousign API
AES and QES are off by default
You need support enablement, and a plan that includes them. Promising QES « available in the API » without that step is false. Scoping starts with the account entitlements.
QES refuses the iframe
Constraint around identity video: redirect URLs are mandatory. A product designed entirely in an iframe breaks on the first QES contract. 30-minute window after identification.
One QES field on an already-signed PDF
In QES, a single cryptographic signature for the whole document. On a locked PDF, one field only. SES and AES do not have this constraint. A classic UAT incident.
60 requests / min, 1,200 / h in prod
Sandbox 30 / min and 200 / h. 429 Too many requests. Headers x-ratelimit-limit-minute / -hour. Single queue, no parallel request activation. Sandbox: no load test.
Yousign API or Docusign API?
Two eIDAS signature APIs. The right choice depends on how SES, AES and QES are expressed, and on your current stack.
| Criterion | YousignThis page | DocusignGlobal reference |
|---|---|---|
| Core object | Signature Request | Envelope (GUID) |
| eIDAS SES / AES / QES | signature_level enum per signer | SBS, account options to enable |
| Authentication | Bearer, API key | OAuth 2.0, JWT Grant (1 h token) |
| Webhooks | x-yousign-signature-256, 1 s timeout | Connect, HMAC X-Docusign-Signature-1 |
| QES in the journey | Video + human, no iframe, 30 min | QTSP, IdNow example, outside iframe |
| API quota | 60 / min and 1,200 / h in production | 3,000 / h per account, burst 500 / 30 s |
| The right case | French product, eIDAS native in the API | Docusign already in the stack |
All three (Yousign, Docusign, Universign) cover SES, AES and QES. None makes QES free or iframe by default. This is a scoping trade-off, not a final choice.
What we measure on a Yousign integration
The other signature APIs
If Yousign is not the right foundation, these options are discussed at scoping.
YousignWe build your Yousign connectorThis page
DocusignEnvelope, SBS, Connect HMAC, go-live that refuses polling.
UniversignFive levels, qualified seal and timestamp, JWS PS256 webhooks.We combine Yousign with
The stack around Yousign on our projects.
Yousign integration: your questions
Three steps. First a Bearer key, scoped organization or workspace, sandbox and production kept apart. Then build the Signature Request: documents, signers with signature_level, activation. Finally webhooks: verify x-yousign-signature-256 (sha256= prefix, raw body), return 2xx in under a second, process in a queue, deduplicate on event_id. The hard part is not the POST, it is the eIDAS level actually open on the account and the QES journey outside the iframe.
They are the three eIDAS levels, exposed as an enum. SES (electronic_signature): no_otp, otp_email or otp_sms, iframe and custom UI allowed. AES (advanced_electronic_signature): ID document, otp_sms only, iframe OK, custom UI forbidden, off by default. QES (qualified_electronic_signature): ID plus face/ID video checked by a human, no OTP, no iframe, sequential signers, 30 minutes to sign, off by default. Only QES has the legal effect of a handwritten signature across the Union (regulation (EU) No 910/2014, art. 25(2)).
No. QES refuses the iframe and custom UI: you need redirect URLs. A product designed entirely in an iframe breaks on the first QES contract. The window after successful identification is 30 minutes; after that, signer.identification_expired. AES and SES accept the iframe. We settle this at scoping, before the first pixel, and we plan the business timeout plus identification_blocked. Promising QES « like the quote, but in an iframe » is false.
A first useful flow, typically a quote in SES with iframe and write-back on signature_request.done, ships in two to three weeks. A chain with AES or QES, multi-tenant workspaces, seal and identity checks is closer to six to eight weeks: support enablement and the redirect journey weigh as much as the code. Sandbox signatures are not legally binding, so UAT on production entitlements is on the calendar. We scope the perimeter up front and give a firm estimate before starting.
Yousign if you want SES, AES and QES as an enum, a French vendor, and yousign.app hosts. Docusign if the stack is already there: envelope, SBS to enable, Connect, strict go-live on polling. Universign if you need qualified seal and timestamp on top of signature, with five levels including level3 which is not a QES. No API makes QES iframe by default. The choice is a stack and evidence-policy trade-off.
A Yousign integration project?
Let's talk. 30 minutes to scope your Signature Requests, the eIDAS level actually open on the account, and to tell you frankly what is feasible.
Discuss my Yousign project