Getting Started

Veramask API Specifications

Veramask is a high-performance, stateless middleware for the automated detection and anonymization of Personally Identifiable Information (PII) in text and JSON payloads. It enables developers and organizations to share or process sensitive data assets while aligning with GDPR and CCPA expectations with configurable masking strategies and optional deterministic output for repeatable integrations.

Authentication

All API requests must include your API key in the x-api-key header:

x-api-key: YOUR_API_KEY

Requests without a valid API key will receive a 401 Unauthorized response. You can find your API key on the Subscription page.

Quick Start: anonymizeText (Minimal Request)

Use this endpoint when you only want to send raw text and rely on default settings.

Request

POST /v1/anonymizeText

{
    "data": "Alice Smith can be reached at alice@example.com or +1 555 123 9999"
}

Example response

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

Note: Exact anonymized values can vary when consistency_salt is not provided.

Supported locale(s)

• en_US only

If an unsupported locale is provided, validation fails.

Common Request Models

Both anonymization endpoints share the same top-level structure:

• settings (optional object)
• overrides (optional object)
• data (required, type depends on endpoint)

settings object

All fields are optional (defaults apply):

overrides object

• Type: object/map where each key is an entity type (for example PERSON, EMAIL_ADDRESS, PHONE_NUMBER).
• Value: one strategy object per entity key.
• If omitted for an entity, the API tries default strategy mapping from StrategiesService.

Supported override strategies:

{
  "data": "Alice Smith can be reached at asmith@mygoogle.com",
  "overrides": {
    "EMAIL_ADDRESS": {
      "type": "mask",
      "masking_char": "*",
      "chars_to_mask": 5,
      "from_end": false
    }
  }
}

{
  "masked_data": "Jane Doe can be reached at *****h@mygoogle.com"
}

{
  "data": "Alice Smith can be reached at asmith@mygoogle.com",
  "overrides": {
    "EMAIL_ADDRESS": {
      "type": "redact"
    }
  }
}

{
  "masked_data": "Jane Doe can be reached at "
}

{
  "data": "Alice Smith can be reached at asmith@mygoogle.com",
  "overrides": {
    "EMAIL_ADDRESS": {
      "type": "replace",
      "new_value": "dummy@example.com"
    }
  }
}

{
  "masked_data": "Jane Doe can be reached at dummy@example.com"
}

{
  "data": "Alice Smith can be reached at asmith@mygoogle.com",
  "overrides": {
    "EMAIL_ADDRESS": {
      "type": "hash"
    }
  }
}

{
  "masked_data": "8f223fc..."
}

{
  "data": "Alice Smith can be reached at asmith@mygoogle.com",
  "overrides": {
    "EMAIL_ADDRESS": {
      "type": "substitute",
      "attribute": "state"
    }
  }
}

{
  "masked_data": "Jane Doe can be reached at Deanbury"
}

Endpoints

1) POST /v1/anonymizeText

Anonymizes sensitive entities in free text.

Request body

{
    "data": "Alice Smith can be reached at asmith@mygoogle.com",
    "settings": {
        "locale": "en_US",
        "confidence_threshold": 0.8,
        "consistency_salt": "0123456789abcdef"
    },
    "overrides": {
        "PERSON": {
            "type": "substitute",
            "attribute": "name"
        },
        "EMAIL_ADDRESS": {
            "type": "mask",
            "masking_char": "*",
            "chars_to_mask": 10,
            "from_end": false
        }
    }
}

Request parameters

1. Top-level

• data (string, required): raw text to anonymize.
• settings (object, optional): global anonymization settings.
• overrides (object, optional): per-entity operator overrides.

2. Validation constraints

• settings.locale must be en_US.
• settings.confidence_threshold must be between 0.0 and 1.0.
• settings.consistency_salt must be at least 16 bytes when non-empty.

Success response

• 200 OK

{
  "masked_data": "Christopher Taylor can be reached at **********oogle.com"
}

Field notes:

• masked_data: anonymized output text.

Error responses

• 400 Bad Request: if the request is malformed or fails validation (for example: invalid JSON structure, missing required fields).
• 403 Subscription Limit: if the request contains parameters not allowed by the subscription plan.
• 413 Payload Too Large: if request body exceeds configured limit.
• 422 Unprocessable Entity: request model validation errors.
• 500 Internal Server Error: unexpected runtime failures.

2) POST /v1/anonymizeJSON

Anonymizes all string values recursively in a JSON object while preserving structure.

Request body

{
    "data": {
        "customer": {
            "name": "Alice Smith",
            "email": "alice@example.com"
        },
        "notes": [
            "Home address: 7211 Jewel Lake Rd, Anchorage, Alaska"
        ]
    },
    "settings": {
        "locale": "en_US",
        "confidence_threshold": 0.7,
        "consistency_salt": "0123456789abcdef"
    },
    "overrides": {
        "EMAIL_ADDRESS": {
            "type": "substitute",
            "attribute": "email"
        }
    }
}

Request parameters

1. Top-level

• data (object, required): JSON object to process.
• settings (object, optional): global anonymization settings.
• overrides (object, optional): per-entity operator overrides.

2. data type rules

• Must be a JSON object (dictionary/map).
• Values must be JSON-compatible recursively:
  • Allowed: strings, numbers, booleans, null, arrays, objects.
  • Disallowed: non-JSON Python-native values.

3. Processing behavior

• Strings are analyzed/anonymized.
• Arrays are traversed item by item.
• Objects are traversed key by key.
• Non-string primitives are returned unchanged.

Success response

• 200 OK

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

Field notes:

• masked_data: anonymized JSON with original structure preserved.

Error responses

• 413 Payload Too Large: if request body exceeds configured limit.
• 422 Unprocessable Entity: request model validation errors.
• 500 Internal Server Error: unexpected runtime failures.

Default Entity Strategy Mapping (When Overrides Are Missing)

When no override is provided for a detected entity type, the service applies defaults based on internal mapping:

Notes for Integrators

• Deterministic output depends on consistency_salt; without it, substitutions may vary by request.
• Language passed to analyzer is derived from locale prefix (en_US -> en).
• Unhandled exceptions are logged server-side and returned as generic 500 responses with a request ID.

Global Request Constraints

Request body size limit

For POST, PUT, and PATCH requests, a middleware enforces a maximum payload size, which depends on the subscribed plan.

• Error response on overflow:

• HTTP status: 413 Payload Too Large