--- title: "Read identity details with the API" description: "Turn on identity details access in Backoffice, create a server key with the read permission, and read the extracted details of a verification, business entity or merchant case from your server." canonical_url: "https://noxtica.com/docs/identity-verification-identity-details/" markdown_url: "https://noxtica.com/docs/identity-verification-identity-details/index.md" last_updated: 2026-10-28 published: 2026-10-28 section: "identity-verification" section_title: "Identity Verification" site: "Noxtica" language: "en" source: markdown --- # Read identity details with the API This guide is for a backend engineer who needs the details Noxtica read from a customer's identity document, or the registered details of a business or merchant case, inside your own system. Three read-only calls return them: one for an identity verification (KYC), one for a business entity (KYB) and one for a merchant case (KYM). A tenant administrator decides whether your organisation uses them, and every read is recorded. The status read of a hosted session (`GET /v1/kyc/sessions/{sessionId}`) returns the outcome of a verification and never a name, a date of birth or a document number. The calls on this page return those values. ## What it is Availability: Controlled availability. Identity verification is provisioned per tenant by your account team, and identity details access is a separate setting that a tenant administrator turns on in Backoffice when it is available for your organisation. Until it is on, every call below is refused. The business and merchant calls also need the business or merchant verification module, which depends on your organisation (see [Business and merchant verification (KYB and KYM)](https://noxtica.com/docs/identity-verification-business/)). Ask your account team what applies to you. The three calls, all `GET`, all under `https://collect.noxtica.com`, all authenticated with a server key as a bearer token: | Call | Returns | | ---- | ------- | | `/v1/kyc/verifications/{verificationId}/identity` | The document type, number, expiry and issuing country, the holder's names, date of birth, sex and nationality, the machine-readable-zone check results, the verification status and a summary of the checks. | | `/v1/kyb/entities/{entityId}/identity` | The registered business: legal name, registration number, country, kind and status, its beneficial owners and representatives with their ownership share, and its documents. | | `/v1/kym/cases/{caseId}/identity` | The merchant: name, registration number, country and status, its beneficial owners and directors with their latest screening status, and its documents. | How the calls behave, in short: - **Opt-in, in two steps.** The key needs the `read:identity_details` permission, and a tenant administrator must have enabled identity details access for the organisation. A key with the permission is refused until then. - **Sensitive values are withheld by default.** The full document number comes back masked, and the personal number and the raw machine-readable-zone lines are left out. You receive them only when a request names them in `?fields=`. - **Nothing is hidden silently.** Every masked, left-out or unavailable item is listed in `redactions`, so you can tell "withheld on purpose" from "not there". - **Every read is recorded.** Noxtica records the key, the time and the names of the fields returned, never their values. - **Responses are never cached.** Every response carries `Cache-Control: no-store, private`. Do not cache or log the body. - **Identity details are never sent in webhooks.** Events tell you that something happened. You read the details with these calls. The calls return no images, no face data and no scores. The checks are summarised as verdicts. ## Prerequisites - **Identity verification provisioned for your organisation**, and at least one finished verification whose document was read. See [Identity verification integration](https://noxtica.com/docs/identity-verification-integration/). - **A tenant administrator** to turn on identity details access. Recording it asks for fresh step-up verification (MFA), and a person who may not administer the organisation cannot do it. - **A lawful basis, decided by your organisation.** The setting records an attestation that your organisation, as the controller of its customers' data, has a lawful basis under Article 6 and a condition under Article 9 of the GDPR for receiving these details, and that your customers were informed. Your own counsel owns that decision. This page is not legal advice. - **A new server key that carries the permission.** A key keeps the permissions it was created with, so an existing key never gains `read:identity_details`. Create a new key for this job and give it to as few services as possible. - **A secret store for the key**, and a place for the details that follows your own retention rules. - **For a business or merchant call:** the module for that type enabled for your organisation, and the `entityId` or `caseId` from Backoffice or from the `kyb.entity.*` and `kym.*` events described in [Identity verification events and webhooks](https://noxtica.com/docs/identity-verification-webhooks/). ## Steps ### 1. Turn on identity details access A tenant administrator opens Backoffice → Identity Verification → KYC Invitations → Settings and finds the card **Identity details API**. 1. Read the attestation text shown on the card. It is the text your organisation records, in the version shown. 2. Choose the Article 6(1) lawful basis and the Article 9(2) condition, tick the acknowledgement, type the confirmation text the card asks for, and select **Enable identity details API**. Complete the step-up verification when it asks. 3. The card now shows **Enabled**, since when, and by whom. If the card reads "Not available on this platform yet", identity details access is not open for your organisation. Ask your account team. To stop all reads at once, an administrator selects **Disable** on the same card and gives a reason. Reads stop immediately: the next call answers `403 identity_read_not_enabled`. No key needs to be rotated. ### 2. Create a key with the permission In Backoffice open API & SDK → Server API Keys, create a new key and tick the permission `read:identity_details` ("Read identity details of KYC verifications, KYB entities and KYM cases"). The secret is shown once. Keep it in your server secret store, never in a browser or an app. The key starts with `sk_prod_`. The permission is separate from the one that creates verifications (`write:identity`): a key that starts verifications cannot read their details, and the reverse. ```bash export NOXTICA_SERVER_KEY='sk_prod_…' ``` ### 3. Read the details of a verification (KYC) `verificationId` is the id that `POST /v1/kyc/verify` returned. The id of a hosted session is accepted too, and so is the evidence group id of a verification made from your own capture screens: all of them resolve to the same verification. ```bash curl -sS "https://collect.noxtica.com/v1/kyc/verifications//identity" \ -H "Authorization: Bearer $NOXTICA_SERVER_KEY" ``` ```json { "ok": true, "verificationId": "", "sourceEvidenceGroupId": null, "extractedAt": "2026-10-28T14:22:11.000Z", "verification": { "status": "verified", "level": "verified" }, "document": { "type": "national_id", "side": "front", "issuingCountry": "GB", "number": "••••4821", "expiryDate": "2031-05-17", "idType": "national_id" }, "person": { "fullName": "ADA EXAMPLE", "surname": "EXAMPLE", "givenNames": "ADA", "dateOfBirth": "1990-01-31", "sex": "F", "nationality": "GB", "personalNumber": null }, "address": null, "mrz": { "format": "TD1", "fieldChecks": [ { "field": "document_number", "checkDigitValid": true }, { "field": "birth_date", "checkDigitValid": true } ] }, "checks": { "documentAuthenticity": "pass", "faceMatch": "pass", "liveness": "pass", "selfie": "pass", "crossValidation": { "overall": "match", "fields": [{ "field": "dateOfBirth", "agreement": "match" }] } }, "redactions": [ { "field": "document.number", "reason": "masked_by_default", "include": "documentNumber" }, { "field": "person.personalNumber", "reason": "omitted_by_default", "include": "personalNumber" }, { "field": "mrz.lines", "reason": "omitted_by_default", "include": "mrzLines" }, { "field": "address", "reason": "not_extracted" } ], "requestId": "" } ``` The values above are invented. Every response carries `requestId`: quote it when you contact support. | Field | Meaning | | ----- | ------- | | `verificationId` | The verification the details belong to. | | `sourceEvidenceGroupId` | The evidence group id the verification was made from, or `null` when it did not come from your own capture screens. | | `extractedAt` | When the details were read from the document and stored (UTC). | | `verification.status` | `verified`, `unverified`, `failed`, `error` or `pending`. Treat the details as input for your own decision, not as the decision. | | `verification.level` | `verified`, `partial`, `unverified`, `inconclusive`, or `null` when none was assigned. | | `document` | `type` (`national_id`, `driving_license`, `passport`, `residence_permit` or `unknown`), `side`, `issuingCountry`, `number` (masked unless you ask), `expiryDate` and `idType`. | | `person` | `fullName`, `surname`, `givenNames`, `dateOfBirth`, `sex` (usually `M`, `F` or `X`), `nationality` and `personalNumber` (`null` unless you ask). | | `address` | Always `null` today: Noxtica does not read an address from identity documents. The key is there so a later release can fill it without changing the shape. | | `mrz` | `format` (`TD1`, `TD2` or `TD3`) and the check-digit result of each field. `null` when the document has no machine-readable zone. `lines` appears only when you ask for `mrzLines`. | | `checks` | A verdict per check family: `pass`, `review`, `fail`, `skipped`, `pending`, or `null` when the verification has no such check. `crossValidation` says whether the values read from different parts of the document agree, field by field, without returning the values compared. | | `redactions` | Every masked, left-out or unavailable item: `field`, `reason` and, when a `fields` value returns the full item, `include`. | A value that could not be read is `null`, and a `surname`, `givenNames` or `personalNumber` that older stored details do not carry is `null` with a `not_extracted` entry in `redactions`. The `reason` of a redaction is one of: | Reason | Meaning | | ------ | ------- | | `masked_by_default` | The value is returned masked: only its last characters. | | `omitted_by_default` | The value is left out. | | `not_extracted` | Noxtica does not read this item, or did not read it for this record. | | `not_available` | The item is not available for this record. | ### 4. Choose what you receive with `?fields=` Add `?fields=` with a comma-separated list to receive withheld values. The accepted values for the verification call are `documentNumber`, `personalNumber` and `mrzLines`. ```bash curl -sS "https://collect.noxtica.com/v1/kyc/verifications//identity?fields=documentNumber,personalNumber" \ -H "Authorization: Bearer $NOXTICA_SERVER_KEY" ``` With `documentNumber` the full number replaces the masked one in `document.number`, with `personalNumber` the value appears in `person.personalNumber`, and with `mrzLines` the raw lines appear in `mrz.lines`. Each item you ask for leaves `redactions`. Ask only for what the next step needs: the request is recorded with the names you asked for. An unknown value answers `400` with `error: "invalid_fields"` and the list of accepted values in `allowed`: ```json { "error": "invalid_fields", "allowed": ["documentNumber", "personalNumber", "mrzLines"], "requestId": "" } ``` Names, date of birth, expiry date, nationality, sex, issuing country, ID type and document type are always returned in full. ### 5. Read a business entity (KYB) ```bash curl -sS "https://collect.noxtica.com/v1/kyb/entities//identity" \ -H "Authorization: Bearer $NOXTICA_SERVER_KEY" ``` The response carries `entity` (`legalName`, `registrationNumber`, `countryOfIncorporation`, `entityKind`, `status`, `createdAt`, `updatedAt`), `parties` (each with `id`, `fullName`, `role`, `ownershipPercent` and `interestType`), `documents` (each with `id`, `kind`, `state`, `extractedAt` and `extractedClass`), `redactions` and `requestId`. `ownershipPercent` runs from 0 to 100 and is `null` when no share is recorded. `?fields=extractions` adds, to each document, `extractions`: the values read from the document as `{ "name", "value" }` pairs. Without it they are listed in `redactions`. Nothing else is accepted: any other value answers `400 invalid_fields`. A business has no date of birth, nationality or registered address in this response, because Noxtica does not hold them. `redactions` lists them as `not_extracted`. ### 6. Read a merchant case (KYM) ```bash curl -sS "https://collect.noxtica.com/v1/kym/cases//identity" \ -H "Authorization: Bearer $NOXTICA_SERVER_KEY" ``` The response carries `merchant` (`merchantName`, `registrationNumber`, `country`, `status`, `createdAt`, `updatedAt`), `parties` (each with `id`, `fullName`, `role`, `lastCheckStatus` and `lastCheckAt`), `documents` (each with `id`, `kind` and `state`), `redactions` and `requestId`. This call accepts no `fields` values. Free-text notes, transactions and screening reasons are not returned. ### 7. Handle the data - **Read when you need it.** Noxtica does not delete verification details or evidence automatically, and it sets no retention date. They stay available until an administrator of your organisation deletes them. You do not need to copy details into your own system to keep them. - **If you do store a copy, it is your data.** Apply your own retention and deletion rules, and delete your copy when your organisation deletes the verification. See [Verification data: storage, access and deletion](https://noxtica.com/docs/identity-verification-data/). - **Never cache, never log the body.** The response is personal data. Log the `requestId`, the status code and the id you asked for, not the body. Do not put values in URLs, error trackers or analytics. - **Do not wait for an event to carry the details.** No webhook event contains identity details. After `kyc.session.completed` or `kyc.verification.completed`, call the read once the verification has finished. - **Respect the limit.** Calls are limited for each key. A call over the limit answers `429` with a `Retry-After` header: wait that many seconds and retry. - **A deleted record answers `410`.** Stop reading it and remove your copy according to your own rules. ## Verify it works - Before you enable anything, a call with the new key answers `403` with `identity_read_not_enabled`. That proves the key is valid and the gate is closed. - After an administrator enables access, a call for a finished verification answers `200` with `"ok": true`, a `redactions` list and a `requestId`, and `document.number` is masked. - A call with `?fields=documentNumber` returns the full number and drops `document.number` from `redactions`. - A call with a key that lacks the permission answers `403` with `API key does not have read:identity_details scope`. - After an administrator selects **Disable**, the next call answers `403 identity_read_not_enabled` again. - The response headers include `Cache-Control: no-store, private`. ## Troubleshooting | Symptom | Cause | Fix | | ------- | ----- | --- | | `404` with `V1 endpoint not found` | The id is malformed, unknown or belongs to another organisation, or the feature or the business or merchant module is not available for your organisation. The answer is the same in every case, on purpose. | Check the id and the path, then ask your account team. Do not retry in a loop. | | `401 invalid_api_key` | The key is missing, revoked or malformed. | Check the `Authorization: Bearer` header and the key. | | `403` with `API key does not have read:identity_details scope` | The key was created without the permission. | Create a new key with `read:identity_details` ticked. An existing key cannot be changed. | | `403 identity_read_not_enabled` | No administrator has enabled identity details access, or it was disabled. | A tenant administrator enables it in Backoffice → Identity Verification → KYC Invitations → Settings. | | `400 invalid_fields` | A value in `?fields=` is not accepted for this call. | Use only the values listed in `allowed`. | | `409 identity_not_available` with `reason` `not_completed` | The verification has not finished yet. | Wait for the outcome, then read again. | | `409 identity_not_available` with `reason` `not_extracted` | Nothing was read or stored for this verification: stored evidence is not enabled for your organisation, or the verification predates reading. | Ask your account team. Retrying does not change it. | | `410` with `verification_deleted`, `entity_deleted` or `case_deleted` | An administrator of your organisation deleted the record. | Stop reading it and remove your copy according to your own rules. | | `429 Rate limit exceeded` | Too many calls for this key. | Wait for the `Retry-After` seconds, then retry. | | `503` with `identity_audit_unavailable` or `identity_unavailable` | A temporary fault. Nothing was returned. | Retry after a short delay, and quote the `requestId` if it persists. | The shared error envelope and the rate-limit rules are described in [Errors](https://noxtica.com/docs/api/errors/) and [Rate limits](https://noxtica.com/docs/api/rate-limits/). Request and response fields are in the [identity API reference](https://noxtica.com/docs/api/reference/kyc/). ## Related - [Identity verification integration](https://noxtica.com/docs/identity-verification-integration/): create a hosted session and read its outcome. - [Self-hosted identity verification (direct API)](https://noxtica.com/docs/identity-verification-self-hosted/): where a `verificationId` comes from. - [Identity verification events and webhooks](https://noxtica.com/docs/identity-verification-webhooks/): events are notifications and carry no identity details. - [Business and merchant verification (KYB and KYM)](https://noxtica.com/docs/identity-verification-business/): where entity and case ids come from. - [Verification data: storage, access and deletion](https://noxtica.com/docs/identity-verification-data/): how long verification data stays and how an administrator deletes it. - [Authentication](https://noxtica.com/docs/api/authentication/): server keys and permissions. - [Identity API reference](https://noxtica.com/docs/api/reference/kyc/): the generated field-level reference.