Detection API
Batch Detection
Detect PII across multiple texts in a single API call with the batch detection endpoint.
Batch Detection
Use batch detection when you need to scan several texts in one request, such as chat transcripts, imported tickets, CRM notes, or queued documents. The endpoint returns one standard DetectResponse per input text, plus batch-level totals.
POST /api/v1/detect/batch
Submit up to 50 texts in a single request. Each text can be up to 50000 characters.
Request body
DetectBatchRequest
| Field | Type | Required | Description |
|---|---|---|---|
texts | string[] | Yes | Between 1 and 50 input texts, each up to 50000 characters |
country | string | null | No | ISO country code. Set to null for automatic country detection |
language | string | null | No | Shared language hint for the batch |
privacy_preset | string | No | "conservative", "balanced", or "aggressive" |
{
"texts": [
"Customer email: eva.kralova@example.cz, phone: 777 555 222.",
"Payroll note: PESEL 44051401458 assigned to Jan Kowalski.",
"French vendor record lists SIREN 552120222 and contact finance@paris-example.fr."
],
"country": null,
"language": "en",
"privacy_preset": "balanced"
}Response body
DetectBatchResponse
| Field | Type | Description |
|---|---|---|
results | DetectResponse[] | Per-text detection results |
total_entities | integer | Total detected entities across the batch |
total_processing_time_ms | integer | Total processing time for the request |
Batch detection example
curl -X POST "https://api.fastpii.com/api/v1/detect/batch" \
-H "Authorization: Bearer fpk_your_api_key" \
-H "Content-Type: application/json" \
-d '{
"texts": [
"Customer email: eva.kralova@example.cz, phone: 777 555 222.",
"Payroll note: PESEL 44051401458 assigned to Jan Kowalski.",
"French vendor record lists SIREN 552120222 and contact finance@paris-example.fr."
],
"country": null,
"language": "en",
"privacy_preset": "balanced"
}'import requests
payload = {
"texts": [
"Customer email: eva.kralova@example.cz, phone: 777 555 222.",
"Payroll note: PESEL 44051401458 assigned to Jan Kowalski.",
"French vendor record lists SIREN 552120222 and contact finance@paris-example.fr.",
],
"country": None,
"language": "en",
"privacy_preset": "balanced",
}
response = requests.post(
"https://api.fastpii.com/api/v1/detect/batch",
headers={
"Authorization": "Bearer fpk_your_api_key",
"Content-Type": "application/json",
},
json=payload,
timeout=60,
)
print(response.status_code)
print(response.json())Response:
{
"results": [
{
"text": "Customer email: eva.kralova@example.cz, phone: 777 555 222.",
"entities": [
{
"type": "email",
"original": "eva.kralova@example.cz",
"country": "CZ",
"confidence": 0.99,
"validated": true,
"start": 16,
"end": 38,
"metadata": {
"normalized": "eva.kralova@example.cz"
}
},
{
"type": "phone_number",
"original": "777 555 222",
"country": "CZ",
"confidence": 0.95,
"validated": true,
"start": 47,
"end": 58,
"metadata": {
"e164": "+420777555222",
"line_type": "mobile"
}
}
],
"countries_detected": [
{
"code": "CZ",
"confidence": 0.98
}
],
"privacy_preset": "balanced",
"processing_time_ms": 16,
"api_version": "v1"
},
{
"text": "Payroll note: PESEL 44051401458 assigned to Jan Kowalski.",
"entities": [
{
"type": "pesel",
"original": "44051401458",
"country": "PL",
"confidence": 1.0,
"validated": true,
"start": 21,
"end": 32,
"metadata": {
"birth_date": "1944-05-14",
"gender": "male",
"checksum_valid": true
}
}
],
"countries_detected": [
{
"code": "PL",
"confidence": 0.97
}
],
"privacy_preset": "balanced",
"processing_time_ms": 14,
"api_version": "v1"
},
{
"text": "French vendor record lists SIREN 552120222 and contact finance@paris-example.fr.",
"entities": [
{
"type": "siren",
"original": "552120222",
"country": "FR",
"confidence": 1.0,
"validated": true,
"start": 33,
"end": 42,
"metadata": {
"checksum_valid": true
}
},
{
"type": "email",
"original": "finance@paris-example.fr",
"country": "FR",
"confidence": 0.98,
"validated": true,
"start": 55,
"end": 79,
"metadata": {
"normalized": "finance@paris-example.fr"
}
}
],
"countries_detected": [
{
"code": "FR",
"confidence": 0.98
}
],
"privacy_preset": "balanced",
"processing_time_ms": 17,
"api_version": "v1"
}
],
"total_entities": 5,
"total_processing_time_ms": 47
}Performance considerations
Batch detection reduces HTTP overhead and works well for queue workers, ETL jobs, and document ingestion. It is usually more efficient than sending many single-text requests when the payloads are small to medium in size.
Keep these guidelines in mind:
| Consideration | Recommendation |
|---|---|
| Batch size | Start with 10 to 25 texts per request for steady throughput |
| Large texts | Use smaller batches when individual texts are close to 50000 characters |
| Mixed countries | Leave country as null when records may span several countries |
| Retries | Retry only failed requests, with backoff on 429 responses |
| Latency-sensitive flows | Use POST /api/v1/detect for single interactive requests |
Rate limits
Batch requests follow the same API key authentication and request window limits as other Detection API endpoints.
| Limit | Value |
|---|---|
| Default request rate | 60 requests per minute |
| Max texts per batch | 50 |
| Max text size | 50000 characters per text |
If you exceed your request window, the API returns 429 Too Many Requests with Retry-After and related rate limit headers.