kyc

Order a QES-signed identification package for a role-holder.

Asynchronous, because a human subject signs. The registers name the holders of the claimed role; the subject proves they are one of them by signing the composed dossier with their own qualified electronic signature; the platform verifies that the identity certified in that signature corresponds to the register record, and the responsible advokatas attests exactly that correspondence. Returns immediately with an order id and, on delivery: link, the ceremony URL to hand the subject. Billed on delivery only: refusal, expiry, mismatch and failure cost nothing.

post/v1/kyc-packages

Request

  • Base URL: https://api.tvarka.pro
  • URL: https://api.tvarka.pro/v1/kyc-packages
  • Auth: HTTP bearer

Headers

Idempotency-Keystring

Optional tenant-and-operation-scoped create key (1-128 visible ASCII characters). Identical input replays the original response; changed input or an unresolved execution returns 409. After 90 days the response expires but the key remains reserved. Do not change keys to retry a request with an uncertain outcome.

Request body

entityCodestring required

Lithuanian legal-entity code of the entity the subject is claimed to serve.

subjectRole'vadovas' | 'dalyvis' | 'naudos_gavejas' required

The role the subject is claimed to hold, as recorded in the registers.

purpose'AML_KYC' | 'BUSINESS_RELATIONSHIP_DD' | 'TRANSACTION_DD' | 'LEGAL_CLAIM' | 'OTHER' required

Purpose of processing. Logged, and reproduced in the dossier the subject signs.

purposeNotestring
delivery'link' | 'email'

link returns the ceremony URL for you to place in your own onboarding flow; email has Tvarka send it to subjectEmail.

subjectEmailstring email

Required when delivery is email.

callbackUrlstring uri

Public HTTPS endpoint notified on the terminal state, HMAC-SHA256 signed with your webhook secret in X-Tvarka-Signature. Polling is the equivalent fallback.

expiresInDaysinteger

How long the subject has to sign before the order expires unbilled.

reverificationboolean

Requests the repeat-identification price. Eligibility is checked after the subject signs against a prior delivered package for the same client, entity and certified subject identity. Otherwise the ordinary package price applies.

Response

Order accepted; the subject has not signed yet.

orderIdstring uuid required
status'created' | 'dossier_ready' | 'awaiting_evidence' | 'awaiting_subject' | 'subject_signed' | 'validated' | 'match' | 'mismatch' | 'attested' | 'delivered' | 'refused' | 'expired' | 'failed' required

Terminal states are delivered, mismatch, refused, expired and failed. Only delivered is billed and only delivered has an artifact.

entityCodestring required
entityNamestring
subjectRolestring required
purposestring required
createdAtstring date-time
expiresAtstring date-time
deliveredAtstring date-time
ceremonyUrlstring uri

Present while the subject still has to sign, on the link delivery path.

crossCheckOutcome'match' | 'mismatch' | 'unsupported_subject'
detailstring

Changes

No recorded changes to this operation across all 1 revision of this API.