QES identification

Identify one person remotely, confirmed with one qualified signature, and receive the full identification data set. In testing, on request.

In testing. The complete flow runs in our test environment; there is no production host yet. Access, test credentials and the base URL on request from IDCanopy.

QES identification is IDCanopy's standard identification workflow for qualified trust services. It identifies one person remotely (ID document, selfie, liveness) and confirms the identification with exactly one qualified electronic signature, on the contract of the signing service. The certificate issued for that signature is disposed of after signing, so the session returns the whole identification data set: the values the certificate was issued on, which are the ones you keep, for example to issue a certificate or a seal yourself.

No document of yours is signed in this workflow. To identify people and have them sign your own PDF, use QES identify and sign. Both use the same API: this workflow is a session created with mode: identification.

Workflow

You create a session with mode: identification for one person, with their email address and mobile number, and receive a personal url.
The person opens the link and is guided through the identification wizard in the session's language.
The ID document is captured (passport or national ID card) and checked for authenticity and validity.
Selfie and liveness check: the face is compared with the document photo.
The person confirms their data as it will appear in the certificate.
One signature: the person signs the contract of the signing service, confirmed with a one-time code sent to their mobile number. Every completed identification carries this signature as proof of consent.
The person is sent back to your redirect URL.
You are notified by webhook (session.completed) and read the session for the identification data set and the signature evidence.

There is no document step: the session goes from identifying straight to signing once the person has identified, then to completed. If a check fails, the session ends failed. You decide whether to start a new session.

Create a session

POST /qes-onboarding/sessions with mode: identification:

{
  "mode": "identification",
  "language": "de",
  "signers": [
    {
      "person": { "email": "erika.mustermann@example.com", "phone": "+436601234567" },
      "signature_fields": ["Signature_1"],
      "reference": "applicant"
    }
  ],
  "reference": "seal-request-42"
}

mode: sign (default) or identification.
signers holds exactly one signer, with exactly one entry in signature_fields.
language: ISO 639-1 language of the wizard, per session. Default en.
contract.display: collapsed (default) or expanded. Allowed only with mode: identification. The value is stored with the session; how the wizard shows the contract depends on the signing service, and support for this setting is still pending.
template_id, document, document_after and signing_order are not allowed in this mode: 400 invalid_request.
PUT /qes-onboarding/sessions/{session_id}/document answers 409 wrong_state: an identification session never waits for a document.
503 identification_unavailable: identification sessions are not configured on this environment. Nothing was created; retry later.

Every other part of the API works as for QES identify and sign: Idempotency-Key, finding sessions by reference, cancelling, and the 7-day expiry.

The session carries mode: identification and contract; signing_order is parallel and document_after is all_identified, since there is one person.

Events

One person is both subject and signer, so an identification session sends session events only and no signer.* events: session.signing (the person identified and signing is open), session.completed (data set ready), session.failed, session.expired and session.cancelled. The same event may arrive more than once: deduplicate on event_id. You can always read the current state of the session, so a missed event loses nothing. See Webhooks.

Identification data set

Once the person has identified, GET /qes-onboarding/sessions/{session_id} carries the data set in signers[0].identification. Every field is always present; a value the signing service did not state is null.

Field	Content
`first_name`, `last_name`	Names
`date_of_birth`	Date
`birth_place`	Place of birth
`gender`	Gender
`nationality`	ISO 3166-1 alpha-2
`personal_number`	As printed on the identity document, in the format of the issuing country
`email`, `mobile`	Contact details
`document.type`	For example `ID_CARD` or `PASSPORT`
`document.number`	Document number
`document.issuing_country`	ISO 3166-1 alpha-2
`document.issuing_authority`	Issuing authority
`document.issue_date`, `document.expiry_date`	Dates
`method`	How the person was identified, as the signing service states it
`completed_at`	When the identification completed
`field_checks`	The checks behind each value, below
`document_check`, `face_check`	`passed` and `errors`, the keys of the failed controls; or `null`

field_checks has one entry per field (first_name, last_name, date_of_birth, birth_place, gender, nationality, personal_number, email, mobile, and document_number for document.number). Each entry has three checks, each ok, failed or skipped:

Check	Meaning
`from_document`	The value was read from the identity document.
`matches_request`	The value matches the data you sent when you created the session.
`otp_confirmed`	The value was confirmed by a one-time code to the person.

skipped means the signing service recorded no result for that check: neither a pass nor a failure.

The signer's signature carries the evidence of the qualified signature: signed_at, level and the certificate's subject, issuer, serial number and validity.

Evidence report

An evidence report is planned: an IDCanopy summary of who was identified, when and how, with the data set, the checks, the signature and the hashes of the stored evidence files. The API does not return it yet.

Download a sample evidence report (PDF). Sample, made-up data, layout may change, not yet sealed.

The other evidence (ID document images, selfie, face-check and document-capture videos, the signed contract as a PDF, the face-check report) is not part of the API in this version; delivery through the API is planned. Until then, ask IDCanopy how it is delivered.

Languages and documents

The wizard language is set per session, with English as the fallback. Accepted documents are passports and national ID cards per the coverage list, shared on request.

Data protection

IDCanopy acts as processor. How long IDCanopy keeps the identification data, images and evidence is agreed per customer in the data processing agreement.