How to Anonymize PII in Text with an API

Michele — Thu, 09 Jul 2026 21:48:22 +0000

What Is Data Masking?

Data masking is a technique that replaces sensitive information with realistic but fictitious data, preserving the format and structure of the original while removing its identifiable meaning. The goal is to keep data usable for development, testing, analytics, or sharing — without exposing real personally identifiable information (PII).

Common masking techniques include:

Substitution — Replace a real value with a plausible fake (e.g., Alice Smith → Jane Doe).
Masking (partial obscuring) — Show only a portion of the value (e.g., 4111-1111-1111-1234 → ****-****-****-1234).
Redaction — Remove the value entirely.
Hashing — Replace with a cryptographic hash. Irreversible, but deterministic when salted.

Data masking is widely used in non-production environments, analytics pipelines, data marketplaces, and any scenario where real PII is not needed but structural fidelity is.

What Is Dynamic Data Masking?

Static data masking (SDM) applies transformations to data at rest — you clone a production database, mask it, and ship the masked copy to a lower environment. The masking happens once, and the result is a permanent dataset.

Dynamic data masking (DDM) applies transformations on the fly, at query or API time, based on who is asking. The original data stays untouched; the masking rules are applied in the response layer. This means:

Different roles see different levels of detail (e.g., support agents see the last 4 digits of a credit card; auditors see the full number).
No masked copies to maintain — one source of truth, many views.
Masking policies are centralized and enforceable without application changes.

Veramask implements a DDM-style model over an API: you send a request with payload and settings, and receive back the transformed result in real time. No data is persisted on the server — each call is independent and stateless.

Anonymizing PII with the Veramask API

Veramask exposes two endpoints for dynamic PII masking:

Endpoint	Input	Use Case
`POST /v1/anonymizeText`	Raw string	Free-text fields, log lines, chat messages, documents
`POST /v1/anonymizeJSON`	JSON object	Structured payloads, API responses, database records

Both accept a common set of controls: settings for global behavior (locale, confidence threshold, consistency salt) and overrides for per-entity-type strategy selection.

Step 1: Get an API Key

Sign up through the Veramask Developer Portal to obtain an API key. You will include this key in the x-api-key header of every request.

Step 2: Make Your First Anonymization Request

The simplest call sends raw text and relies on default strategies for each detected entity type.

curl -X POST https://veramask-gateway-3irxmt23.uc.gateway.dev/v1/anonymizeText \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "data": "Alice Smith can be reached at alice@example.com or +1 555 123 9999"
  }'

Response:

{
  "masked_data": "Jane Doe can be reached at fake_user@example.com or +1 555 482 7714"
}

Notice that PERSON, EMAIL_ADDRESS, and PHONE_NUMBER were all detected and replaced with synthetic substitutes — the names are swapped, the email faked, and the phone number replaced — while the sentence structure is preserved.

Step 3: Choose Your Anonymization Strategy Per Entity Type

You can override the default behavior for any entity type using the overrides object. Five strategies are available:

Strategy	Behavior
`mask`	Partially obscures the value (configurable character, count, direction)
`redact`	Removes the value entirely
`replace`	Substitutes with a fixed caller-provided value
`hash`	Replaces with a SHA-256 digest (salted when `consistency_salt` is set)
`substitute`	Replaces with realistic synthetic data via the Faker library

Example — Mask email addresses, hash phone numbers, substitute person names:

curl -X POST https://veramask-gateway-3irxmt23.uc.gateway.dev/v1/anonymizeText \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "data": "Alice Smith can be reached at alice@example.com or +1 555 123 9999",
    "overrides": {
      "PERSON": { "type": "substitute", "attribute": "name" },
      "EMAIL_ADDRESS": {
        "type": "mask",
        "masking_char": "*",
        "chars_to_mask": 10,
        "from_end": false
      },
      "PHONE_NUMBER": { "type": "hash" }
    }
  }'

Response:

{
  "masked_data": "Christopher Taylor can be reached at **********@example.com or a1b2c3d4e5f6..."
}

Step 4: Enable Deterministic (Repeatable) Output

By default, Veramask produces different synthetic values on each call. If you need consistent anonymization — for example, to join datasets across time without leaking identity — provide a consistency_salt.

curl -X POST https://veramask-gateway-3irxmt23.uc.gateway.dev/v1/anonymizeText \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "data": "Alice Smith can be reached at alice@example.com",
    "settings": {
      "consistency_salt": "0123456789abcdef"
    }
  }'

The same input with the same salt always produces the same output. This is deterministic pseudonymization — the transformation is repeatable without maintaining a lookup table.

Step 5: Anonymize Structured JSON

For JSON payloads, use /v1/anonymizeJSON. Veramask traverses all string values recursively.

curl -X POST https://veramask-gateway-3irxmt23.uc.gateway.dev/v1/anonymizeJSON \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "data": {
      "customer": {
        "name": "Alice Smith",
        "email": "alice@example.com"
      },
      "notes": [
        "Home address: 7211 Jewel Lake Rd, Anchorage, Alaska"
      ]
    },
    "settings": {
      "confidence_threshold": 0.7
    },
    "overrides": {
      "EMAIL_ADDRESS": { "type": "substitute", "attribute": "email" }
    }
  }'

Response:

{
  "masked_data": {
    "customer": {
      "name": "Christopher Taylor",
      "email": "pespinoza@example.com"
    },
    "notes": [
      "Home address: 7211 Lake Brentland, Kathymouth, Rowehaven"
    ]
  }
}

The JSON structure is preserved exactly — keys, nesting, and non-string types are untouched. Only string values containing PII are transformed.

Step 6: Tune Detection Sensitivity

The confidence_threshold (range 0.0–1.0, default 0.4) controls how aggressively Veramask flags tokens as PII:

Lower values (e.g., 0.2) — more aggressive; catches borderline cases but may over-mask.
Higher values (e.g., 0.8) — conservative; only masks high-confidence detections, reducing false positives.

"settings": {
  "confidence_threshold": 0.8
}

End-to-End Workflow Summary

Client App                  Veramask Gateway              Anonymization Engine
    │                             │                              │
    │  POST /v1/anonymizeText     │                              │
    │  x-api-key: ...             │                              │
    │  { data, settings, ... }    │                              │
    │────────────────────────────>│                              │
    │                             │  1. Authenticate API key     │
    │                             │  2. Check subscription       │
    │                             │  3. Validate features        │
    │                             │  4. Attach GCP key           │
    │                             │                              │
    │                             │  POST /anonymizeText         │
    │                             │  { data, settings, ... }     │
    │                             │─────────────────────────────>│
    │                             │                              │
    │                             │    NER → strategy → mask     │
    │                             │                              │
    │                             │  { masked_data }             │
    │                             │<─────────────────────────────│
    │                             │                              │
    │                             │  5. Strip internal fields    │
    │  { masked_data }            │                              │
    │<────────────────────────────│                              │

Default Entity Strategies (No Overrides)

When you don't specify overrides, Veramask applies sensible defaults per entity type:

Entity Type	Default	Example Output
`CREDIT_CARD`	Mask (last 4)	`****1234`
`CRYPTO`	Hash	`e3b0c442...`
`DATE_TIME`	Jitter (±7 days)	Date shifted deterministically
`EMAIL_ADDRESS`	Substitute	`fake_user@example.com`
`IBAN_CODE`	Partial hash	`DE******9999`
`IP_ADDRESS`	Mask (last octet)	`192.168.1.0`
`MAC_ADDRESS`	Mask (last 3 octets)	`AD:F3:7A:00:00:00`
`PERSON`	Substitute	Synthetic name
`LOCATION`	Substitute	Synthetic state/region
`PHONE_NUMBER`	Substitute	Synthetic phone number
`URL`	Redact (query strings)	Keeps base domain

Error Handling

Status	Meaning
`400`	Malformed request or validation failure
`403`	Feature not in subscription plan
`413`	Payload exceeds size limit
`422`	Request model validation errors
`500`	Internal server error

Key Takeaways

Data masking obscures PII while preserving structure; dynamic data masking does this at request time with no persistent copy.
Veramask gives you an API-first DDM layer: send data, get it back anonymized, no storage involved.
Five strategies (mask, redact, replace, hash, substitute) give per-entity-type control.
A consistency_salt enables deterministic pseudonymization for referential integrity.
The /v1/anonymizeText endpoint handles free text; /v1/anonymizeJSON handles structured objects.
Zero retention means no long-term PII liability on the service side.

DEV Community: Michele

How to Anonymize PII in Text with an API

What Is Data Masking?

What Is Dynamic Data Masking?

Anonymizing PII with the Veramask API

Step 1: Get an API Key

Step 2: Make Your First Anonymization Request

Step 3: Choose Your Anonymization Strategy Per Entity Type

Step 4: Enable Deterministic (Repeatable) Output

Step 5: Anonymize Structured JSON

Step 6: Tune Detection Sensitivity

End-to-End Workflow Summary

Default Entity Strategies (No Overrides)

Error Handling

Key Takeaways