API DocsAnonymization

Anonymization

Anonymize text and files, anonymous LLM chat with automatic de-anonymization.

Text Anonymization

Automatically mask personally identifiable information (PII) in any text.

POST/api/anonymize

Send the text to anonymize in the request body.

Parameter	Type	Default	Description
`text`required	`string`	-	The text to be anonymized.
`language`	`string`	`"de"`	Language of the text (e.g. de, en). Improves detection accuracy.

Example request

1curl -X POST https://app.anymize.ai/api/anonymize \
2  -H "Authorization: Bearer YOUR_API_KEY" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "text": "Max Mustermann wohnt in Berlin und seine E-Mail ist max@example.com",
6    "language": "de"
7  }'

Example response

The anonymized text contains placeholders for detected entities.

202Accepted

{
  "job_id": "11111111-1111-4111-8111-111111111111",
  "status": "processing",
  "message": "Job created. Use /api/status/{job_id} to check status.",
  "zdr": false
}

Need to anonymize files?

For documents and images, use File Anonymization.

File Anonymization

Endpoint

Upload documents or images for OCR processing and automatic anonymization.

POST/api/ocr

Supported Formats

The following file formats are supported for OCR processing.

PDF

PNG

JPG

TIFF

Parameters

Parameter	Type	Default	Description
`file`required	`File`	-	Document or image file (PDF, PNG, JPG, TIFF), up to 100 MB

Multipart Upload

File uploads must use multipart/form-data encoding, not JSON.

Up to 100 MB per file

Larger files get a 413 with the code FILE_TOO_LARGE, usually straight from Content-Length, before the file is fully up. Check the code field, not the text in error.

Example Request

1curl -X POST https://app.anymize.ai/api/ocr \
2  -H "Authorization: Bearer YOUR_API_KEY" \
3  -F "file=@document.pdf"

Response

Returns a job ID. Processing runs asynchronously — check status with the Status API.

202Accepted

{
  "job_id": "11111111-1111-4111-8111-111111111111",
  "status": "processing",
  "message": "Document submitted for OCR and anonymization. Use /api/status/{job_id} to check status."
}

413Payload Too Large

{
  "error": "FILE_TOO_LARGE",
  "code": "FILE_TOO_LARGE",
  "maxBytes": 104857600
}

Processing Pipeline

File anonymization runs through a 3-step pipeline.

1OCR extracts text from the uploaded document

2Anonymization pipeline detects and replaces personal data

3Anonymized document is available for export

Check processing status

Use the Job Status API to poll for completion. Processing time depends on file size.

Anonymous Chat

Endpoint

Combine chat and anonymization in a single request — your data is masked before reaching the model.

POST/api/v1/llm-anonymous/chat/completions

Base URL for anonymous chathttps://app.anymize.ai/api/v1/llm-anonymous

Flow

Here's how anonymous chat processes your request:

1Your message is received and analyzed.

2Personal data is automatically masked.

3The anonymized text is sent to the model.

4The response is de-anonymized and returned to you.

Higher Latency

Due to automatic anonymization before the LLM call and de-anonymization of the response, there is higher latency compared to the standard chat endpoint. Expect roughly 2-5 seconds of additional processing time.

Parameters

Same parameters as Chat Completions plus anonymization options.

Parameter	Type	Default	Description
`model`required	`string`	-	Model ID — all chat models are supported.
`messages`required	`array`	-	Array of messages (system, user, assistant).
`language`	`string`	`"de"`	Text language for better PII detection.
`stream`	`boolean`	`false`	Enable SSE streaming.

Placeholder Handling

In anonymous chat, personal data is automatically replaced with placeholders in the format [[Type-HASH]]. For de-anonymization to work, the model must preserve these placeholders exactly.

Wrong

Dear [name redacted], I am writing to you regarding...

Correct

Dear Mr. [[Person-ABC123]], I am writing to you regarding...

Without the right system prompt, the model often writes 'an anonymized person' or '[name redacted]' instead of using the placeholder [[Person-ABC123]]. This makes de-anonymization impossible.

The anonymous endpoint automatically appends the following part to your system prompt. It is added to your own system prompt, not replacing it:

Auto-injected system prompt part

1## CRITICAL RULE: ANONYMIZATION PLACEHOLDERS
2
3THIS IS THE MOST IMPORTANT RULE. VIOLATING IT MAKES YOUR RESPONSE USELESS.
4
5The user's messages contain anonymized placeholders shaped [[<Type>-<HASH>]],
6where <Type> is the PII category (person, email, iban, telephone_number,
7address, ...) and <HASH> is a short random code.
8
9FORBIDDEN:
10- Writing "[Name anonymisiert]" or "[anonymized]"
11- Describing WHAT the placeholder is instead of USING it
12- Writing a double-bracket token that was NOT in the user's message — the hash
13  is a database key, so an invented one resolves to nothing. Never copy a hash
14  out of these instructions.
15
16REQUIRED:
17- Copy each placeholder character-for-character from the user's message
18- Use it inline like the real value: "Herr <placeholder> hat..."
19- Need a value the user never gave you? Use SINGLE brackets ([Name]).
20
21WHY: After your response, placeholders get replaced with real values.
22BEFORE RESPONDING: Check that every double-bracket token also appears, character-for-character, in the user's message.

Automatically injected

This text is appended to your system prompt as an addition. Your own system prompt is fully preserved. You don't need to add this part yourself.

Example request

1curl -X POST https://app.anymize.ai/api/v1/llm-anonymous/chat/completions \
2  -H "Authorization: Bearer YOUR_API_KEY" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "model": "fountain-1.0",
6    "messages": [
7      {"role": "user", "content": "Schreibe eine E-Mail an Max Mustermann, max@example.com, wegen dem Termin am 15. Januar."}
8    ],
9    "language": "de",
10  }'

Response

The response contains the de-anonymized text and metadata.

200OK

{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "model": "fountain-1.0",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Sehr geehrter Herr Max Mustermann,\n\nich schreibe Ihnen bezüglich unseres Termins am 15. Januar..."
      },
      "finish_reason": "stop"
    }
  ],
  "_anymize": {
    "anonymized": true,
    "job_id": "44444444-4444-4444-8444-444444444444",
    "language": "de"
  }
}

Response header

The x-anonymization-job-id header contains the job ID for later reference.

Zero Data Retention

Zero Data Retention (ZDR) is configured in your account settings, not per API request. When ZDR is enabled, no jobs or hash pairs are stored. De-anonymization is not available.

Credit usage

Anonymous chat consumes credits for two services:

•LLM credits for model usage (same as regular chat).
•Anonymization credits for PII masking.

De-Anonymization

Overview

Replace placeholders with original data — reverse the anonymization.

POST/api/deanonymize

Parameters

Send the anonymized text and job ID to restore the original data.

Parameter	Type	Default	Description
`text`required	`string`	-	The text with placeholders to de-anonymize.

Placeholder format

Placeholders follow the pattern [TYPE_123], e.g. [PERSON_1] or [ADDRESS_2].

Example request

1curl -X POST https://app.anymize.ai/api/deanonymize \
2  -H "Authorization: Bearer YOUR_API_KEY" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "text": "Sehr geehrter [[Person-QSEZB6]], Ihre Adresse [[Adress-NT9DQE]] wurde aktualisiert."
6  }'

Response

The de-anonymized text contains the original data in place of placeholders.

200OK

{
  "text": "Sehr geehrter Max Mustermann, Ihre Adresse Berliner Str. 42, 10115 Berlin wurde aktualisiert.",
  "replacements": 2
}

Limitations

Zero Data Retention

De-anonymization is not available when Zero Data Retention (ZDR) is enabled in your account settings.

•The job ID must exist and not be expired.
•The original job must not have been created with ZDR.
•Only the user who created the job can de-anonymize.

Error cases

Common de-anonymization errors and what they mean.

404Not Found

{
  "error": {
    "message": "No hash pairs found for the given placeholders",
    "type": "not_found_error",
    "code": "hash_pairs_not_found"
  }
}

Hash Pairs

Endpoint

Retrieve the mapping table between placeholders and original data.

GET/api/status/{jobId}/strings

Parameters

Parameter	Type	Default	Description
`jobId`required	`string`	-	The job ID of the anonymization job.

Response

The response contains an array of pairs with placeholder and original value.

200Hash Pairs

{
  "job_id": "11111111-1111-4111-8111-111111111111",
  "count": 6,
  "hash_pairs": [
    {
      "original": "Max Mustermann",
      "hash": "A1B2C3",
      "prefix_name": "Person",
      "placeholder": "[[Person-A1B2C3]]"
    },
    {
      "original": "Berlin",
      "hash": "D4E5F6",
      "prefix_name": "Location",
      "placeholder": "[[Location-D4E5F6]]"
    },
    {
      "original": "Acme GmbH",
      "hash": "G7H8I9",
      "prefix_name": "Organization",
      "placeholder": "[[Organization-G7H8I9]]"
    },
    {
      "original": "15.03.1990",
      "hash": "J1K2L3",
      "prefix_name": "Date",
      "placeholder": "[[Date-J1K2L3]]"
    },
    {
      "original": "max@example.com",
      "hash": "M4N5P6",
      "prefix_name": "Email",
      "placeholder": "[[Email-M4N5P6]]"
    },
    {
      "original": "+49 170 1234567",
      "hash": "Q7R8S9",
      "prefix_name": "Phone",
      "placeholder": "[[Phone-Q7R8S9]]"
    }
  ]
}

Entity types

Placeholders are categorized by type: PERSON, ADDRESS, PHONE, EMAIL, etc.

Person[[Person-HASH]]

Location[[Location-HASH]]

Organization[[Organization-HASH]]

Date[[Date-HASH]]

Email[[Email-HASH]]

Phone[[Phone-HASH]]

Address[[Address-HASH]]

IBAN[[IBAN-HASH]]

ID[[ID-HASH]]

Restrictions

Zero Data Retention

When Zero Data Retention (ZDR) is enabled in your account settings, no hash pairs are stored and this endpoint returns no data.

Example request

1curl https://app.anymize.ai/api/status/11111111-1111-4111-8111-111111111111/strings \
2  -H "Authorization: Bearer YOUR_API_KEY"

Use cases

Typical scenarios where hash pairs are useful:

•Anonymization quality check — verify what was masked.
•Partial de-anonymization — replace only specific placeholders.
•Audit and compliance — document which data was anonymized.