Language: PII, Entities, Language Detection and Health

This content was generated with the assistance of AI and should be verified against the official documentation before being relied on in production.

See the section bibliography for the reference material consulted while preparing these pages.

This page targets Azure CLI 2.90.0 and the Language text REST API 2024-11-01 (GA), with PII on the newer GA version 2026-05-01 and previews 2025-11-15-preview and 2026-04-15-preview. The client libraries are azure-ai-textanalytics 5.4.0 (Python; 6.0.0b3 for the newer previews), Azure.AI.TextAnalytics 5.3.0 (.NET; Azure.AI.Language.Text 1.0.0-beta.4 for previews) and com.azure:azure-ai-textanalytics 5.5.15 (Java), checked on 2026-10-06. The GA client libraries default to older API versions, so features new in 2026-05-01 (synthetic replacement, for example) are shown over REST.

Azure Language in Foundry Tools has two groups of features. The core features on this page stay supported: PII detection, named entity recognition, language detection and Text Analytics for health. The legacy features (sentiment, key phrases, summarization, CLU, question answering) reach end of support on 2029-03-31 and are on Language: Sentiment, Summarization, CLU and Question Answering.

The Language REST quickstart on Learn still uses api-version 2022-05-01. The examples here use the current GA versions.

The analyze-text request shape

All sync text features use one endpoint, selected by kind:

TOKEN=$(az account get-access-token --resource https://cognitiveservices.azure.com --query accessToken -o tsv)

curl -s -X POST "https://$FOUNDRY.cognitiveservices.azure.com/language/:analyze-text?api-version=2024-11-01" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "kind": "EntityRecognition",
    "parameters": {"modelVersion": "latest"},
    "analysisInput": {"documents": [
      {"id": "1", "language": "en", "text": "Any new books by Kazuo Ishiguro since Klara and the Sun?"}
    ]}
  }'

Source: Language REST API — Analyze text

kind is one of EntityRecognition, PiiEntityRecognition, LanguageDetection, EntityLinking, KeyPhraseExtraction or SentimentAnalysis. Long-running features (health, custom NER, summarization, document PII) use POST /language/analyze-text/jobs and return 202 with an Operation-Location to poll.

PII detection and redaction

PII detection finds personal data (names, emails, phone numbers, addresses, credit cards, national IDs and dozens of country-specific types) and returns a redacted copy of the text.

New in the 2026-05-01 GA version:

  • Redaction policies: entityMask (replace with [PERSON]), characterMask (replace with *), noMask, or syntheticReplacement, which swaps each value for a realistic fake one (another name, another email) so the text still reads naturally for an LLM or for test data.

  • Confidence threshold: a minimum score per category, to trade recall against false positives.

  • Excluded values: strings never treated as PII, for example your company name.

curl -s -X POST "https://$FOUNDRY.cognitiveservices.azure.com/language/:analyze-text?api-version=2026-05-01" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "kind": "PiiEntityRecognition",
    "parameters": {
      "redactionPolicies": [{"policyKind": "syntheticReplacement"}],
      "confidenceThreshold": {"default": 0.8},
      "excludedValues": ["Bookshelf"]
    },
    "analysisInput": {"documents": [
      {"id": "note-4512", "language": "en",
       "text": "Customer Jane Doe (jane.doe@example.com, +1 555 0100) says order 4512 never arrived at 12 Elm St."}
    ]}
  }' | jq -r '.results.documents[0].redactedText'

Source: Detect and redact PII in text

The same call with the GA client libraries (default entity-label redaction):

from azure.ai.textanalytics import TextAnalyticsClient
from azure.identity import DefaultAzureCredential

client = TextAnalyticsClient(
    endpoint="https://foundry-bookshelf.cognitiveservices.azure.com/",
    credential=DefaultAzureCredential(),
)
note = "Customer Jane Doe (jane.doe@example.com) says order 4512 never arrived."
result = client.recognize_pii_entities([note], language="en")[0]
print(result.redacted_text)
for entity in result.entities:
    print(entity.category, entity.confidence_score)

Source: PII quickstart (Python)

using Azure.AI.TextAnalytics;
using Azure.Identity;

var client = new TextAnalyticsClient(
    new Uri("https://foundry-bookshelf.cognitiveservices.azure.com/"), new DefaultAzureCredential());

PiiEntityCollection entities = client.RecognizePiiEntities(
    "Customer Jane Doe (jane.doe@example.com) says order 4512 never arrived.").Value;
Console.WriteLine(entities.RedactedText);

Source: PII quickstart (C#)

import com.azure.ai.textanalytics.TextAnalyticsClient;
import com.azure.ai.textanalytics.TextAnalyticsClientBuilder;
import com.azure.ai.textanalytics.models.PiiEntityCollection;
import com.azure.identity.DefaultAzureCredentialBuilder;

TextAnalyticsClient client = new TextAnalyticsClientBuilder()
    .endpoint("https://foundry-bookshelf.cognitiveservices.azure.com/")
    .credential(new DefaultAzureCredentialBuilder().build())
    .buildClient();

PiiEntityCollection entities = client.recognizePiiEntities(
    "Customer Jane Doe (jane.doe@example.com) says order 4512 never arrived.");
System.out.println(entities.getRedactedText());

Source: PII quickstart (Java)

Conversation and document PII

  • Conversation PII (/language/analyze-conversations/jobs) redacts chat transcripts and speech transcripts, including the audio timing so you can also bleep the recording.

  • Native document PII takes a PDF, DOCX or TXT file from Blob storage and writes a redacted copy of the document back, keeping its format.

A PII-redaction gateway in front of an LLM

Bookshelf’s support assistant never sends raw customer notes to a model. A small gateway redacts them first, and restores the originals in the answer only where needed.

flowchart LR user[Support agent] --> gw[Redaction gateway in orders-api] gw -->|PiiEntityRecognition, syntheticReplacement| lang[Language PII] lang --> gw gw -->|redacted note and question| llm[Foundry Model] llm --> gw gw -->|answer, optional re-identification| user gw -.->|redacted text only| logs[(Log Analytics)]

The design questions (what to redact, re-identification, logging) are covered on Sensitive Information and Hidden Context.

Named entity recognition

Prebuilt NER returns entities with a category and subcategory: Person, Location, Organization, DateTime, Quantity, Product, Event, Skill and others. Newer API versions add finer entity tags (for example Location.GPE), which help when one span fits several categories.

Custom NER extracts entities that the prebuilt model doesn’t know (for example BookTitle and Edition):

  1. create a custom NER project in the Foundry portal, connected to a Blob container with sample text files

  2. label entities in the files (or import labels)

  3. train, review precision, recall and F1 per entity, and deploy

  4. call analyze-text/jobs with kind: CustomEntityRecognition, the project name and the deployment name

Source: Custom NER overview

Language detection

Language detection returns the language and script of a text, with a confidence score, for 139 languages and script variants. It is the replacement for Translator v3.0 detect, which is not part of Translator 2026-06-06.

for doc in client.detect_language(["Hola, ¿tienen libros de Isabel Allende?", "Bonjour"]):
    print(doc.primary_language.iso6391_name, doc.primary_language.confidence_score)

Source: Language detection quickstart

Text Analytics for health

Text Analytics for health extracts medical entities (conditions, medications, dosages, procedures), links them to UMLS concepts, finds relations (a dosage of a medication) and assertions (negated, conditional, hypothetical, about someone else). It can return a FHIR R4 bundle. It is asynchronous:

poller = client.begin_analyze_healthcare_entities(
    ["Patient denies chest pain. Started metformin 500 mg twice daily."]
)
for doc in poller.result():
    for entity in doc.entities:
        print(entity.category, entity.text, entity.assertion)

Source: Text Analytics for health overview

Limits

  • Sync requests: 5,120 characters per document. Up to 5 documents per request for most features (25 for some, 1,000 for language detection).

  • Async jobs: up to 125,000 characters per job across documents.

  • Rate: up to 1,000 requests per minute on S tiers.

Source: Language data limits

Provisioning

In the Azure portal

  1. Use the Foundry resource foundry-bookshelf.

  2. In the Foundry portal (https://ai.azure.com), open Playgrounds → Language playground to try PII, NER and language detection.

  3. Custom NER projects are created under Fine-tuning → AI Service fine-tuning. Language Studio still works until it retires on 2027-03-20.

  4. Assign Cognitive Services Language Reader (or Cognitive Services User) to the calling identity.

With the Azure CLI

az role assignment create \
  --assignee "$(az identity show --name id-orders-api --resource-group "$RG" --query principalId -o tsv)" \
  --role "Cognitive Services Language Reader" \
  --scope "$(az cognitiveservices account show --name "$FOUNDRY" --resource-group "$RG" --query id -o tsv)"

Source: Language role-based access control

Use cases

Scenario Feature Why this feature Example input → output

Bookshelf: redact customer data from orders-api support notes

PII with syntheticReplacement

Notes go to an LLM and to logs; names and emails must not.

"Jane Doe, jane.doe@example.com" → "Maria Lopez, m.lopez@example.net"

Bookshelf: extract author and title entities from free-text search

Prebuilt NER plus custom NER (BookTitle)

Turn "new Ishiguro after Klara" into filters.

Query → Person: Kazuo Ishiguro, BookTitle: Klara and the Sun

Redact PII before an LLM call

PII entity masking

Data minimization; compliance.

Chat message → [PERSON] called about [PHONENUMBER]

GDPR data-subject requests

Document PII

Find every document that mentions a person.

Archive of DOCX files → list of matches and redacted copies

Contract parties and dates

NER

Fast structured index of contracts.

Contract text → parties, effective date, amounts

Clinical-notes structuring

Text Analytics for health with FHIR

Assertions and UMLS links built in.

Discharge note → FHIR bundle

Routing by detected language

Language detection

Pick the right queue or translation target.

Ticket text → pt → Portuguese support queue

When not to use it

  • For open-ended extraction where the fields change often, a Foundry Model with structured outputs, or Content Understanding, may be faster to adapt than custom NER.

  • For sentiment, summaries and intents, see the legacy features page, where Microsoft recommends Foundry Models.

  • See Choosing a Foundry Tool (or a Foundry Model) for the general trade-off.

Related pages

References