Person Creation from Diia (Diia Sharing)

Diia Sharing lets you fill in a person's card directly from the documents that the person shares from their Diia mobile app. Instead of typing personal data manually, you request the required documents, the person confirms the sharing in Diia, and the system reads the returned data and files and writes them to the Person card, related records, and document attachments.

This article describes how the feature works for a physical person (фізична особа): how the sharing request is processed, which Diia document types are supported, and which person fields are filled in.

Path: People list → Create from Diia, or Person Card → Functions → Update from Diia.

Overview

Diia Sharing is an integration with the official Diia Sharing (шерінг) API. The general principle is:

1. You start a sharing request from Business Central and choose which document (or documents) you want to receive.
2. The person who owns the documents confirms the request in their Diia app.
3. Diia returns a signed package — a set of PDF files together with a structured metadata.json description of each document.
4. Business Central reads the metadata, maps it to person fields, and attaches the PDF files.

The person never sends scans or photos manually — the data comes straight from state registries through Diia, so it is already verified and structured.

Sharing modes

When you create a request you choose a Sharing Mode:

• Online — Business Central generates a deeplink that is shown both as a QR code and as a copyable link. If the person is next to you, they scan the QR code; if not, you send the link via messenger or email. The link is valid for 3 minutes and can be used once. Online mode also supports Multi-Sharing (see below).
• Offline — The person opens the document in their Diia app and reads a 13-digit barcode from it. You enter (or scan) that barcode into Business Central. Offline mode requests one document type at a time.

Request lifecycle

After the request is created, Business Central automatically polls Diia for the status until the person responds:

Status	Meaning
Initialized / Processing	The request is created; the system is waiting for the person to open and approve it in Diia.
Done	The person approved the request. The document package is ready and is downloaded and processed automatically.
Refuse	The person declined the request, or the link expired.
Not used	The link was not opened within its validity window.

You do not need to refresh anything manually — the wizard updates itself and moves to the results step once the documents arrive or the request fails.

Prerequisites

Diia Sharing relies on the SMART eSignature for Ukraine extension, which handles the connection to Diia. Before you can request documents, an administrator must:

• Configure the Diia service URLs and the partner access token in the eSignature setup.
• Register at least one Diia branch with Enable Sharing turned on.
• Configure the offers and sharing scopes (the list of document types your organization is allowed to request) for that branch.

The permissions to request a given document type are granted on the organization's Diia acquirer account and agreed with Diia. If a document type is not enabled for your organization, it cannot be requested.

If several branches have sharing enabled, you select the branch in the first step of the wizard. If only one branch is available, it is selected automatically.

Create a person from Diia

Use this flow to create a brand-new person record from shared documents.

1. Open the People list and choose Create from Diia.
2. In the Diia Document Sharing wizard, on the first step:
   • Select the Branch ID (and review the Branch Name).
   • Choose the Sharing Mode (Online or Offline).
   • Select the Document Type you want to request, or turn on Multi-Sharing to request several documents at once (online only — see Multi-Sharing).
3. Continue with the mode-specific step:
   • Online — Show the QR code to the person, or copy the Link and send it to them. Wait while they approve the request in Diia.
   • Offline — Ask the person to open the document in Diia and read the 13-digit barcode; enter or scan it, then continue.
4. The wizard shows a Waiting step while the person approves the request in Diia.
5. When the documents arrive, the Results step shows the received data: Document Type, Full Name, Taxpayer Number (РНОКПП), Document No., Date of Birth, and a full Summary. You can download the primary file or the whole package.
6. Finish the wizard. A new Person card is created and opened, with all recognized fields filled in and the PDF files attached.

Update an existing person from Diia

Use this flow to add or refresh data for a person who already exists — for example, to add a marriage record, update an address, or attach a new document.

1. Open the Person Card of the person.
2. Choose Functions → Update from Diia.
3. Go through the same wizard steps as above.
4. When processing completes, the system shows a confirmation that the person was updated.

When updating, the system is careful not to overwrite data that should not change automatically. In particular, if the person is already linked to an Employee, the name is not silently overwritten — instead, a name-change process is offered so the change is properly registered.

Identity matching and conflict resolution

Before writing the data, the system checks the identity read from the primary shared document — Taxpayer number (РНОКПП), date of birth and name — against existing persons, so the same individual is not duplicated and data is not written to the wrong card.

• When creating (Create from Diia): if a person with the same Taxpayer number (РНОКПП) + date of birth + name already exists, the system asks what to do:
  • Create New — create a new person anyway;
  • Update Existing — write the shared data to the existing person instead;
  • Cancel — stop without changes.
• When updating (Update from Diia): if the Taxpayer number (РНОКПП) read from the document differs from the current person's Taxpayer number (РНОКПП), the system warns about the mismatch and asks:
  • Update Current — apply the data to the current person anyway;
  • Create New — create a new person from the shared data;
  • Update Other — shown only when another person already has the recognized РНОКПП; applies the data to that person instead;
  • Cancel — stop without changes.

For documents that do not carry a stable identity (for example act records), this check is skipped and the data is applied directly.

Multi-Sharing (мультишеринг)

Multi-Sharing lets you request all document types configured in an offer in a single sharing session, with one confirmation from the person in Diia.

• Single sharing requests one document type. The person approves that one document, and the response contains that document (or several instances of the same type).
• Multi-Sharing requests every document type in the offer's scope at once — for example an ID card, a taxpayer card, and a birth certificate together. The person approves once, and the response contains all of them.

Multi-Sharing is available only in Online mode and only when the selected branch has an offer configured with more than one document type. The Multi-Sharing check box appears on the first wizard step only when these conditions are met.

When several documents are returned, the system processes each of them and writes the data from each into the appropriate place on the person card and related records.

Supported documents and how they are processed

The system recognizes the Diia document types below and maps each to specific person data. When a value is already present and should not be overwritten automatically (for example, the name of a person linked to an employee), it is preserved.

Diia document	What it fills in
ID card (internal passport)	Surname / First name / Patronymic (UA), Last/First name (English), Date of birth, Gender, Tax number (РНОКПП), Unique registry record number, Nationality, Registration address, Place of birth; creates a person document with number, issue date and authority.
Foreign (biometric) passport	Same identity fields as the ID card, including English names and registration address; creates the corresponding person document.
Taxpayer card (РНОКПП)	Surname / First name / Patronymic (UA), Date of birth, and the tax number.
Child taxpayer card	Creates the child as a relative (Child) with name, date of birth and gender.
Birth certificate (child's)	Creates the child as a relative (Child) with name, date of birth and gender; the signed PDF is attached to that relative record.
Own birth certificate (user-birth-record)	The person's own birth certificate. Fills the person's surname / first name / patronymic, date of birth, gender and tax number, place of birth, parents as relatives, and records the certificate as a person document.
Internally displaced person (IDP / ВПО) reference	Surname / First name / Patronymic, Date of birth, Gender, permanent address, place of birth; records the reference document.
Residence permit (permanent / temporary)	Identity fields incl. English names, tax number, registration address; records the permit document.
Driver license	Surname / First name / Patronymic including English names, Date of birth, Unique registry record number, records the driver license as a person document with document number, issue and expiration dates, issuing department.
Pension card	Surname / First name / Patronymic; records a pensioner privilege in medical info (pension type and case number) and the pension document.
Student ID card	Surname / First name / Patronymic, document number, issue and expiration dates.
Veteran certificate	Surname / First name / Patronymic; records the disability group and a Combatant Veteran privilege in medical info (with issue and expiration dates) and assigns the matching additional employment-guarantee code; records the certificate as a person document.
Education document	Creates a qualification record: institution, speciality, qualification, document series/number, study dates, faculty, and document type (Diploma / Other).
Name-change act record	Updates surname / first name / patronymic and date of birth. (The registration address is no longer taken from this document.)
Marriage act record	Sets family status to Married, creates the spouse as a relative (Spouse) with relation start date, names and date of birth.
Divorce act record	Sets family status to Divorced and closes the spouse relation with an end date.
OK-5 / OK-7 references	Received and attached for reference.

Marriage and divorce act records are processed after the other documents in the package, so that spouse data is not overwritten prematurely when several documents are shared together (multi-sharing).

Birth certificate (child's) can only be imported together with the parent's personal documents. This type of document is not used as a source for the initial creation of Person Card.

Person fields that get filled

For a physical person, the data returned by Diia is written to the following fields and related records.

Identity

Field	Source / notes
Surname (Прізвище)	From documents that contain a person’s full name (such as a passport, taxpayer card, driver license, etc.).
First Name (Ім'я)	Same sources.
Patronymic / Middle Name (По батькові)	Same sources.
Last Name (English), First Name (English)	From foreign passport, driver license and residence permit.
Date of Birth (Дата народження)	Protected once a tax number and birth date are already set.
Tax Registration No. (РНОКПП / ІПН)	Personal identification number for the individual.
Unique Registry Record No.	Registry record number.
Gender (Стать)	Mapped from the Ukrainian value (ч → Male, ж → Female).
Nationality / Citizenship	Mapped from the nationality value (for example, Україна → UA).

Addresses

Addresses are written to the person's alternative-address records:

• Registration address — region, district, city, street, house and apartment, parsed from the passport/permit registration data, with the registration date.
• Place of birth — city, district and region, parsed from the birthplace text.
• Permanent address — from the IDP (ВПО) reference.

Related records

• Person documents — ID card, foreign passport, driver license, student card, IDP reference, pension certificate, veteran certificate and others, each with number, series, issue/valid dates and issuing authority. The signed PDF is attached.
• Relatives — children (from birth certificate and child taxpayer card) and spouse (from marriage/divorce records), with names, dates of birth, gender, relation dates. The relative code is chosen by relation type and gender (for example son vs. daughter).
• Medical info —
  • Disability (from a veteran certificate), with disability group, start and end dates;
  • Combatant Veteran privilege (from a veteran certificate), with the matching additional employment-guarantee code, privilege type = Combatant Veteran, and start/end dates;
  • Pensioner privilege (from a pension card), with pension type, privilege type = Pensioner, start/end dates and case number.
• Qualification — education data from an education document, including the document type (Diploma / Other).

Notes and limitations

• Multi-Sharing is online-only. In offline mode you request one document at a time, because the barcode is tied to a specific document in the Diia app.
• Links are short-lived. An online sharing link (and an offline barcode) is valid for about 3 minutes and can be used once. Generate a new link if it expires.
• Files are stored as PDF. Documents arrive as signed envelopes; the signature wrappers (.p7s, .p7e) are removed and the PDF is attached to the corresponding record.
• Existing data is matched and updated, not duplicated. When a person, document or relative already exists, the system updates the missing values instead of creating a duplicate. Identity is matched on РНОКПП + date of birth + name; on a conflict you are prompted to create a new record, update the existing one, or cancel (see Identity matching and conflict resolution).
• Place of birth keeps the most detailed value. When a birthplace already exists, the system keeps the version with more detail (city / district / region / country) instead of blindly overwriting it, and uses the person's date of birth as the address validity date.
• Name protection for employees. If the person is linked to an employee, the name is not overwritten automatically; a Change Name report is used instead, dated from the act's registration date.

Related topics

• Person Card
• Person Document Recognition — Ukrainian ID Card
• Reserve+ QR Recognition