Protection API
Batch Protection
Protect PII across multiple texts in a single API call with the batch protection endpoint.
Batch Protection
The batch protection endpoint lets you protect PII across multiple texts in a single API call. This is more efficient than making separate requests when you need to process many documents at once.
POST /api/v1/protect/batch
Protect PII in up to 50 texts per request.
Request body
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
| texts | list[string] | Yes | - | Texts to protect (1-50 items, each max 50,000 characters) |
| mode | string | No | "replace" | Protection mode: replace, mask, hash, tokenize, policy |
| country | string | No | null | ISO 3166-1 alpha-2 country code. Auto-detected if null. |
| language | string | No | null | Language hint for detection |
| privacy_preset | string | No | null | "conservative", "balanced", or "aggressive" |
The policy mode requires an Enterprise plan. If you use policy mode on a non-Enterprise plan, the API returns a 400 error.
Response fields
| Field | Type | Description |
|---|---|---|
| results | list[ProtectResponse] | Protection results for each text |
| total_entities | integer | Total entities found across all texts |
| total_processing_time_ms | float | Total processing time in milliseconds |
Each item in results has the same structure as a single protect response.
Batch protection example
curl -X POST https://api.fastpii.com/api/v1/protect/batch \
-H "Authorization: Bearer fpk_your_api_key" \
-H "Content-Type: application/json" \
-d '{
"texts": [
"Email: jan.novak@example.cz, RČ: 8001011238",
"PESEL: 44051401458, telefon: +48 123 456 789",
"Steuer-ID: 86095742719, Adresse: Berliner Str. 1"
],
"mode": "mask"
}'import requests
response = requests.post(
"https://api.fastpii.com/api/v1/protect/batch",
headers={"Authorization": "Bearer fpk_your_api_key"},
json={
"texts": [
"Email: jan.novak@example.cz, RČ: 8001011238",
"PESEL: 44051401458, telefon: +48 123 456 789",
"Steuer-ID: 86095742719, Adresse: Berliner Str. 1",
],
"mode": "mask",
},
)
result = response.json()Response:
{
"results": [
{
"original_text": "Email: jan.novak@example.cz, RČ: 8001011238",
"protected_text": "Email: *******************, RČ: **********",
"entities": [
{"type": "email", "original": "jan.novak@example.cz", "protected": "*******************", "country": "cz", "confidence": 0.95, "validated": false, "start": 7, "end": 27, "metadata": {}},
{"type": "rodne_cislo", "original": "8001011238", "protected": "**********", "country": "cz", "confidence": 1.0, "validated": true, "start": 33, "end": 43, "metadata": {"checksum_valid": true}}
],
"countries_detected": [{"code": "cz", "confidence": 0.98}],
"protection_mode": "mask",
"processing_time_ms": 3.5,
"api_version": "v1"
},
{
"original_text": "PESEL: 44051401458, telefon: +48 123 456 789",
"protected_text": "PESEL: ***********, telefon: ***************",
"entities": [
{"type": "pesel", "original": "44051401458", "protected": "***********", "country": "pl", "confidence": 1.0, "validated": true, "start": 7, "end": 18, "metadata": {"checksum_valid": true}},
{"type": "phone", "original": "+48 123 456 789", "protected": "***************", "country": "pl", "confidence": 0.85, "validated": false, "start": 28, "end": 44, "metadata": {}}
],
"countries_detected": [{"code": "pl", "confidence": 0.97}],
"protection_mode": "mask",
"processing_time_ms": 3.8,
"api_version": "v1"
},
{
"original_text": "Steuer-ID: 86095742719, Adresse: Berliner Str. 1",
"protected_text": "Steuer-ID: ***********, Adresse: **************",
"entities": [
{"type": "steuer_id", "original": "86095742719", "protected": "***********", "country": "de", "confidence": 1.0, "validated": true, "start": 11, "end": 22, "metadata": {"checksum_valid": true}},
{"type": "address", "original": "Berliner Str. 1", "protected": "**************", "country": "de", "confidence": 0.75, "validated": false, "start": 33, "end": 48, "metadata": {}}
],
"countries_detected": [{"code": "de", "confidence": 0.96}],
"protection_mode": "mask",
"processing_time_ms": 3.2,
"api_version": "v1"
}
],
"total_entities": 4,
"total_processing_time_ms": 10.5
}Batch with different modes
You can use any protection mode with batch:
curl -X POST https://api.fastpii.com/api/v1/protect/batch \
-H "Authorization: Bearer fpk_your_api_key" \
-H "Content-Type: application/json" \
-d '{
"texts": [
"RČ: 8001011238",
"IČO: 25594231"
],
"mode": "hash",
"country": "cz"
}'Performance considerations
| Approach | When to use | Throughput |
|---|---|---|
| Single protect | Real-time requests, 1 text per call | Lower latency per request |
| Batch protect | Processing multiple documents, background jobs | Higher throughput overall |
Batch protection processes all texts in a single server round-trip, reducing network overhead. For best performance:
- Send full batches (up to 50 texts) rather than many small batches
- Use batch for background processing, not for latency-sensitive real-time requests
- Keep each text under the 50,000 character limit
Rate limits
Batch endpoints share the same rate limit pool as single protection endpoints. Each batch request counts as one API call regardless of the number of texts in the batch.
Using with FastPII Connect
from fastpii_connect import FastPIIClient
client = FastPIIClient(api_key="fpk_your_api_key")
result = client.protect_batch(
texts=[
"Email: jan.novak@example.cz, RČ: 8001011238",
"PESEL: 44051401458",
],
mode="mask",
country="cz",
)
print(f"Total entities: {result.total_entities}")
print(f"Processing time: {result.total_processing_time_ms}ms")See the client reference for full method signatures.