Journeys and tags

A journey is the moment your backend asks for an assessment (POST /v1/assessments): a login, a withdrawal, an order. It is not a page; the Web SDK collects on whatever page the action happens.

There are two request profiles on the same route, with the same HMAC authentication:

Profile	schema_version	How the moment is named
v1.1	event-assessment-request.v1.1	A free tag that you choose (login, saque, pix_transfer, trade…)
v1	event-assessment-request.v1	One of three fixed journeys: LOGIN, WITHDRAWAL or TRADE

Each call picks its profile by its schema_version; there is nothing to configure per application. New integrations should use v1.1. If you are on v1 today, see moving from v1 to v1.1.

Both profiles are accepted in production

Production accepts the v1.1 request with your tag. The v1 request is unchanged and stays accepted, so an integration on v1 keeps working as it is.

The v1.1 tag

tag is a slug that names the call site in your system. It has no registration, no limit, no activation and no list to keep in sync with FingerTrackID: send it on each call.

• Grammar: ^[a-z0-9][a-z0-9_]{0,63}$. Lowercase ASCII letters, digits and underscore, 1 to 64 characters, starting with a letter or a digit. There is no normalization: Login, pix-transfer or saque (with a space) are refused, not corrected.
• At most ten digits in total. Eleven or more digits are refused, together or apart (cpf_12345678901 and cpf_123_456_789_01 alike), because that is the shape of a tax ID or a phone number. This check does not prove the tag is free of personal data: that guarantee is yours.
• No personal data. Never put an email, tax ID, phone number, name, user ID, account number or Pix key in the tag. A tag names a moment of your product, never a person.
• The tag is part of the operation’s identity. A retry must repeat the whole body, tag included; the same external_event_id or idempotency_key with another tag is 409 idempotency-conflict.

What the tag changes, and what it does not

The tag organises your reading. On the console you filter accesses by tag, see the volume and status of each tag, export it, and read how many events with the same tag reached the same account (when you send account_ref) or the same device in the last minute, five minutes and hour.

The tag does not change how FingerTrackID assesses. Every v1.1 request runs the same internal behaviour, whatever its tag:

• the same evidence and the same policy give the same status, score and recommendation under any tag;
• the deadline_ms range is the same for every tag (250–5000 ms, default 5000 ms when null);
• the tag never selects a policy, a detector, a provider, a fallback, a quota or a price;
• the tag never appears in FingerTrackID’s metrics, logs or traces.

Pick tags that are useful to read. The journey templates suggest when to call, what to send and what to look at for ten common moments; they are guidance only and have no effect on the assessment.

Example

The v1.1 body has no amount, currency, order or beneficiary field. FingerTrackID assesses the device and the access; your system already has the transaction. Context items that depend on an amount or a beneficiary come back not evaluated for a v1.1 event, with a reason that says the request does not carry them.

{
  "schema_version": "event-assessment-request.v1.1",
  "external_event_id": "evt_withdrawal_0001",
  "idempotency_key": "idem_evt_withdrawal_0001",
  "occurred_at": "2026-11-03T14:05:22.481Z",
  "subject_ref": "usr_5c0e",
  "account_ref": "acc_77d2",
  "event_context_token": "ect_withdrawal_0001",
  "tag": "saque",
  "deadline_ms": null
}

The v1 profile

The v1 profile has three fixed journeys. Each one defines the action, which references are required, the shape of journey_context and the technical budget deadline_ms. It stays accepted, unchanged, for integrations that use it.

Journey	action	subject_ref and account_ref	journey_context	deadline_ms when null	Explicit range
LOGIN	LOGIN_ATTEMPT	May be null; account_ref requires subject_ref	{}	5000	250–5000
WITHDRAWAL	WITHDRAWAL_REQUEST	Both required	amount_minor, currency, beneficiary_ref	1000	500–1000
TRADE	TRADE_REQUEST	Both required	{}	750	250–750

WITHDRAWAL

• amount_minor is a positive integer in the currency’s minor unit — centavos for BRL: 150000 = R$ 1,500.00. Never a decimal.
• currency is the uppercase ISO 4217 code (^[A-Z]{3}$), and the currency must be on the allowlist of your application’s policy.
• beneficiary_ref is an opaque pseudonym of the beneficiary, created by your backend.

{ "amount_minor": 150000, "currency": "BRL", "beneficiary_ref": "beneficiary_789" }

TRADE

An order does not trigger a new collection or an external lookup per order: it reuses the session’s fresh evidence. In the browser, several orders can come from the same accepted collection, each with its own event context (see the SDK). In v1.1 the same flow uses the tag trade (orders, one assessment each).

deadline_ms

• It is an internal technical budget, counted from when the request enters the service. A number can only reduce the default.
• This is not an SLA. It does not change the score or the evidence and is not part of the operation’s identity: changing only deadline_ms on a retry keeps the same operation.
• Your HTTP client timeout must add network latency on top of the budget. For a LOGIN (v1) or any v1.1 tag sent with null, that means a timeout above about 6 s (5000 ms plus the network). A body that signs deadline_ms explicitly may send any value up to 5000, or null; a body already signed with 750 or 1000 stays valid and keeps exactly that budget.

Action when there is no score

When the assessment does not end in COMPLETED (INCONCLUSIVE, UNSCORABLE or FAILED), the recommendation is MONITOR: for every v1 journey and for every v1.1 tag.

MONITOR is a neutral contingency. It is not a favourable score, an authorization or an action taken; your system still decides what to do. recommendation_basis tells you why there is no score.

Assessments created before this change may carry STEP_UP (LOGIN) or REVIEW (WITHDRAWAL) without a score, and the v1 schema still accepts them. Code against the fields you receive (recommended_action, recommendation_basis, fallback_policy_version), not against a fixed table. No state without a score receives ALLOW.