Skip to main content

​
Why Custom Patterns?

Standard entities cover names, emails, etc. Custom patterns let you detect org-specific data like employee IDs (EMP-123456), project codes, internal account numbers, or any custom identifier.

​
Request Body

FieldTypeRequiredDescription
namestringYesPattern name (e.g., “EMPLOYEE_ID”)
patternstringYesRegex pattern to match
descriptionstringNoHuman-readable description
examplesarrayNoExample matches for validation

​
Example Request

curl -X POST https://api.ambientmeta.com/v1/patterns \
  -H "X-API-Key: am_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "EMPLOYEE_ID",
    "pattern": "EMP-[0-9]{6}",
    "description": "Internal employee identifier",
    "examples": ["EMP-123456", "EMP-789012"]
  }'

​
Response

FieldTypeDescription
pattern_idstringUnique pattern identifier
namestringPattern name
statusstringPattern status ("active")
analysisobject|nullOverlap and quality analysis (see below)
conflictobject|nullConflict details if overlaps are detected

​
Example Response

{
  "pattern_id": "pat_xyz789",
  "name": "EMPLOYEE_ID",
  "status": "active",
  "analysis": {
    "overlaps_with": [],
    "overlap_count": 0,
    "contradiction_risk": "low",
    "golden_set_coverage": 0,
    "suggested_improvements": []
  },
  "conflict": null
}

​
Response with Conflict

If the new pattern overlaps with existing entity detections, the response includes a conflict block: 
{
  "pattern_id": "pat_abc123",
  "name": "ACCOUNT_NUMBER",
  "status": "active",
  "analysis": {
    "overlaps_with": ["PHONE_NUMBER"],
    "overlap_count": 23,
    "contradiction_risk": "medium",
    "golden_set_coverage": 0,
    "suggested_improvements": []
  },
  "conflict": {
    "has_conflict": true,
    "conflicting_spans": 23,
    "conflicting_type": "PHONE_NUMBER",
    "resolution_required": true,
    "resolution_options": [
      {"option": "reclassify_all", "description": "Reclassify all 23 spans as ACCOUNT_NUMBER"},
      {"option": "add_context_condition", "description": "Add context rule to distinguish"},
      {"option": "refine_pattern", "description": "Narrow the pattern to avoid overlap"}
    ],
    "insight_id": "ins_abc"
  }
}
When a conflict is detected, an insight is automatically created. Use the Insights API to resolve it.

​
Using Custom Patterns

Once created, custom patterns are automatically included in sanitization when config.custom_patterns is set to true in the request body: 
curl -X POST https://api.ambientmeta.com/v1/sanitize \
  -H "X-API-Key: am_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Contact EMP-123456 about the project",
    "config": {"custom_patterns": true}
  }'
Response: 
{
  "sanitized": "Contact [EMPLOYEE_ID_1] about the project",
  "session_id": "ses_...",
  "entities_found": 1
}

​
List Patterns

GET /v1/patterns returns all patterns for your organization.

​
Delete Patterns

DELETE /v1/patterns/{pattern_id} removes a pattern.