DEV Community

Michele
Michele

Posted on

How to Anonymize PII in Text with an API

#api #privacy #security #tutorial

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"
  }'
Enter fullscreen mode Exit fullscreen mode

Response:

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

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" }
    }
  }'
Enter fullscreen mode Exit fullscreen mode

Response:

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

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"
    }
  }'
Enter fullscreen mode Exit fullscreen mode

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" }
    }
  }'
Enter fullscreen mode Exit fullscreen mode

Response:

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

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
}
Enter fullscreen mode Exit fullscreen mode

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 }            │                              │
    │<────────────────────────────│                              │
Enter fullscreen mode Exit fullscreen mode

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.

Top comments (0)