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.
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.
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.
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.
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.
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, Requests and deletion and the Privacy Policy.
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.
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
sessionIdand, when you have it, therequestIdfrom 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
GET https://collect.noxtica.com/v1/kyc/sessions/{sessionId}
Authorization: Bearer sk_prod_your_server_keyA 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
200withsessionId,url,expiresAtandrequestId. - 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-Deliveryvalues and reads the status before it acts. - Backoffice → Identity Verification → KYC → KYC Processes shows
deliveredfor 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. |
Related
- Identity verification integration — create a session and read the outcome.
- Identity verification events and webhooks — register an endpoint and verify signatures.
- Noxtica Verification ID — format, validity and revocation.
- Business and merchant verification — KYB and KYM.
- Identity verification data — what is kept and who deletes it.
- KYC Hosted Sessions — expiry and the
410responses. - Errors — the generic error reference.