PII

PII Detection & Management

The pii domain of the Aimable Platform API enables secure detection, redaction, and management of Personally Identifiable Information (PII) in text. This is critical for compliance with data privacy regulations (e.g., GDPR, CCPA) and for protecting sensitive user information in conversational AI systems.

PII includes data such as names, email addresses, phone numbers, and other identifiers that can be used to trace an individual's identity. The Aimable Platform helps you automatically detect and redact such data, replacing it with consistent placeholders across conversations to maintain context while ensuring privacy.

Key Concepts

Redacted Text: The original input text with PII replaced by anonymized placeholders like <EMAIL_1>.
PII Mapping: A dictionary that maps placeholders to their original values. This allows safe reconstruction of data when authorized.
Consistent Placeholders: When thread_id and space_id are provided, the system reuses existing placeholders across messages in a conversation.
Enhanced Detection: Optional modes like include_business_data or include_oii allow detection of business-specific or other sensitive info (OII).

Endpoints

Detect PII in Text

Use this endpoint to scan and redact PII from any text input.

Endpoint: POST /api-proxy/v1/pii/detect

Headers:

Content-Type: application/json
X-API-Key: <your-api-key>

Example Request:

curl -X POST "https://api.aimable.com/api-proxy/v1/pii/detect" \
  -H "X-API-Key: ak_xxx123xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "My name is John Doe and my email is john.doe@example.com. Call me at (555) 123-4567.",
    "enhanced_mode": true,
    "existing_mapping": {
      "<PHONE_1>": "+15551234567"
    },
    "thread_id": "thread_abc123",
    "space_id": "space_xyz987"
  }'

Example Response (200 OK):

{
  "redacted_text": "My name is <PERSON_1> and my email is <EMAIL_1>. Call me at <PHONE_1>.",
  "pii_mapping": {
    "<PERSON_1>": "John Doe",
    "<EMAIL_1>": "john.doe@example.com"
  },
  "entity_details": {
    "PERSON": ["John Doe"],
    "EMAIL": ["john.doe@example.com"],
    "PHONE": ["(555) 123-4567"]
  }
}

Note: Even though (555) 123-4567 was detected, it reused <PHONE_1> from existing_mapping for consistency.

Get Supported PII Types

Retrieve the full list of supported PII types for validation or UI rendering.

Endpoint: GET /api-proxy/v1/pii/types

Example Request:

curl -X GET "https://api.aimable.com/api-proxy/v1/pii/types" \
  -H "X-API-Key: ak_xxx123xxx"

Example Response (200 OK):

[
  { "id": "PERSON", "label": "Person Name" },
  { "id": "EMAIL", "label": "Email Address" },
  { "id": "PHONE", "label": "Phone Number" },
  { "id": "SSN", "label": "Social Security Number" },
  { "id": "CREDIT_CARD", "label": "Credit Card Number" },
  { "id": "OII", "label": "Other Sensitive Information" }
]

Use this list to validate detected entities or populate dropdowns in your interface.

Common Workflows

1. Real-Time Message Redaction

When processing user messages in a chatbot:

Call POST /api-proxy/v1/pii/detect on each incoming message.
Store the pii_mapping per thread_id and space_id.
Use redacted_text for downstream processing (e.g., LLM prompts).
Reuse existing_mapping in subsequent calls to maintain placeholder consistency.

2. Batch Data Review

For manual review of conversation logs:

Fetch messages from your database.
Send each through POST /api-proxy/v1/pii/detect with enhanced_mode: true.
Present redacted_text to reviewers with an option to reveal PII using pii_mapping if authorized.

Authentication & Error Handling

All endpoints require authentication via the X-API-Key header. Replace <your-api-key> with your actual key.

Common Errors:

401 Unauthorized: Missing or invalid API key.
403 Forbidden: Insufficient permissions.
422 Unprocessable Entity: Invalid request body (e.g., missing text field).

Example 422 response:

{
  "detail": [
    {
      "loc": ["body", "text"],
      "msg": "Field required",
      "type": "missing",
      "input": {}
    }
  ]
}

Always validate your input structure and ensure required fields like text are present.

Use the pii API to build privacy-first applications with consistent, auditable redaction workflows.

POST /v1/pii/detect — Detect Pii Endpoint
GET /v1/pii/types — Get Pii Types Endpoint

PII