Skip to content

pseudonymize.io API

Welcome to the pseudonymize.io documentation. Put this API in the path of your sensitive data before it reaches external systems (like LLMs, analytics warehouses, or third-party support tools).

Quickstart

Send a request to the Text API to pseudonymize prose.

curl -X POST https://api.pseudonymize.io/text \
  -H "Authorization: Bearer ps_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Alice Rossi disputed invoice INV-204 from [email protected]",
    "policy": "default"
  }'

Response:

{
  "text": "PERSON_01 disputed invoice INV-204 from EMAIL_01",
  "entities": [
    { "type": "PERSON", "original": "Alice Rossi", "pseudonym": "PERSON_01" },
    { "type": "EMAIL", "original": "[email protected]", "pseudonym": "EMAIL_01" }
  ],
  "tokensProcessed": 12,
  "creditsSpent": 1,
  "creditsRemaining": 9
}

Security Warning on Downstream Forwarding: The entities array contains the original PII mapping exclusively for client-side audit logging and local verification. Do not forward the full response body downstream to external LLMs or third parties. Send only the transformed text or data fields to external recipients.

Authentication

All API requests must include your API key in the Authorization header.

Authorization: Bearer ps_live_...

API keys are generated in the format ps_live_.... For your security, the complete secret key is displayed only once upon creation. pseudonymize.io never stores API keys in plaintext—only a non-reversible cryptographic hash (SHA-256) and a short identifying prefix (ps_live_XXXX) are persisted.

You can manage your API keys in the Dashboard.

Text API

POST https://api.pseudonymize.io/text (also available via POST https://api.pseudonymize.io/v1/text and /api/v1/text)

Replaces identifiers inside prose without flattening the text around them.

Request Body

  • text (string, required): The text to process.
  • policy (string, optional): The policy to use. Defaults to "default".
  • detect (array, optional): Specific entity types to detect.
{
  "text": "Call me at +39 333 1234567.",
  "detect": ["PHONE"]
}

Structured Data API

POST /api/v1/data

Pseudonymize identifier fields while keeping rows and schemas usable.

Request Body

  • payload (object | array, required): The JSON structure to process (can also be passed as data).
  • policy (string, optional): The policy to use. Defaults to "default".
  • detect (array, optional): Specific entity types to detect.
{
  "payload": {
    "user": {
      "name": "Mario Rossi",
      "email": "[email protected]"
    }
  },
  "detect": ["PERSON", "EMAIL"]
}

Billing & Credit Reservation

Pseudonymize.io operates on a transparent pay-as-you-go model:

  • €1 per million metered tokens. Each successful request is rounded up to the next 1,000 tokens (1 credit), with a minimum charge of €0.001.
  • Pre-flight Reservation: Credits are atomically reserved at the gateway boundary before payloads reach the core engine. If an account has insufficient credits, the API returns 402 Payment Required immediately without forwarding customer data.
  • Automated Refund Guarantee: If an upstream core processing call fails or times out, reserved credits are immediately refunded in full.

Pseudonyms & Deterministic Identity

Pseudonymize.io uses deterministic identity preservation within a single request. If "Alice" appears three times in the same document, she becomes PERSON_01 all three times. This allows LLMs to understand that it is the same person without knowing who it is.

Errors & Limits

We use standard HTTP status codes.

  • 200 OK: Successful processing.
  • 400 Bad Request: Invalid or missing payload format, or structured data depth exceeding 32 levels.
  • 401 Unauthorized: Missing, invalid, or inactive API key.
  • 402 Payment Required: Insufficient credits remaining. Blocked at the gateway boundary.
  • 413 Payload Too Large: Request body exceeds 10MB or total structured element count exceeds 50,000 keys.
  • 422 Unprocessable Entity: Request contract violation or Idempotency-Key reuse mismatch against a different payload.
  • 429 Too Many Requests: Rate limit exceeded (60 req/min per API key, 120 req/min per account, 120 req/min per client IP). The Retry-After header indicates seconds to wait before retrying.
  • 502 Bad Gateway: Core engine unreachable or backend processing failure. Credits are automatically refunded.
  • 504 Gateway Timeout: Core engine did not respond within 30 seconds. Credits are automatically refunded.

Idempotency & Retries

Pseudonymize.io supports the Idempotency-Key header on all /v1/* transformation endpoints:

  • Tenant & Endpoint Scoping: Idempotency keys are strictly bound to your organization/account and the target endpoint. Keys from independent tenants do not collide.
  • Payload Verification: Each request payload is cryptographically hashed. Reusing the same key with conflicting payloads returns 422 Unprocessable Entity.
  • In-Memory Replay: Completed requests retain the response body, including entity details that may contain original identifiers, in gateway process memory for a five-minute replay window. Cached retries receive Idempotent-Replay: true without another debit. Expired responses are unavailable and are removed on access or by the one-minute cleanup sweep; restarts also lose the cache. This is transient retention, not an end-to-end zero-retention guarantee.

Rate Limiting Architecture

  • Guarantees: Rate limits are enforced using a sliding-window counter per gateway node (60 req/min per key, 120 req/min per account, 120 req/min per IP).
  • Response Headers:
    • X-RateLimit-Limit: Maximum requests permitted within the 60-second window.
    • X-RateLimit-Remaining: Remaining request capacity in the current window.
    • X-RateLimit-Reset: Seconds until window resets.
    • Retry-After: Seconds to wait when encountering HTTP 429.

Supported Entities

  • PERSON (Names)
  • ORGANIZATION (Company names)
  • EMAIL (Email addresses)
  • PHONE (Phone numbers)
  • LOCATION (Cities, addresses)
  • IP (IPv4 and IPv6)
  • IBAN (Bank accounts)
  • CARD (Credit/Debit cards)

Security

  • Gateway billing tables and structured request metrics exclude API request and response bodies. Account, authentication, usage, reservation and payment metadata are retained separately; account deletion does not purge every record or backup.
  • Successful responses with an Idempotency-Key are retained in process memory for a five-minute replay window. Entity details may contain original identifiers. Engine, proxy, swap, crash-dump and backup controls require separate verification; zero disk persistence is not guaranteed across the processing chain.
  • See the Privacy Policy and the Security page for handling and deletion limits.