---
title: "Identity verification FAQ and troubleshooting"
description: "Short answers to the questions integrators ask about hosted identity verification: statuses, review, links, keys, events, the Verification ID and data, plus a five-step triage."
canonical_url: "https://noxtica.com/docs/identity-verification-faq/"
markdown_url: "https://noxtica.com/docs/identity-verification-faq/index.md"
last_updated: 2026-10-27
published: 2026-10-27
section: "identity-verification"
section_title: "Identity Verification"
site: "Noxtica"
language: "en"
source: markdown
---

# Identity verification FAQ and troubleshooting

This page answers the questions that backend engineers and Backoffice operators ask most about hosted identity verification. Start with the concept answers, use the five-step triage when something looks wrong, and use the troubleshooting tables to match a symptom to a fix.

## What it is

Availability: Controlled availability. Identity verification is provisioned by your account team, and optional steps apply when they are enabled for your organisation. Every answer below follows the behaviour of the hosted flow described in [Identity verification integration](https://noxtica.com/docs/identity-verification-integration/).

### Sessions and results

**What do I get back when I create a session?** A `sessionId` and a single-use `url`. Store the `sessionId`, send the customer to the `url`, then read the outcome by status read or by a signed event. See [Identity verification integration](https://noxtica.com/docs/identity-verification-integration/).

**What is the difference between `completed`, `unverified`, `error` and `review_pending`?** `completed` means a decision approved the session. `unverified` is a negative outcome. `error` means processing could not finish. `review_pending` means a person in your Backoffice must decide. It is neither an approval nor a rejection. Only `completed` is an approval.

**Why does my session wait in `review_pending`?** A finished capture currently waits for a decision in Backoffice → Identity Verification → KYC Review Queue. A session in `review_pending` does not expire while it waits. An administrator selects "Approve" or "Override", and either completes the session. "Record escalation" leaves the session as it is. There is no separate reject decision today.

**Is a result a decision about my customer?** No. A result is an automated signal. You decide what it means, and a person in your organisation should review any adverse decision before it affects a customer. Results can be wrong in either direction and are not legal proof of identity.

**Can I embed the hosted page in an iframe?** No. The page refuses to load inside a frame. Open it as a full page or in a new tab. It does not post a message to your page and does not close itself, so learn the outcome by status read or event.

**Can I set the language of the hosted page?** No. The language comes from the customer's browser, and the link accepts no parameters beyond its own path.

**How long does a link stay valid?** An unopened link stays valid for 86400 seconds by default. You can set `expiresInSeconds` from 300 to 604800. After the customer opens the link, the customer has 30 minutes to finish, or until the original expiry if that is sooner. See [KYC Hosted Sessions](https://noxtica.com/docs/kyc-hosted-sessions/).

**Can I resend, revoke or cancel a hosted link in Backoffice?** No. Backoffice has no such control for hosted links. If a link is lost or no longer wanted, create a new session and let the old one expire. Retrying with the same `Idempotency-Key` returns the same `sessionId` without the `url`.

**Do I need a return link?** No. `returnUrl` is optional. It must be an `https` address whose host you approved in Backoffice → Identity Verification → KYC Invitations → Settings. After a completed outcome the page shows a plain link to it. There is no automatic redirect, and the address carries no session id or status. Never treat a visit to your return page as proof of completion.

### Keys and events

**Which key do I use?** Create a key with the "Verify identity documents (KYC)" permission in Backoffice → API & SDK → Server API Keys. Server keys start with `sk_prod_`. Never put the key in a browser or an app.

**Should I poll the status or use events?** Use both. Events save you from polling, and the status read is the authority. When you poll, increase the delay between reads and stop at a final status.

**Which events can I receive, and do they carry my customer reference?** `kyc.session.completed`, `kyc.session.cancelled`, `kyc.verification.completed`, `kyc.erasure.completed`, `kyc.document.expiry_warning` and `kyc.reverification.due`. Some depend on settings for your organisation. Events never carry your `subjectRef`: match an event to your customer by `sessionId`. The status read returns your reference as `subjectId`. See [Identity verification events and webhooks](https://noxtica.com/docs/identity-verification-webhooks/).

**Why do I see the same event twice, or in a different order?** Delivery is at least once and order is not fixed. Deduplicate on `X-Noxtica-Delivery`, then read the status before you act.

### Data and identifiers

**What is a Noxtica Verification ID?** A short reference that a hosted session receives when it completes or waits for review. It is not a credential. See [Noxtica Verification ID](https://noxtica.com/docs/identity-verification-id/).

**What data does Noxtica keep, and can I delete it?** Noxtica does not delete verification details or evidence automatically, and it sets no retention date for them. They stay until a tenant administrator deletes them, so verification data is never deleted automatically. An administrator deletes verifications in Backoffice → Identity Verification → KYC Verifications: select **Delete verification** on a case, or tick several rows and select **Delete selected** (up to 25), give a reason, type the confirmation phrase and complete the step-up check. The delete removes the verification and its evidence files and keeps the billing usage records, the legal-basis receipts and the audit trail. Right-to-erasure requests are handled in KYC Erasure, where a request is approved by an administrator other than the requester. See [Identity verification data](https://noxtica.com/docs/identity-verification-data/), [Requests and deletion](https://noxtica.com/docs/compliance/requests-and-deletion/) and the [Privacy Policy](https://noxtica.com/privacy/).

**Are business and merchant verification available?** KYB and KYM are in development. Availability depends on your organisation; ask your account team. See [Business and merchant verification](https://noxtica.com/docs/identity-verification-business/).

## Prerequisites

- A server key with the identity permission, and access to the Backoffice KYC pages. Reading cases needs a user who can open KYC Verifications. Recording a decision needs the administrator role and fresh step-up verification (MFA).
- The `sessionId` and, when you have it, the `requestId` from the response or the error body.
- An endpoint registered under Backoffice → Integrations & API → Webhooks, if you use events.

## Steps

Triage in five steps.

### 1. Read the session status

```http
GET https://collect.noxtica.com/v1/kyc/sessions/{sessionId}
Authorization: Bearer sk_prod_your_server_key
```

A session you created always returns `200`, including an expired one. A `404` means the id is unknown, belongs to another organisation, or the module is not provisioned.

### 2. Match the status to an action

| `status` | What it means | What to do |
| -------- | ------------- | ---------- |
| `pending` | Created. The customer has not opened the link. | Wait. The link expires at `expiresAt`. |
| `opened` | The customer is working through the steps. | Wait. The session expires within 30 minutes of the customer opening the link. |
| `verifying` | The customer submitted and processing is running. | Wait and read again. If it stays longer than you expect, go to step 5. |
| `review_pending` | A decision is needed in your Backoffice. | Open KYC Review Queue and record a decision. |
| `completed` | A decision approved the session. | Continue your journey. |
| `unverified` | Processing finished with a negative outcome. | Have a person review before you act on it. |
| `error` | Processing could not finish. | Create a new session. If it repeats, go to step 5. |
| `expired` | The link or the capture window lapsed. | Create a new session. |
| `cancelled_by_user` | The customer cancelled. | Create a new session if you still need one. |

### 3. Open the case in Backoffice

Open Backoffice → Identity Verification → KYC Verifications and find the case by the `verificationId` from the status read. The case shows the checks, the decision and the timeline. For session and verification events, Backoffice → Identity Verification → KYC → KYC Processes → "View" lists the webhook deliveries for that process.

### 4. Check delivery

If you expected an event, confirm that the endpoint is enabled and subscribed to it under Integrations & API → Webhooks, that your receiver answers `2xx` within the wait per attempt (5 seconds by default), and that the signature check uses the raw body and the current secret. Read the status instead of waiting for an event that does not apply: neither `review_pending` nor `expired` sends one.

### 5. Collect the details and contact support

Quote the `requestId` from the response or error body, the `sessionId` and the time. Do not send the one-shot link, the server key or the signing secret.

## Verify it works

- Creating a session returns `200` with `sessionId`, `url`, `expiresAt` and `requestId`.
- The status read returns the status you expect, and a Backoffice case exists for a submitted session.
- Your receiver verifies each signature, drops repeated `X-Noxtica-Delivery` values and reads the status before it acts.
- Backoffice → Identity Verification → KYC → KYC Processes shows `delivered` for the events your endpoint acknowledged.

## Troubleshooting

### Creating sessions

| Symptom | Cause | Fix |
| ------- | ----- | --- |
| `404` with `V1 endpoint not found` | The module is not provisioned for your organisation, or the path is wrong. | Check the path. If it is right, ask your account team. Do not retry in a loop. |
| `401` with `invalid_api_key` | The key is missing, malformed, unknown or revoked. | Check the `Authorization` header and that the key is a current `sk_prod_` key. |
| `403` with `API key does not have write:identity scope` | The key lacks the identity permission. | Create a key with "Verify identity documents (KYC)" ticked. |
| `403` with `kyc_legal_basis_receipt_required` | Your organisation has not recorded the legal basis for hosted identity verification. | An authorised person records it in Backoffice → Identity Verification → KYC Invitations → Settings. |
| `400` with `invalid_request` or `invalid_hosted_options` | Malformed JSON, a missing or over-long `subjectRef`, an `expiresInSeconds` outside 300 to 604800, an `Idempotency-Key` outside 8 to 128 characters, or a `hostedOptions` object that is not complete. | Fix the request, and send the complete `hostedOptions` object or leave it out. An unknown field is ignored without an error, so check the spelling of each name. |
| `400` with `return_url_not_allowed` | `returnUrl` is not `https`, or its host is not approved. | Add the host in the hosted page settings, or leave `returnUrl` out. |
| A retry returned `"replayed": true` and no `url` | The `Idempotency-Key` matched an existing session. The link is shown once, in the initial response. | Create a new session with a new key and let the old one expire. |
| `429` with `Rate limit exceeded` | Too many requests. | Back off and honour `retryAfter` or `Retry-After`. Bounds can change. |
| `503` with `hosted_verify_not_configured` | The hosted service is not set up for this environment. | Ask your account team. |

### What your customer sees

| Symptom | Cause | Fix |
| ------- | ----- | --- |
| "Verification isn't ready yet" | Your hosted verification page is not fully set up. | Complete the settings and check the readiness checklist in the Backoffice KYC pages. |
| "This link has expired" | The link or the 30-minute capture window ran out. | Create a new session and send the new link. |
| The page says the browser cannot run verification | The customer opened the link in an in-app browser. | Ask the customer to open the link in their regular browser. |
| The customer cancelled and the link no longer works | A cancel ends the link. The status is `cancelled_by_user`. | Create a new session. The reason comes in the `kyc.session.cancelled` event when that event is enabled for your organisation. |

### Results and events

| Symptom | Cause | Fix |
| ------- | ----- | --- |
| A session stays in `review_pending` | Nobody has recorded a decision. | Open Backoffice → Identity Verification → KYC Review Queue and select "Approve", "Override" or "Record escalation". |
| No event arrives for `review_pending` or `expired` | Neither state sends an event. | Read the session status. |
| An event arrives minutes after the decision | Review decisions are sent on a periodic schedule. | Wait a few minutes. The status read is current. |
| The signature check fails | The body was parsed before it was hashed, the secret was rotated, or `created_at` was used instead of the timestamp header. | Hash the raw body with the current secret and the `X-Noxtica-Timestamp` header. |
| The endpoint shows "No deliveries yet" while events work | Identity event outcomes are recorded under KYC Processes, not on the endpoint row. | Open KYC Processes → "View" → "Webhook deliveries". |
| `nvid` is missing from the status read or an event | Verification IDs are not enabled for your organisation, or the session has none. | See [Noxtica Verification ID](https://noxtica.com/docs/identity-verification-id/). |

## Related

- [Identity verification integration](https://noxtica.com/docs/identity-verification-integration/) — create a session and read the outcome.
- [Identity verification events and webhooks](https://noxtica.com/docs/identity-verification-webhooks/) — register an endpoint and verify signatures.
- [Noxtica Verification ID](https://noxtica.com/docs/identity-verification-id/) — format, validity and revocation.
- [Business and merchant verification](https://noxtica.com/docs/identity-verification-business/) — KYB and KYM.
- [Identity verification data](https://noxtica.com/docs/identity-verification-data/) — what is kept and who deletes it.
- [KYC Hosted Sessions](https://noxtica.com/docs/kyc-hosted-sessions/) — expiry and the `410` responses.
- [Errors](https://noxtica.com/docs/api/errors/) — the generic error reference.