> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qa.esectra.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Return flow

> Bring the person back to your platform with a one-time result code, and exchange it for the result.

A published flow may carry a **return URL**. When a hosted session under that flow finishes, the completion screen still says only that the submission is done - and offers a *Return* button. The button leads to your URL with three query parameters:

| Parameter | What it is |
| - | - |
| `code` | A one-time result code: 256 random bits, valid for ten minutes, exchangeable once by your API key. |
| `session_id` | The `verification_session_id` you were given when you opened the session. |
| `state` | The value you passed as `state` when opening the session, unchanged. Absent if you passed none. |

Nothing else is in the URL. No verdict, no personal data, no API key, and never the capture token - the code is minted separately, after the session has concluded, and the two have nothing in common.

## Configure the return URL

The URL belongs to the flow, set by an organisation admin, and is frozen into each session when it opens. Nothing in the capture link, the query string or the person's browser can change where they are sent. It must be `https` with a host and no credentials or `#fragment`; a deployment running a development profile also accepts `http://localhost` and `http://127.0.0.1`. Existing query parameters on your URL are kept; `code`, `session_id` and `state` are appended.

## Exchange the code

Your server receives the redirect and exchanges the code under its API key:

```bash theme={null}
curl -X POST "$ESECTRA_BASE_URL/v1/verifications/result-codes/exchange" \
  -H "Authorization: Bearer $ESECTRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"code":"'"$CODE"'"}'
```

The answer is the session's result:

```json theme={null}
{
  "verification_session_id": "vs_...",
  "subject_id": "customer-123",
  "status": "PASSED",
  "intent": "FIRST_TIME",
  "flow": { "flow_id": "vf_...", "revision": 1, "flow_type": "FULL_IDENTITY" },
  "decision_id": "verify-vs_...",
  "decision": "ALLOW",
  "risk_level": "LOW",
  "reasons": [{ "code": "ALL_REQUIRED_CHECKS_PASSED", "message": "Every check the policy required was satisfied." }],
  "checks": [{ "check": "FACE_MATCH", "outcome": "PASS", "reason_code": "FACE_MATCH", "detail": "The live capture matches the reference face." }],
  "review_case_id": null,
  "created_at": "...",
  "completed_at": "..."
}
```

Reasons and check details are worded from fixed vocabularies keyed on stable codes - the same wording Control shows. No score, model name or threshold is ever in them; a stored code the API does not describe is reported as `UNSPECIFIED`.

The exchange is atomic and single-use: the code is bound to your tenant, spent by the request that wins, and refused afterwards. Refusals are `404 RESULT_CODE_INVALID` (no such code for your tenant - another tenant's code looks exactly like this), `409 RESULT_CODE_CONSUMED` (already exchanged) and `410 RESULT_CODE_EXPIRED`. If a store fails after the code has been spent, the answer is `503 RESULT_UNAVAILABLE_AFTER_EXCHANGE` and its message names the session id to read instead; the code is not given back.

## Read the result without the code

The code is a pointer, not the only way in. Read the same result at any time by session id with your API key, so a lost exchange response or a missed webhook costs nothing:

```bash theme={null}
curl "$ESECTRA_BASE_URL/v1/verifications/sessions/$SESSION_ID" \
  -H "Authorization: Bearer $ESECTRA_API_KEY"
```

A session that has not finished reads as `status: "PENDING"` with no decision.

## What is recorded

Issuing, exchanging and refusing a code are audit events (`RESULT_CODE_ISSUED`, `RESULT_CODE_EXCHANGED`, `RESULT_CODE_REFUSED`) that name the session and the outcome. The code itself is stored only as a hash and appears in no log or audit event.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.