QES identify and sign
Available on request. Identify a person and have them sign a PDF with a qualified electronic signature in one session
Available on request. Contact IDCanopy for access; details may change. Test environment only.
Identify a person and have them sign a PDF with a qualified electronic signature (QES) in one session. The flow pauses after identification so you can upload the document, personalised with the identified name if you need it. One signer per session.
This follows the draft contract 0.1.0. It runs in a test environment only; the base URL is shared on
request. It is a separate service from the QES onboarding operations of the Umbrella
API (/onboarding/*), which stay as documented.
Flow
POST /qes-onboarding/sessionscreates a session and returns aurl. Send the person there to identify. The session isidentifying.- After identification the session moves to
awaiting_documentand your webhook receivessession.awaiting_document.GET /qes-onboarding/sessions/{session_id}now carries the identification summary. - Upload the PDF with
PUT /qes-onboarding/sessions/{session_id}/document. The session moves tosigningand the person signs. - On
session.completed, read the session for the signature evidence and download the signed PDF fromGET /qes-onboarding/sessions/{session_id}/signed-document.
A session that is not finished can be cancelled with
POST /qes-onboarding/sessions/{session_id}/cancel.
Statuses
| Status | Meaning | Next |
|---|---|---|
created | Being set up. | identifying |
identifying | The person can identify at url. | awaiting_document |
awaiting_document | Identified. Upload the PDF. | signing |
signing | The person can sign. | completed |
completed | Signed. Final. | |
failed | Ended without a signature. Final. | |
cancelled | Cancelled by you. Final. | |
expired | The link expired. Final. |
failed, cancelled and expired carry a failure_reason: provider_unavailable,
provider_failed, provider_expired, document_not_uploaded or cancelled_by_client. Every
session keeps a history of its status changes, oldest first.
Authentication
Send your API token as Authorization: Bearer <token> on every call.
Pending verification: how the token is issued is not part of the contract yet.
Errors
Errors are application/problem+json with type, title, status, code and detail. Branch on
the HTTP status and code.
| HTTP | code | Meaning | What to do |
|---|---|---|---|
| 400 | invalid_request | The request is malformed or fails validation; detail names the field. | Fix the request. |
| 401 | unauthorized | Missing or invalid token. | Check the token. |
| 403 | forbidden | The token is valid but not enabled for QES onboarding. | Contact IDCanopy. |
| 404 | session_not_found | No session with this id for your account. | Check the id. |
| 409 | wrong_state | The session is not in a state that allows this call. | Read the session and follow its status. |
| 429 | rate_limited | Rate limit reached. | Retry after Retry-After seconds. |
| 500 | internal_error | Unexpected error. | Retry later. |
| 502 | provider_unavailable | The signing service did not respond as expected. | Retry later. |