Integration best practices

This page provides best practices for integrating with the Documents API, focusing on resilience, security, and graceful handling of API evolution.

Handling API evolution gracefully

The Documents API evolves continuously to support new document types, detection capabilities, and customer requirements. Integrations should handle changes gracefully without breaking.

New enum values may appear without notice

Adding new enum values is not considered a breaking change. New values may be introduced at any time without prior notice or version bumps.

Enum fields that may expand:

score values (e.g., new fraud risk levels beyond NORMAL, TRUSTED, WARNING, HIGH_RISK)
status values (e.g., new terminal or intermediate statuses)
indicator.type values (new indicator types beyond RISK, TRUST, INFO)
metadata.type values (new visualization formats beyond DataOnly, ElementsCollection, Combining)
Document tags (new classification tags)

New API fields may appear without notice

Adding new response fields is not considered a breaking change. New fields may be introduced at any time.

Your integration should:

Ignore unknown fields — do not fail on unexpected JSON keys
Use permissive JSON parsing — most modern libraries ignore extra fields by default
Avoid strict schema validation in production — use it in tests, but allow unknown fields in prod

Example (Python):

# Bad: strict dataclass fails on new fields
@dataclass
class FraudResult:
    status: str
    score: str
    indicators: list
    # No __post_init__ to ignore extras → breaks on new field

# Good: ignores unknown fields
fraud_result = response.json()
status = fraud_result.get("status")
score = fraud_result.get("score")
indicators = fraud_result.get("indicators", [])
# Unknown fields are silently ignored

Always use `metadata.type` to determine visualization format

Do not hardcode which indicators have which metadata types. The metadata format for a given indicator can change over time as detection capabilities improve.

Indicator metadata types can evolve:

An indicator that was DataOnly (no visualization) may become Combining (structured tables) in a future release
An ElementsCollection indicator may gain additional element types
New metadata types may be introduced

Recommended approach: Always read metadata.type from the response and switch on that value:

for indicator in indicators:
    metadata = indicator.get("metadata", {})
    if not metadata:
        render_text_only(indicator.get("title", "Unknown indicator"))
        continue
    
    metadata_type = metadata.get("type")
    
    if metadata_type == "Combining":
        render_combining_table(metadata)
    elif metadata_type == "ElementsCollection":
        render_elements_collection(metadata)
    elif metadata_type == "DataOnly":
        render_data_table(metadata)
    else:
        # Unknown type → fallback to text-only
        render_text_only(indicator.get("title", "Unknown indicator"))

Do not do this:

# Bad: hardcoded mapping breaks when metadata.type changes
INDICATOR_METADATA_MAP = {
    "in_transaction_cluster": "Combining",
    "in_font_inconsistency": "ElementsCollection",
    # ... hardcoded for all indicators
}

# This breaks when we change an indicator's metadata.type

Use `metadata.title` for table headers

The metadata.title field (introduced in recent releases) provides a human-readable title for indicator metadata tables. Rules:

If metadata.title is present, display it as the table heading
If metadata.title is absent, do not display a table heading
metadata.title is optional and may be null or missing

Example:

metadata = indicator.get("metadata", {})
title = metadata.get("title")

if title:
    print(f"### {title}")

render_table_rows(metadata.get("rows", []))

Format back-ticked text as monospace code

When rendering metadata elements that contain text fields (e.g., BBoxWithOldAndNewText elements with original_text and new_text), text wrapped in backticks (text) should be formatted as monospace code. Example:

This improves readability for technical fields (e.g., font names, metadata fields, encoded values).

Do not hardcode indicator IDs or indicator names

Indicator IDs and names evolve over time. Resistant AI continuously adds, deprecates, and improves indicators as detection capabilities advance.

Your integration should:

Never hardcode indicator IDs (e.g., in_transaction_cluster, in_font_inconsistency) in business logic
Never build conditional logic around specific indicator names (e.g., “if indicator ID contains X, then do Y”)
Use indicator properties dynamically — rely on type, score, severity, or metadata.type instead

Why this matters:

Indicators may be split, merged, or renamed as detection models improve
New indicators are added regularly
Deprecated indicators may be removed or replaced

If you need indicator-specific handling, contact Resistant AI support to discuss stable integration points.

Consider using Web UI or iFrame viewer for visualization

If building a custom UI for fraud indicators is not a core requirement, consider:

Web UI — let users view results in the hosted Web UI (no custom UI needed)
iFrame viewer — embed Resistant AI’s viewer in your application

Benefits:

No custom parsing or rendering logic
Automatic support for new metadata types
Consistent user experience
Reduced maintenance burden

See:

If you only need to display fraud results occasionally (e.g., for manual review), linking to the Web UI or embedding the iFrame is often simpler than building a custom renderer.

Fetching fraud results

Use `with_metadata` parameter appropriately

The GET /v2/submission/{submission_id}/fraud endpoint accepts an optional with_metadata query parameter (defaults to false). When to use with_metadata=true:

You are displaying indicator details in a custom UI
You need structured metadata for rendering tables, charts, or visualizations
You are building a manual review interface with detailed fraud evidence

When to omit it (default false):

You only need the overall score or decision for routing
You are auto-approving/declining based on score alone
You want faster response times and smaller payloads

Performance impact: Responses with with_metadata=true are larger and may take slightly longer to return. If you only need the fraud score or decision, omit the parameter to optimize performance. Example:

# Minimal response (score + decision only)
GET /v2/submission/{submission_id}/fraud

# Full response with indicator metadata
GET /v2/submission/{submission_id}/fraud?with_metadata=true

Handling missing or null fields

Not all fields in the fraud result response are guaranteed to be present. Your integration should handle missing or null values gracefully. Fields that may be missing or null:

Field	When missing or `null`
`decision`	Adaptive Decision not enabled for tenant, or `enable_decision: false` in submission request
`query_id`	Not provided in the original submission request
`indicators`	May be an empty array for certain document types, or if analysis fails
`metadata`	Only present if `with_metadata=true` in the request
`metadata.title`	Optional field; may be `null` or missing even when metadata is present

Getting started

Integrate

Receiving results

View results in Resistant UI

Operations & Support

Integration best practices

Handling API evolution gracefully

New enum values may appear without notice

New API fields may appear without notice

Always use `metadata.type` to determine visualization format

Use `metadata.title` for table headers

Format back-ticked text as monospace code

Do not hardcode indicator IDs or indicator names

Consider using Web UI or iFrame viewer for visualization

Fetching fraud results

Use `with_metadata` parameter appropriately

Handling missing or null fields

​Handling API evolution gracefully

​New enum values may appear without notice

​New API fields may appear without notice

​Always use metadata.type to determine visualization format

​Use metadata.title for table headers

​Format back-ticked text as monospace code

​Do not hardcode indicator IDs or indicator names

​Consider using Web UI or iFrame viewer for visualization

​Fetching fraud results

​Use with_metadata parameter appropriately

​Handling missing or null fields

Handling API evolution gracefully

New enum values may appear without notice

New API fields may appear without notice

Always use `metadata.type` to determine visualization format

Use `metadata.title` for table headers

Format back-ticked text as monospace code

Do not hardcode indicator IDs or indicator names

Consider using Web UI or iFrame viewer for visualization

Fetching fraud results

Use `with_metadata` parameter appropriately

Handling missing or null fields