Tracking References

What is a Tracking Reference?

A tracking reference is a single-use identifier issued for one customer onboarding visit. It works like a one-time password: each tracking reference represents a single attempt to onboard a customer with your organisation, and a fresh one is issued for each visit rather than reusing an existing one.

You create a tracking reference by calling POST /v1/user/invite. There is no limit on how many you may issue for the same customer and organisation, and there is no cost to doing so.

Recommended Integration Pattern

We recommend the following pattern for working with tracking references:

1. Issue a fresh tracking reference for every customer visit, including when a customer returns to continue onboarding they previously started.
2. Persist the most recent tracking reference for each (customer, organisation) pair on your side, and read status from that one.
3. Treat tracking references as disposable. There is no API to resume a previous tracking reference, and we recommend against attempting to detect or recover abandoned sessions on the partner side. Session continuity is handled within VerifiMe: when a customer returns after stepping away, issuing a new tracking reference allows them to pick up where they left off without any additional integration work on your part.

When this pattern is followed, the states typically observed in practice are Inactive (the customer has not yet started this visit) and Completed (the customer has finished). The Active state is a transient signal during a single visit and generally does not need to be rendered or recovered across visits.

Status Lifecycle

A tracking reference progresses through the lifecycle in one direction only. It does not move backwards or reset.

What Completed means. A status of Completed indicates that the customer has finished the information they need to provide. Identity verification, biometric checks, DVS validation, and risk assessment are run by VerifiMe as a separate phase after data submission, and that phase takes time to complete. By design, the verification phase is handled internally by VerifiMe and does not require partner integration; there is no partner-visible status for it. See Integration Flow for the full two-phase model.

A note on Active. The Active state indicates a session is in flight, but does not distinguish between an in-progress session and one the customer has stepped away from. For this reason, persisting an Active tracking reference and attempting to resume it on a later visit is not supported; issuing a new tracking reference on the next visit is the recommended approach.

What Tracking Status Does Not Indicate

A tracking reference's status reflects only the progress of customer-supplied information. It does not indicate:

• Whether identity verification passed or failed
• Whether biometric checks were completed
• Whether DVS validation succeeded
• The result of any risk assessment
• The entity type that was verified
• Whether the verification has been approved

These outcomes are produced by the verification phase that runs after the customer has finished their part, and are surfaced through the appropriate VerifiMe endpoints rather than the tracking reference itself.

When to Check Tracking Status

Automatic polling by the widget. The VerifiMe widget polls the tracking status endpoint automatically using exponential backoff (starting at one second, capping at ten seconds), and pauses polling when the browser tab is hidden. You do not need to poll this endpoint directly.

Optional manual polling. If you need to check status outside the widget context, you may poll GET /v1/user/signup/tracking/{trackingReference}/status. We recommend reading status from the most recent tracking reference for the (customer, organisation) pair, in line with the integration pattern above.