Persons¶

A person is an individual profile within an organization. It combines user identifiers, photos, verification status, and the history of associated Workflow sessions.

The person system recognizes returning users, adds data from new verifications to their profiles, and, when configured, reuses previously collected data.

Person data¶

flowchart TD
    P[Person] --> A[Aliases]
    P --> F[Photos]
    P --> V[is_verified status]
    P --> S[Workflow sessions]
    P --> H[Activity history]

Each person belongs to one organization. Aliases are unique within the organization and are used for lookup and duplicate prevention.

Aliases¶

An alias is an identifier that the system can use to find a person.

Type	Purpose	Details
`system_id`	Internal person UUID	Created automatically and cannot be changed
`phone`	Phone number	Can be extracted from an E-Document result
`personal_number`	IIN or another personal number	Can be extracted from a document
`document_number`	Passport or identity document number	Can be extracted from a document result
`custom`	Client system identifier	Supplied by the client system

A person can have several aliases of different types. Each alias value must be unique within the organization.

Photos¶

A profile can contain photos from different sources. Priority determines which image is preferred as the primary photo:

Type	Priority	Source
`digital`	1	Digital photo from E-Document
`scan`	2	Portrait from a scanned document
`live`	3	Best Liveness frame
`other`	4	Manually uploaded photo

A lower number means a higher priority. When a photo with a higher-priority type is added, the system can make it the primary photo. The only primary photo cannot be deleted.

Verification status¶

The is_verified field indicates whether the person's identity has been verified. With automatic data collection, the status can be determined by the Face2Face result or set by the Workflow's forced verification option.

Do not use the existence of a person as proof that the current session succeeded. Make business decisions using the current session result.

Automatic data collection¶

If person collection is enabled in the Workflow configuration, the system processes results in the background after a session ends:

Extracts aliases and photos from technology results and metadata.
Searches for an existing person by the aliases found.
Updates the matching profile or creates a new one.
Adds new aliases and photos without duplicating existing data.
Selects the primary photo according to priority.
Associates the session with the person.

Automatic collection sources:

Source	Data
E-Document	IIN, document number, phone number, and `digital` photo
Document Recognition	Personal number, document number, and `scan` photo
Liveness	Best `live` frame
Session metadata	Client system alias

Processing runs asynchronously after the session ends, so profile changes may not appear at the same time as the Workflow interface reports completion.

Associate a session with a person¶

When creating a session, pass any alias of an existing person or a new unique client system identifier:

{
  "api_key": "<FLOW_API_KEY>",
  "metadata": {
    "person": {
      "alias": "<PERSON_ALIAS>"
    }
  }
}

The alias type is not passed separately:

if the value matches any alias of an existing person in the organization, the system associates the session with that person;
if the value is not found and person collection is enabled, the system creates a new person and adds the supplied value as a custom alias.

Person settings in a Workflow¶

Setting	Behavior
Person collection	Automatically creates and updates profiles from completed sessions
Forced verification	Creates new persons with `is_verified = true` regardless of the Face2Face result
Skip existing results	Finds a person by `metadata.person.alias` and can use results from previous technologies
Use for Face2Face	Uses a suitable person photo as the reference image for comparison

If person collection is disabled, automatic creation and association stop, but manual management through the Backend API or dashboard remains available. Configuration changes affect new sessions and do not modify existing profiles retroactively.

Repeat verification¶

To verify a known user again:

Retrieve one of the person's aliases from your system.
Pass the value as metadata.person.alias when creating a new session.
Start the Workflow as usual.
Retrieve the new session result and make a decision using current data.

If skipping existing results is enabled in the Workflow, the system can copy a suitable result from a previous session and avoid running the corresponding technology again. If using a person's photo for Face2Face is enabled, the system selects a reference image with this priority: digital → scan → live.