API documentation

curl -s -X POST 'https://www.pii.kwizmo.eu/api.php?action=pseudonymize' \
  -H 'Content-Type: application/json' \
  -d '{
    "text": "Spoštovani gospod Novak, moje ime je Maja Kovačič. Tel: 041 123 456",
    "accept_terms": true
  }'

{
  "ok": true,
  "text": "Spoštovani gospod Zajc, moje ime je Irena Božič. Tel: 078 369 169",
  "locale": "sl",
  "replacements": 4,
  "mapping": [
    { "type": "phone", "original": "041 123 456", "pseudonym": "078 369 169" },
    { "type": "name",  "original": "Novak",       "pseudonym": "Zajc" },
    { "type": "name",  "original": "Maja",        "pseudonym": "Irena" },
    { "type": "name",  "original": "Kovačič",     "pseudonym": "Božič" }
  ],
  "fallback": false,
  "warning": null,
  "processing_ms": 14
}

{
  "text": "Poštovani gospodine Kovačeviću, šaljem ugovor br. 45/2023.",
  "locale": "hr",
  "disable": ["ip", "email"],
  "known_names": ["Ivana Marić", "Petar Babić"],
  "key": "b6Jq0v7yZ3-our-team-key",
  "include_mapping": true,
  "accept_terms": true
}

{
  "texts": [
    "Poštovani gospodine Kovačeviću, šaljem ugovor.",
    "Razgovarao sam s gospodinom Kovačevićem. Kovačević se slaže."
  ],
  "locale": "hr",
  "accept_terms": true
}

{
  "ok": true,
  "texts": [
    "Poštovani gospodine Blaževiću, šaljem ugovor.",
    "Razgovarao sam s gospodinom Blaževićem. Blažević se slaže."
  ],
  "locales": ["hr", "hr"],
  "replacements": 3,
  "mapping": [
    { "type": "name", "original": "Kovačević",   "pseudonym": "Blažević" },
    { "type": "name", "original": "Kovačeviću",  "pseudonym": "Blaževiću" },
    { "type": "name", "original": "Kovačevićem", "pseudonym": "Blaževićem" }
  ],
  "fallback": false,
  "warning": null,
  "processing_ms": 9
}

{
  "text": "Hvala, gospodine Blaževiću. Blažević će dobiti odgovor danas.",
  "mapping": [
    { "original": "Kovačević",  "pseudonym": "Blažević" },
    { "original": "Kovačeviću", "pseudonym": "Blaževiću" }
  ],
  "accept_terms": true
}

{
  "ok": true,
  "text": "Hvala, gospodine Kovačeviću. Kovačević će dobiti odgovor danas.",
  "processing_ms": 1
}

curl -s 'https://www.pii.kwizmo.eu/api.php?action=info&pretty'
curl -s 'https://www.pii.kwizmo.eu/api.php?action=openapi' -o openapi.json

{
  "ok": false,
  "error": {
    "code": "rate_limited",
    "message": "Too many requests. The limit is 10 requests per minute per network.",
    "retry_after": 42
  }
}

<?php
// PHP 7.4+, no Composer or extensions needed.

function piiApi(string $action, array $payload): array
{
    $payload['accept_terms'] = true;
    $context = stream_context_create([
        'http' => [
            'method'        => 'POST',
            'header'        => "Content-Type: application/json\r\n",
            'content'       => json_encode($payload, JSON_UNESCAPED_UNICODE),
            'timeout'       => 30,
            'ignore_errors' => true, // read the JSON body of 4xx/5xx responses too
        ],
    ]);
    for ($attempt = 1; $attempt <= 3; $attempt++) {
        $body = file_get_contents('https://www.pii.kwizmo.eu/api.php?action=' . urlencode($action), false, $context);
        $data = json_decode((string) $body, true);
        if (!is_array($data)) {
            throw new RuntimeException('The PII service did not return JSON.');
        }
        if ($data['ok'] ?? false) {
            return $data;
        }
        if (($data['error']['code'] ?? '') === 'rate_limited' && $attempt < 3) {
            sleep((int) ($data['error']['retry_after'] ?? 60)); // wait as instructed, then retry
            continue;
        }
        throw new RuntimeException($data['error']['message'] ?? 'PII service error');
    }
    throw new RuntimeException('The PII service stayed rate limited.');
}

// 1. Pseudonymize before sending the text anywhere
$result = piiApi('pseudonymize', [
    'text'        => $ticketText,
    'locale'      => 'sl',
    'known_names' => [$customer['full_name']],
]);
$safeText = $result['text'];
$mapping  = $result['mapping'];   // contains real data: keep it in memory only

// 2. Use the safe text with an external service
$reply = $externalService->answer($safeText);

// 3. Put the real values back into the reply
$restored = piiApi('restore', ['text' => $reply, 'mapping' => $mapping]);
echo $restored['text'];

// Browser or Node.js 18+
async function piiApi(action, payload) {
  const response = await fetch('https://www.pii.kwizmo.eu/api.php?action=' + action, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ ...payload, accept_terms: true }),
  });
  const data = await response.json();
  if (!data.ok) {
    const err = new Error(data.error.message);
    err.code = data.error.code;
    err.retryAfter = data.error.retry_after;
    throw err;
  }
  return data;
}

const { text: safeText, mapping } = await piiApi('pseudonymize', {
  text: 'Sehr geehrte Frau Dr. Müller, meine Adresse ist Karl-Marx-Straße 12, 10115 Berlin.',
  locale: 'de',
});

const reply = await askSomeService(safeText);

const { text: realReply } = await piiApi('restore', { text: reply, mapping });

import time
import requests

API = "https://www.pii.kwizmo.eu/api.php"

def pii_api(action, payload, retries=3):
    payload = {**payload, "accept_terms": True}
    for attempt in range(retries):
        r = requests.post(API, params={"action": action}, json=payload, timeout=30)
        data = r.json()
        if data.get("ok"):
            return data
        if data["error"]["code"] == "rate_limited" and attempt < retries - 1:
            time.sleep(int(r.headers.get("Retry-After", 60)))
            continue
        raise RuntimeError(f'{data["error"]["code"]}: {data["error"]["message"]}')

result = pii_api("pseudonymize", {
    "texts": ["Зовем се Јелена Јовановић, ЈМБГ 2505905710011.", "Јелена ће доћи сутра."],
    "locale": "sr",
    "key": "a-long-random-key-for-this-project",
})
safe_texts = result["texts"]
restored = pii_api("restore", {"texts": safe_texts, "mapping": result["mapping"]})