Understanding the Request State Machine

The core unit of interaction for end users of Nametag is the request. At a high level, a request is created, delivered to the user, and completed by the user. Throughout this process, the data attached to the request is accessible via the console, APIs, or webhooks.

The goal of this document is to explain how the underlying state machine for requests functions and how to interpret its outputs.

States

The current state of a request is represented by the state field. This information can be viewed directly via the API or webhooks. Below is provided a table with a list of all states that a request can possess and an explanation for what that state means.

State	Meaning
`new`	Request has been created, but not yet opened by the subject.
`opened`	The subject has opened the request or link and is in the process of verifying their identity.
`success`	The identity has been verified.
`rejected`	The identity could not be verified, but the subject has the option to attempt to verify their identity again.
`abandoned`	The subject did not complete the process. A request can become abandoned if too much time elapses after the requests entered opened, or if the app is closed without succeeding. However, the subject can select the link again and return to opened.
`possible_fraud`	The identity could not be verified, and the subject has not appealed. A Nametag investigator may look at the scan and issue a review. In that case, the request moves to abandoned if successful, or fraud/unusable if rejected by the Nametag investigator.
`fraud`	The evidence provided by the subject is fraudulent.
`unusable`	The evidence provided by the subject is not fraudulent, but cannot be used.
`appealed`	The subject has appealed a rejection, but the appeal has not yet been reviewed.
`expired`	The request has expired.
`canceled`	The requester has canceled the request. A request can be canceled from any non-terminal state.
`deleted`	The subject associated with the request has deleted their data.

There are three important things to note about the states:

All requests start in the new state.
success is not a terminal state. This reflects the core nature of Nametag, that data provided by end users is only shared for a limited time at the behest of the end user.
The only terminal states are expired, canceled, and deleted. This is important to note when looking back at historical data, because all requests eventually transition into one of these three statuses.

The state provides a momentary view of what the current status of the request is. For additional information about what the user is doing or how they are moving between states, it is critical to look at the events on the request.

Events

When an action relevant to a request occurs, that action is recorded on the request in the events field which is accessible via the API or webhooks. This field records an ordered list of all interactions that happened during the lifetime of the request. While the majority of events are generated by end users, there are several events that are created outside their interaction with the app.

The table below provides a list of all events and descriptions of what that event entails. Events are listed in the general order in which a user would encounter them.

Event	Meaning
`link_opened`	The request link has been shown, but the subject has not yet opened the Nametag app. Some messaging apps, such as Slack, may open the link when shared to generate previews.
`app_opened`	The subject has opened the request in the Nametag app.
`consent_given`	The subject has consented to data sharing and use of biometrics.
`scan`	The subject has opened a scan.
`expired`	The `expires_at` time of the request has passed.
`success`	The evidence provided by the subject has been accepted.
`finished`	The subject has completed the verification process and their identity has been verified.
`rejected`	The evidence provided by the subject has been rejected.
`canceled`	The requester has canceled the request.
`appealed`	The subject, having been rejected, has appealed the rejection.
`review_accepted`	The Nametag investigator has accepted the evidence provided by the subject after an appeal.
`review_rejected`	The Nametag investigator has rejected the evidence provided by the subject after an appeal.
`customer_fraud_reported`	The customer has reported fraud.
`abandoned`	The subject has abandoned the request e.g. by closing the app without completing the scan.
`recovered_account`	The subject has successfully linked their device to an existing Nametag identity (Magic Account Recovery).
`person_deleted`	The subject has chosen to delete their Nametag data.

Many events can happen multiple times in the course of a single request. For example, if a verification link is forwarded to an end user over Slack, the link_opened event may be dispatched twice as first Slack opens the verification link and then a second time when the end user opens the link again.

Most events will have additional metadata attached to them; for more details on the structure of these events, see the API reference for request events.

To help provide context for what an example user experience would look like when viewed through request events, some examples are provided below.

Example successful request

In a successful case, a user is sent a request and completes it successfully. In that case, the events on the request might look like:

link_opened - The end user opens the link.
app_opened - The end user opened the Nametag app.
scan - The end user began a scan.
success - The evidence provided by the user was approved.
finished - The end user agreed to share their data.

Example rejected requested

In some situations, an end user may provide unacceptable evidence that Nametag rejects. When this happens, Nametag provides context on why they were rejected and the end user may scan again to attempt to fix the problem.

link_opened - The end user opens the link.
app_opened - The end user opened the Nametag app.
scan - The end user began a scan.
rejected - The evidence provided by the user was rejected. As part of the rejection, the user is provided context on why the evidence was rejected and how to fix the problem.
scan - The end user began a scan. They are now aware of the issue with the previous scan and can complete the scan successfully.
success - The evidence provided by the user was approved.
finished - The end user agreed to share their data.

Example appealed request

Nametag allows end users to appeal a rejection. If that happens, the series of events could appear as such:

link_opened - The end user opens the link.
app_opened - The end user opened the Nametag app.
scan - The end user began a scan.
rejected - The evidence provided by the user was rejected.
appealed - The user appeals the rejection.
review_accepted - The appeal is accepted by Nametag. When this happens, a notification is sent to the user’s phone to encourage them to return to complete the request.
app_opened - The end user has returned to the Nametag app.
finished - The end user agreed to share their data.

In some situations, the user may not be able to return to the existing request because it has expired or possibly due to automation built up around OIDC interactions. If that happens, the events described above may end up split between two separate requests. In situations such as those, it is advisable to use the subject field on the request to bridge the events from those requests together.

Example fraudulent request

If Nametag determines that the evidence presented by an end user is fraudulent, the request may be marked for fraud. One example of a request where fraud is detected is shown below. Not all cases of fraud will look like the following, however.

link_opened - The end user opens the link.
app_opened - The end user opened the Nametag app.
scan - The end user began a scan.
rejected - The evidence provided by the user was rejected.
appealed - The user appeals the rejection.
review_rejected - The appeal is rejected by Nametag.

In this situation, metadata will be attached to review_rejected to indicate that it was rejected for fraud. For more details on the structure of events, be sure to consult the API reference for request events.

State diagram

The following two diagrams give a basic, graphical overview of how a request transitions between states based on the events received.

At a high level, there are three basic groups of states for requests:

New - This covers only the new state. Requests in this state have had no user interaction.
Finished - This covers the canceled, expired, and deleted states. User interaction with the request is no longer possible.
Active - All other states occur in this state group. While in this group of states, the request is open to user interaction and may change state in various ways.

flowchart TD New --> Active Active --> Finished

The diagram below shows state progressions that are possible after a request leaves a New state and before it reaches a Finished state.

There are two categories of events that are not described by this diagram:

consent_given & recovered_account - These events do not alter the state of the request.
canceled, expired, & person_deleted - These events transition the request to a finished state, effectively exiting the described diagram.