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)). 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:

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.
• 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.

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.

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.

curl -sS "https://collect.noxtica.com/v1/kyc/verifications/<verification-id>/identity" \
  -H "Authorization: Bearer $NOXTICA_SERVER_KEY"

{
  "ok": true,
  "verificationId": "<verification-id>",
  "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": "<request-id>"
}

The values above are invented. Every response carries requestId: quote it when you contact support.

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:

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.

curl -sS "https://collect.noxtica.com/v1/kyc/verifications/<verification-id>/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:

{ "error": "invalid_fields", "allowed": ["documentNumber", "personalNumber", "mrzLines"], "requestId": "<request-id>" }

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)

curl -sS "https://collect.noxtica.com/v1/kyb/entities/<entity-id>/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)

curl -sS "https://collect.noxtica.com/v1/kym/cases/<case-id>/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.
• 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

The shared error envelope and the rate-limit rules are described in Errors and Rate limits. Request and response fields are in the identity API reference.

Related

• Identity verification integration: create a hosted session and read its outcome.
• Self-hosted identity verification (direct API): where a verificationId comes from.
• Identity verification events and webhooks: events are notifications and carry no identity details.
• Business and merchant verification (KYB and KYM): where entity and case ids come from.
• Verification data: storage, access and deletion: how long verification data stays and how an administrator deletes it.
• Authentication: server keys and permissions.
• Identity API reference: the generated field-level reference.