What to look for in a PII redaction API before you build on it

The basic contract is short. You send a string, the API finds the sensitive values in it, and you get back the same string with those values transformed, plus a list of what it found. Everything interesting is in the details: which values it finds, what it replaces them with, whether you can get the originals back, and what it keeps.

A concrete example from Maskflare's API. You send the text Contact ada@example.com for details to POST /v1/mask with a Redaction-purpose key. You get back the output Contact mf_mask_170b8521c1b944b3beb9ca02b328efbe for details, and a tokens list with one entry: the token id 170b8521c1b944b3beb9ca02b328efbe and the rule key email. The response names the rule that matched; it doesn't echo the email address back. Later, POST /v1/unmask with that token id returns ada@example.com, for the same key, for up to 30 days.

That shape is worth holding every vendor to. The output must be usable directly, for example sent to a language model or written to a log. The findings must be usable by code, for example to count what was masked per rule. And the original value must never appear anywhere it wasn't asked for, including error messages and the vendor's own logs.

A useful API returns the transformed content and structured findings that identify the data type, location and action without unnecessarily echoing the sensitive value. Stable error codes and versioned behavior matter because policy decisions become application dependencies: if a field name or an error code changes, the code that enforces your fail-closed policy breaks quietly.

Offsets are the detail most evaluations skip. If you need to highlight masked phrases in a user interface, or silence the matching seconds of a voice recording, you need to know exactly where each value sat in the input. Check whether offsets are given in Unicode code points or UTF-16 units, because an emoji or an accented name earlier in the text shifts one but not the other. Maskflare's Python SDK returns spans in code points and its TypeScript SDK in UTF-16 indices, matching how each language slices strings.

Consistency matters as much as accuracy. Within one request, the same value should get the same placeholder, so a model or a reviewer can still follow who did what. Across requests, you usually want the opposite for chat (tokens that don't link conversations) and the same thing for search (stable tokens so an indexed document and a later query still match). A good API lets you choose per call.

Redaction is one action among several, and a single API should offer the ones your workflows need. The right action depends on whether anyone downstream needs the original value, a recognizable shape of it, or only the fact that something was there.

Maskflare offers these as per-rule actions: mask, which replaces a value with a reversible token such as mf_mask_170b...; redact, which removes it for good; partial, which keeps the first or last few characters; hash, a keyed HMAC per organization that lets you join records without seeing values; format-preserving encryption (FF1), which keeps the format and is reversible with the key; alert, which counts the match and changes nothing; and block, which refuses the request.

A typical policy mixes them. Card numbers partially masked to the last four digits for a support reply. Email addresses masked so the model can address the customer and the value comes back in the answer. Passwords and API keys blocked outright, because no task needs them in a prompt. New rules start in alert mode for a week to measure how often they would fire before they change anything.

If the API offers reversible masking, someone stores the mapping from token to value. Ask where, for how long, encrypted with what, and who can read it back. In Maskflare's case the original values behind tokens are kept encrypted for 30 days so they can be restored, and then tokens expire: a restore call simply omits them.

Scope is the security question. Tokens resolve only for the API key that created them, so a token copied out of one organization means nothing to another. Inside your own application, that's not enough on its own: if many of your users share one key, restore only the tokens your code minted for the current request, or a user could paste someone else's token and read it back. Deterministic tokens can be scoped further by tenant, so the same value under two of your customers produces two different tokens that resolve only in their own scope.

Key purpose is the operational question. Maskflare's Redaction-purpose keys can call mask and unmask but are rejected on the AI-gateway forwarding routes, so a key leaked from a logging pipeline can't be used to spend your AI provider budget. Separate keys per environment (development, staging, production) keep test traffic and production tokens apart.

A single accuracy figure hides the failures that matter. Ask for, or measure, recall and precision per data type: email, phone, IBAN, card number, each national ID you care about, person names, API keys and secrets. A missed national identifier and an unnecessary masked date have very different consequences.

Understand the detection method, because it predicts the failure modes. Deterministic engines (patterns, checksums, context keywords and word lists) are predictable and fast, give the same answer every time, and are strong on structured identifiers that carry a check digit. Machine-learning models generalize better to unusual names and free text, but they're probabilistic, harder to explain, and need more compute. Maskflare combines both: a deterministic engine with 574 detectors in 53 packs, including 47 country packs and 232 credential and secret formats, and a local named-entity layer for names and free-text details that runs inside Maskflare.

Be precise about published numbers. On Maskflare's internal test corpus, overall recall is 0.996 and precision 1.000, and on a 228-case Swiss benchmark the engine with its named-entity layer found 100% of values with no false positives. Those are our own sets, not independent benchmarks, and the useful test is still your own representative data. Include the awkward cases: values split by zero-width or look-alike characters, base64 or hex-encoded text, JSON strings with escaped characters, names in the languages your customers write in.

Teams should know where requests are processed, whether content is retained, how diagnostic logging works, and whether customer data is used to improve models. Authentication, authorization, encryption, rate limits and tenant isolation belong in the API evaluation. For Maskflare: hosting is in the EU by default, with on-premises deployment available for enterprise; prompts and responses are never logged or stored, and records hold metadata and counts only. Maskflare's SOC 2 Type II and ISO 27001 audits are in progress, which some procurement teams will want to know early.

Failure behavior is a policy decision. A high-risk submission might fail closed, while a lower-risk batch could queue for retry. Silent pass-through is dangerous unless explicitly accepted for the workflow. The client library should make the choice easy to enforce: Maskflare's SDKs raise a distinct error when the API rejects a request, with a status, a code and, for rate limits, how long to wait, and a different error when the request never reached the API at all. Your code catches them and decides.

Retries deserve a second look. The SDKs retry twice by default on rate limits and server errors, honoring Retry-After. A mask call isn't idempotent: if an attempt times out after the server processed it, the retry produces fresh tokens and the first set is never used. Both sets stay resolvable, which is harmless, but it means you shouldn't rely on two calls producing identical random tokens.

Redaction sits on the request path, so measure it the way your users will feel it. Maskflare's engine adds about 2 ms (median) to a 10 KB chat request with the default rules, 4.3 ms at the 99th percentile, and around 10 ms with all 574 detectors switched on. Network time from your service to the API comes on top and usually dominates, so run your test from the region your application runs in.

Check the limits that shape your code: the maximum request size per environment, requests per minute per key, how many tokens a restore call accepts at once (Maskflare's restore resolves up to 100 per call, and the SDKs split longer lists automatically), and the default timeout (10 seconds in the SDKs, configurable).

A redaction API is the right tool when you control the code path and the destination isn't only an AI provider: application logs, a data pipeline, a support-ticket export, text you store and show later. Use an official SDK rather than raw HTTP so retries, batching and error types are handled consistently. Maskflare's are pip install maskflare for Python (sync and asyncio clients) and npm install @maskflare/sdk for TypeScript, which has no runtime dependencies and runs on Node 18 and later, Deno, Bun and Cloudflare Workers.

When the destination is an AI provider, a gateway is usually less work: change the SDK's base URL and every request is masked and the answer restored, streaming and tool calls included, without calling mask yourself. If you already run a LiteLLM proxy, a guardrail plugin does the same at that layer. Many teams use two of the three: the gateway for model traffic, the API for logs.

Run this against every candidate with the same approved test data, and keep the results per data type so you can compare like with like.