API integration for Universign
We build your Universign connector
We wire the Universign API into your business file to the Universign API to create transactions, set the right eIDAS level and bring completed status back into your file.
- Senior product team
- signature connectors in production
- from scoping to monitoring
What does the Universign integration provide and how does the contract become a business object?
Universign is an eIDAS-qualified trust service provider offering simple, advanced and qualified electronic signatures, electronic seals and timestamping. Its integration lets your application send a document for signature with the required level of proof, monitor the status of each signer in real time, and retrieve the signature proof in the file as soon as the transaction closes. The document stops being an email attachment and becomes a business object with a legal status, a date and evidential value attached to your process.
What our clients plug into Universign
Real-estate software, sale agreement and annexes
Sale agreement in level2 or level4, agency seal on annexes, timestamp on the file. One connector, three proofs.
Internal signing desk with a fine policy
level1 day to day, switch to level4 on deeds listed by legal. The level is no longer a second vendor.
Multi-tenant SaaS, Master Console
One Universign workspace per end client, webhooks created with the master key. The vendor runs many files without mixing secrets.
Follow-up on a reason, not on silence
action.stalled with signature_refusal or incorrect_name_prerequisite opens a CRM ticket. « The client did not sign » becomes an actionable reason.
What this changes in your journey
Technology in service of a measurable result: the right level, a blocking reason, a proof of date.
The right level for each document
Addendum, framework contract, deed: internal policy picks the eIDAS level. We avoid confusing advanced and qualified signatures.
Seal and timestamp in the same flow
Legal entity and date proof in the same journey. Useful in notaries, real estate, health, finance.
A block becomes a readable reason
Refusal, expired certificate, wrong name: your product stops treating silence as a technical error.
Consumption is readable by level
You see how many simple, advanced or qualified signatures go out. Enough to recharge the surplus to the team that asked for it.
How we ship your Universign connector
Scoping
Which documents, which min_signature_level values are actually open on the workspace, Basic or Bearer, Master Console or workspace key. We list edge cases before writing a line of code.
Development
Transaction state machine, idempotency on POST transactions and start (409 Conflict is nominal), JWS PS256 verify via JWKS, queue.
Testing
Alpha for the flow. A test that « works in level1 » proves nothing for QES: we replay every open level. Pause does not stop expiry.
Monitoring
GET transaction reconciliation, periodic consumptions/summary, alert on 429 rate_limit_error. You know a flow is broken before your customers do.
What the Universign API allows
- Transactions and participants
- Create, start, pause, cancel. Default duration 14 days (20,160 minutes), max 60 days, or 180 if long-term is enabled. Pause does not stop expiry.
- Five eIDAS levels
- level0/level1 = SES, level2 = AES, level3 = AES + qualified certificate (not a QES), level4 = QES. level0, 2, 3 and 4 depend on workspace entitlements.
- Seal, timestamp, identity
- Qualified seal for a legal person, qualified eIDAS timestamp, identity prevalidation for level2 (prevalidation_id / lcp certificate).
- JWS PS256 webhooks
- x-jws-signature header, PS256 algorithm, JWKS keys. Retries 1 min, 5 min, 30 min, 2 h, 6 h, 24 h, 48 h. Universign only logs API calls that returned 200.
Universign API vocabulary
- min_signature_level
- level0 SES with no auth, level1 SES (default), level2 AES, level3 AES + qualified certificate, level4 QES. Mixing up level3 and level4 in a legal quote is an eIDAS qualification error.
- completed vs closed
- closed: actions are finished. completed: extended documents are downloadable. Your product archives on completed, not on closed.
- x-jws-signature
- Detached JWS RFC 7515, PS256 algorithm, kid in the header. This is not an HMAC. A Yousign copy-paste will fail. Prod JWKS: api.universign.com/v1/webhooks/jwks.json.
- action.stalled
- Event with named reasons (signature_refusal, incorrect_name_prerequisite, sealer_expired, and others). Treat it as a business ticket, not a 5xx.
- Workspace entitlements
- The real product catalog. Without them, level0/2/3/4 are not callable. A sandbox test in level1 proves nothing for QES.
- rate_limit_error
- Type returned with the 429. No numeric cap is published. Sizing a batch without asking support for the quota means discovering it in production.
The real constraints of the Universign API
level3 is not a QES
It is AES backed by a qualified certificate. Only level4 is documented as qualified signature. Mixing them up in a quote is an eIDAS error, not an enum detail.
Entitlements make the catalog
Without workspace enablement, level0, 2, 3 and 4 are not callable. We persist the matrix before exposing the choice in the UI. Sandbox level1 is not enough.
The rate quota is unpublished
Official docs name the 429 and rate_limit_error, not a number. We ask support before any batch, rather than discovering it in production.
Pause does not extend the deadline
A paused transaction keeps expiring. Default duration 14 days from start, max 60 days (180 if long-term). Pause is not an extension.
Universign API or Docusign API?
Two eIDAS signature APIs. Universign adds seal and timestamp; Docusign weighs when the stack is already there.
| Criterion | UniversignThis page | DocusignGlobal reference |
|---|---|---|
| Core object | Transaction (draft → completed) | Envelope (GUID) |
| eIDAS SES / AES / QES | 5 levels; level3 ≠ QES; level4 = QES | SBS, signatureProviderName |
| Extra evidence | Qualified seal and timestamp | Envelope pack + Connect |
| Webhooks | JWS PS256 + JWKS | HMAC X-Docusign-Signature-1 |
| Authentication | Basic key: or Bearer | OAuth 2.0, JWT Grant |
| API quota | 429 rate_limit_error, unpublished figure | 3,000 / h, burst 500 / 30 s in prod |
| The right case | Notaries, real estate, French finance | Docusign already in the stack |
All three (Universign, Docusign, Yousign) 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 Universign integration
The other signature APIs
If Universign is not the right foundation, these options are discussed at scoping.
UniversignWe build your Universign connectorThis page
DocusignEnvelope, SBS, Connect HMAC, go-live that refuses polling.
YousignFrench v3 API, SES AES QES as an enum, iframe forbidden in QES.We combine Universign with
The stack around Universign on our projects.
Universign integration: your questions
Three steps. First a workspace key (Basic -u API_KEY: or Bearer) and, if you operate several clients, a Master Console master key. Then create the transaction as draft, set min_signature_level from the internal policy, start, and treat 409 Conflict as a nominal retry. Finally webhooks: verify x-jws-signature in PS256 with the JWKS, return 2xx, queue, deduplicate on evt_*. The hard part is not the POST, it is the entitlement matrix and the fact that level3 is not a QES.
Official mapping: level0 and level1 = SES (level0 with no authentication, level1 default). level2 = AES. level3 = AES backed by a qualified certificate: it is not a QES. level4 = QES, the only value documented as « qualified signature », handwritten equivalence across the Union (regulation (EU) No 910/2014, art. 25(2)). level0, 2, 3 and 4 depend on workspace entitlements. A quote that sells level3 as a QES is a qualification error, not an API detail.
No. Official documentation describes the 429 and the rate_limit_error type, not a numeric cap. We ask support for the quota before sizing a batch, and we read responses in production rather than copying a blog figure. Less catchy than a table, more accurate. A batch launched blind discovers the cap in production: that is exactly what scoping avoids. We do not invent a number just to look precise here.
A first useful flow, typically a level1 transaction and write-back on completed, ships in two to three weeks. A chain with level4, seal, timestamp, Master Console and stalled_reason in the CRM is closer to six to eight weeks: entitlements and JWS verify weigh as much as the code. A test that « works in level1 » proves nothing for QES. We scope the perimeter up front and give a firm estimate before starting.
Universign if you need qualified seal and timestamp, a five-level policy, and a French trust service provider. Docusign if the stack is already there (envelope, Connect, strict go-live). Yousign if SES, AES and QES as an enum is enough, with iframe in SES/AES. None makes QES iframe by default. Universign level3 is not a QES: saying so in the quote avoids a legal error. The choice is a stack and evidence-policy trade-off.
A Universign integration project?
Let's talk. 30 minutes to scope your transactions, the eIDAS level actually open on the workspace, and to tell you frankly what is feasible.
Discuss my Universign project