API Documentation

Tutorial 1: Handling Character Offsets

Offsets are zero-based character indexes into the exact string you submitted; end is exclusive. That means text[start:end] in Python (or text.slice(start, end) in JavaScript) always equals the entity's text field. Two rules keep offsets reliable: (1) keep an untouched copy of the submitted text — any normalization (trimming, collapsing whitespace, decoding entities) must happen before the API call, never between the call and offset use; (2) when replacing spans, work right-to-left so earlier offsets stay valid.

import requests

text = "Contact John Doe at [email protected] or 555-123-4567."

resp = requests.post(
    "https://piidetectionapi.com/api/moderate.php",
    json={
        "api_key": "YOUR_API_KEY",
        "api_type": "pii_detection",
        "text": text,
    },
    timeout=30,
)
data = resp.json()

for e in data["detected_entities"]:
    # The offsets always slice back to the matched text
    assert text[e["start"]:e["end"]] == e["text"]
    print(f"{e['type']:15s} {e['start']:4d}-{e['end']:4d}  {e['text']}")

One caveat for JavaScript: String.prototype.slice counts UTF-16 code units, so emoji and some non-Latin characters occupy two units. If your text contains such characters, compare against the entity's text field and adjust with a code-point-aware index if needed.

Tutorial 2: Building a Redaction Pipeline from Detection Output

The API already returns anonymized_text, but many teams need custom redaction: their own placeholder format, partial masking (keep the last 4 digits of a card), or per-type policies. Detection output gives you everything required — replace spans from the end of the string backwards so offsets never shift:

def redact(text, entities):
    """Apply custom per-type redaction using detection offsets."""
    def policy(e):
        if e["type"] == "CREDIT_CARD_NUMBER":
            return "****-****-****-" + e["text"][-4:]   # keep last 4
        if e["type"] == "EMAIL_ADDRESS":
            return "<email removed>"
        return f"[{e['type']}]"                          # default placeholder

    # Sort by start descending: right-to-left replacement keeps offsets valid
    for e in sorted(entities, key=lambda x: x["start"], reverse=True):
        text = text[:e["start"]] + policy(e) + text[e["end"]:]
    return text

data = resp.json()
clean = redact(original_text, data["detected_entities"])

The same pattern powers highlighting in review UIs (wrap spans in <mark> tags instead of replacing them) and audit logs (store type + offsets, never the raw value). For end-to-end pipeline architectures see PII detection in ETL & streaming pipelines.

Tutorial 3: Batch Processing

To scan many records — support tickets, log lines, database rows — send one request per record and parallelize within your plan's rate limit. A bounded thread pool with a small concurrency (4–8 workers) saturates throughput without triggering 429s:

import requests
from concurrent.futures import ThreadPoolExecutor

API_URL = "https://piidetectionapi.com/api/moderate.php"

def detect(record):
    resp = requests.post(API_URL, json={
        "api_key": "YOUR_API_KEY",
        "api_type": "pii_detection",
        "text": record["text"],
        "threshold": 0.4,          # favor recall for discovery scans
    }, timeout=60)
    data = resp.json()
    return {
        "id": record["id"],
        "entities": data.get("detected_entities", []),
        "count": data.get("entities_detected", 0),
    }

records = [{"id": i, "text": t} for i, t in enumerate(load_tickets())]

with ThreadPoolExecutor(max_workers=6) as pool:
    results = list(pool.map(detect, records))

flagged = [r for r in results if r["count"] > 0]
print(f"{len(flagged)}/{len(results)} records contain PII")

Tips: keep each record under the 50,000-character limit; batch related short strings (e.g. all fields of one row) into a single request with clear separators to save per-request overhead; and persist results keyed by record ID so re-runs can skip already-scanned data.

Tutorial 4: Streaming & Chunking Long Documents

For documents beyond 50,000 characters, split on paragraph boundaries — never mid-sentence, because context is what lets the model distinguish a name from an ordinary word. Track each chunk's base offset and shift the returned entity offsets back into document coordinates:

MAX_CHARS = 50000

def chunk_document(doc):
    """Yield (base_offset, chunk) pairs split on paragraph boundaries."""
    start = 0
    while start < len(doc):
        end = min(start + MAX_CHARS, len(doc))
        if end < len(doc):
            cut = doc.rfind("\n\n", start, end)   # last paragraph break
            if cut > start:
                end = cut
        yield start, doc[start:end]
        start = end

all_entities = []
for base, chunk in chunk_document(long_document):
    resp = requests.post(API_URL, json={
        "api_key": "YOUR_API_KEY",
        "api_type": "pii_detection",
        "text": chunk,
    }, timeout=120)
    for e in resp.json()["detected_entities"]:
        e["start"] += base       # remap into document coordinates
        e["end"]   += base
        all_entities.append(e)

print(f"{len(all_entities)} entities across the whole document")

For streaming sources (chat messages, Kafka topics, log tails), scan each message as it arrives — messages are naturally sized well below the limit. Real-time patterns are covered in real-time PII filtering for chatbots and scanning application logs for PII.

Tutorial 5: Retries & Timeouts

Treat 429 and 5xx as retryable with exponential backoff plus jitter; treat 400/401/402/413 as permanent and surface them immediately. Set a generous client timeout — large texts can take several seconds — and always send requests over HTTPS:

async function detectPII(text, { retries = 3 } = {}) {
    for (let attempt = 0; attempt <= retries; attempt++) {
        const controller = new AbortController();
        const timer = setTimeout(() => controller.abort(), 60000);
        try {
            const res = await fetch('https://piidetectionapi.com/api/moderate.php', {
                method: 'POST',
                headers: { 'Content-Type': 'application/json' },
                body: JSON.stringify({
                    api_key: process.env.PII_API_KEY,
                    api_type: 'pii_detection',
                    text
                }),
                signal: controller.signal
            });
            const data = await res.json();

            if (data.status === 200) return data;
            if (data.status === 429 || data.status >= 500) {
                // retryable: exponential backoff + jitter
                const wait = Math.pow(2, attempt) * 1000 + Math.random() * 500;
                await new Promise(r => setTimeout(r, wait));
                continue;
            }
            throw new Error(`PII API error ${data.status}: ${data.error}`);
        } finally {
            clearTimeout(timer);
        }
    }
    throw new Error('PII API: max retries exceeded');
}

Tutorial 6: Best Practices & Security

Integration best practices:

• Scan before storage, not after. Detect PII at the ingestion boundary (API gateway, message consumer, upload handler) so raw sensitive data never lands in logs, analytics, or LLM prompts. See PII detection for LLM guardrails.
• Restrict entities to what you act on. Smaller result sets are easier to review, and your policies stay explicit.
• Tune threshold per use case. Low (0.2–0.4) for discovery/DLP where recall matters; high (0.8+) for automated redaction where false positives damage documents.
• Log entity types and offsets, never values. An audit record of {"type": "SSN", "start": 71, "end": 82} proves what was found without re-creating the exposure.
• Use hash mode when analytics must survive masking. Consistent hashes preserve joins and counts across records.
• Version your configuration. Store the entity list, threshold, and custom instructions in config so compliance can review exactly what production scans for.

Security: all traffic is TLS-encrypted end to end; submitted text is processed in memory and never stored or used for training; API keys can be rotated and revoked instantly from your dashboard; and the platform is GDPR-native audited. For workloads where data cannot leave your network, an on-premise deployment of the same detection engine is available — contact us. Details on data handling are on the data privacy page.