Skip to content

Person photos and verification

Person photos let you use a saved image as the reference for a repeat face comparison. A profile can contain multiple images; the default is selected based on its source, manual assignment, and validity period.

For profile creation and settings, see Person and Workflow. For requests, see the Person Integration API.

Photo type and source

API type Content
DIGITAL A digital photo, including one from PPS or E-Document
SCAN A portrait extracted from a recognized document
LIVE The best Liveness frame
OTHER Another image, such as one uploaded by the organization

Type and source are separate fields. A manual upload through the API receives source MANUAL and is_uploaded=true, even when its type is DIGITAL. The type does not make it a PPS photo.

How the default photo is selected

Automatic selection considers only active photos that have not been deleted:

  1. An active temporary photo has the highest priority.
  2. A manually assigned default photo with source MANUAL is retained.
  3. Other photos follow the order in the table.
Priority Type and source
1 DIGITAL from PPS
2 DIGITAL from E-Document, including a child's document
3 SCAN from Document Recognition
4 LIVE from Liveness
5 Other combinations of type and source, including legacy data with an unknown source

When priorities are equal, default assignment is considered first, then the newer photo is preferred. When a new PPS result is collected, one of its photos is marked as preferred.

Through the API, a permanent photo becomes the default when is_default=true is explicitly supplied. Uploading with is_default=false alone does not trigger automatic priority selection.

A permanent photo with is_default=true cannot be deleted: assign another default first. Temporary photos follow a separate deletion rule that restores a reference photo.

Use in Face2Face

The Workflow must include Person with Use person's photo for F2F comparison=true. The person is identified using the association saved when the session started or metadata.person.alias. Its current default photo is used.

A supplied metadata.face2face.photo1 takes priority: the Person photo is not added to the comparison in this case. See Face2Face metadata.

In the automatic scenario with active Person + PPS + Face2Face + Liveness, without explicitly supplied images or face2face.photo1, the system selects:

  • the best frame from a successful Liveness check in the current session;
  • the default Person photo, if available for this scenario;
  • if no Person photo is selected or its file is unavailable, a photo from a successful PPS result in the current session.

If required images are missing, the comparison fails with a missing-images error. See Face2Face for comparison inputs and results.

Verification status

is_verified is a profile status that can be set automatically or by the organization:

  • automatic creation considers a successful Face2Face result; Skip person verification=true forces the status to true for a new person;
  • when an existing person is updated, a successful Face2Face result can set it to true; an unsuccessful result alone does not clear a previously set status;
  • the Integration API allows is_verified to be changed explicitly;
  • expiration or deletion of a temporary photo clears the status if no permanent reference can be restored.

Uploading a temporary photo does not itself verify identity and does not require is_verified=true. Checking that the uploaded image belongs to the person remains part of the organization's process: uploading does not start a biometric comparison.

For decisions about a new attempt, check the session result, not just the Person status.

Temporary photos

A temporary photo is an uploaded image with an expires_at value that becomes the default for a limited period. For example, an organization can assign an up-to-date reference when a user's appearance changes temporarily.

Temporary is not a separate photo type: you can use OTHER or another allowed type and set the expiry separately.

Assignment

Add a photo through the API with a future expires_at in ISO 8601 format with a timezone, such as 2030-10-01T12:00:00+05:00. Choose a date that is still in the future when you send the request.

When assigned:

  • the photo becomes the default, even if is_default=false was supplied;
  • a reference to the previous default photo is saved;
  • the previous photo remains in the profile but is no longer the default;
  • a person can have only one active temporary photo.

While it is active, you cannot add a second temporary photo or assign another default. You can add permanent photos with is_default=false. Automatic collection of new photos, including PPS photos, preserves the temporary photo's priority.

Changing the expiry

Use photo update to extend or shorten the validity of an active temporary photo. The new date must remain in the future.

You cannot:

  • extend an expired or deleted photo;
  • remove the expiry from a temporary photo;
  • convert a permanent photo to a temporary one through an update;
  • clear is_default on an active temporary photo.

Omitting expires_at leaves the expiry unchanged. An explicit null is not allowed in an update request. This contract does not limit the maximum validity period or number of extensions.

Replacement and early removal

To replace the image, delete the current temporary photo and upload a new one with a new expiry. Updating a photo through the Integration API changes its properties but does not accept a new file.

A temporary photo can be deleted even when it is the default. Deletion immediately triggers restoration of a permanent reference. Deletion and the subsequent upload are separate requests: between them, the restored photo is already in use, or the profile has no default photo.

If no permanent photo exists, deletion clears is_verified. Uploading another temporary photo does not itself restore that status.

Expiration and restoration

A photo is valid while the current time is strictly earlier than expires_at. Once expires_at is reached, it stops being used as a reference.

The system selects a replacement in this order:

  1. It restores the previous permanent default photo if it is still active and has not been deleted.
  2. Otherwise, it selects an eligible permanent photo according to the priority rules.
  3. If no eligible photos exist, the profile has no default photo and receives is_verified=false.

Successful restoration preserves an existing is_verified=true; it does not automatically change false to true.

API reads and reference selection account for expiration whether or not background processing has run. Background processing records expiration and restoration actions in the history.

If Face2Face has already selected a photo that was valid at selection time, later expiration does not change the pair used by the comparison in progress. The next selection uses the current state.

If the profile has no reference after expiration, the organization chooses the next Workflow with the required image sources and checks.

Active photos and history

Field Meaning
expires_at Scheduled expiry of a temporary photo; null for a permanent photo
is_expired The photo has been removed from active use
expired_at Date of expiration or transfer to history
expiration_reason Reason, such as TTL or SOURCE_REPLACED
source_technology_code Image source
is_default Whether the photo is the current default

Expiration and deletion are different. Expired photos are retained and available when reading with include_expired=true. Deleted photos are not returned even with this parameter.

When a new original PPS result with photos is received, previously active PPS photos move into history with SOURCE_REPLACED. If the previous permanent reference became inactive while the temporary photo was in use, another eligible permanent photo is selected after expiration.

The PPS replacement rule does not automatically expire all older E-Document or Document Recognition photos. Document result reuse validity is configured separately in Person and Workflow.

Next steps