Person: purpose and use in Workflow¶

Person is an individual profile within an organization. It combines user identifiers, photos, verification status, and associated Workflow sessions.

Person supports returning users: your system finds a known user, passes their identifier to a new session, and can use a saved photo or eligible results from previous checks. This reduces repeated data entry and requests to data sources.

This section contains three articles:

• Purpose and use in Workflow — this article.
• Photos and verification — reference selection, Face2Face, and temporary photos.
• Person Integration API — managing profiles, aliases, and photos from your system.

Profile contents¶

Each profile belongs to one organization. Searches and API operations are restricted to the organization associated with the key.

The existence of a Person with is_verified=true does not confirm that a new attempt succeeded. Base business decisions on the current session result, taking failure reasons into account.

Aliases¶

An alias is a value used to find a person. A person can have multiple aliases.

Types are case-sensitive. An alias value is unique within the organization, regardless of type. To associate a person with a Workflow, pass only the value, without its type.

Workflow lookup and exact retrieval through the API use active aliases. An expired alias is not eligible for exact lookup even with include_expired=true: this parameter expands the data included in the returned profile. See Retrieving a person.

If aliases extracted during automatic lookup belong to multiple persons, the system does not merge those profiles automatically: Person processing ends with a conflict. Use a stable, unique identifier from your system and check that aliases identify the correct person.

How profiles are created and updated¶

You can create a profile through the Integration API or have it collected automatically from Workflow results.

When a session completes normally with status FINISHED, background processing starts if the Workflow has a Person configuration:

1. The system uses the person found when the session started, or searches for a profile using aliases from the results and metadata.
2. If a profile is found, it adds data and associates the profile with the session.
3. If no profile is found and collection is enabled, it creates a person from the available data. No profile is created if no data was extracted.
4. It adds aliases and photos according to the deduplication rules.
5. It updates verification status and selects the default photo.

Processing is asynchronous: the Workflow may finish before the updated profile becomes available. Creation requires an eligible Person subscription with available capacity.

Data sources¶

Photo processing accounts for the source result, so sharing the same type does not mean two images are duplicates. For PPS, individual photos from the same result are saved; processing the same image again does not create another copy.

A new original PPS result with photos moves previously active PPS photos into history with reason SOURCE_REPLACED. This does not expire photos from other sources. A copied PPS result does not update the profile as a new source. See the photo lifecycle.

If a profile already has an active PERSONAL_NUMBER and PPS returns a different IIN, the new PPS alias is not added; the conflict is recorded in the history. This rule is not a general mechanism for automatically merging or correcting persons.

Associating a person with a new session¶

When creating a session, pass the alias value:

{
  "api_key": "<FLOW_API_KEY>",
  "metadata": {
    "person": {
      "alias": "customer-1042"
    }
  }
}

This request requires the Workflow key. Direct Person management uses the organization key.

When a Workflow with Person starts, the system searches for a profile by active alias within that Workflow's organization. The profile found is used for repeat checks. The session creation request itself does not create a Person.

If the alias is new, the profile may be found using other extracted identifiers when the session finishes, or created if collection is enabled. The supplied identifier is added as CUSTOM if it does not conflict with existing data.

Person settings in Workflow¶

These settings apply to the Person technology in the selected Workflow.

Disabling Automatically save personal data prevents automatic creation of new profiles, but does not stop an existing person from being updated or associated with the completed session. Lookup, result reuse, and photo use are controlled separately.

Skip person verification applies during creation. Existing profiles follow the status update rules.

Reusing results¶

When metadata.person.alias is supplied and Skip technology with existing Document result is enabled, the system can copy a result into the new session and skip running the technology again.

The result must belong to a session associated with this person, and the technology must be included in the current Workflow. For each technology, the system selects the latest eligible original result, then checks its validity limits. If it fails those checks, older results are not considered.

• saved_result_ttl_days is measured from the original result's creation date. Copying does not extend its validity.
• When a minimum remaining validity is configured, the document expiry date must be strictly later than today's date plus that number of days. With a value of zero, a document expiring today is not eligible.
• If document expiry checking is enabled but the date cannot be obtained or parsed, the result is not reused.
• null disables the corresponding limit. Document expiry limits apply to E-Document and Document Recognition; PPS is subject to the result age limit.

Having a Person or a photo does not allow arbitrary technologies to be skipped: this mechanism is implemented for the three sources in the table. Liveness and Face2Face follow the current Workflow's rules.

Saved result validity and temporary photo validity are separate settings. A temporary photo does not itself enable or disable PPS result reuse.

Returning user scenario¶

1. Find the profile through the Integration API or use a saved alias.
2. Choose a Workflow with the required checks and Person settings.
3. Create a separate session with metadata.person.alias.
4. Launch it through Remote, Widget, or WebView.
5. Retrieve the session result; use webhooks to handle events if needed.
6. Retrieve the updated profile, allowing for background processing.

For changes in appearance, see Temporary photos. For profile management requests, see the Person Integration API.