Screen Analysis API

POST /api/v1/analysis/screen

Submits a compliance-screening job for a blob of text. Use this for customer messages, agent responses, generated documents, marketing copy, or other text that needs compliance review before it is shown, sent, or approved.

Screen Analysis is asynchronous because the work may require agentic, multi-step analysis and can take time. The submit endpoint returns a job id; retrieve the job through the Jobs API to check status and read the result when it is ready.

Submit a Screening Job

Request Body

{
  "content": {
    "type": "text",
    "text": "we can't provide a provisional dispute credit until the investigation is completed"
  },
  "scenario": "dispute"
}

Fields

Name	Type	Required	Description
content.type	string	yes	Content type. v1 supports text.
content.text	string	yes	Text to screen for compliance risk. Min 1 character.
scenario	string	yes	One of the scenario enum values below. Selects the screening context the backend uses.

Note

The request uses content rather than a bare text field so future analysis inputs can add document metadata without changing the endpoint shape.

Scenario Enum

scenario is required and selects which specialized screening context the backend applies. Pick the value that describes the purpose of the text being screened, not the channel it came from. The categories are mutually exclusive by purpose.

Value	Use for
marketing_asset	Outbound promotional content — ads, prescreened offers, marketing emails, landing-page copy
dispute	Transaction or billing error handling — Reg E / Reg Z error-resolution letters, dispute responses
debt_collection	Collections communications — demand letters, collector scripts, dunning emails
complaint	Responses to consumer complaints filed with the institution, a regulator, or the CFPB portal
generic	Anything that does not fit a specialized bucket above — servicing replies, account disclosures, FAQs, adverse-action notices, internal content

When in doubt between a specialized value and generic, pick the specialized value only if the text clearly serves that purpose end-to-end. Mixed content with a dominant purpose should carry that purpose; truly mixed or neutral content goes to generic.

Response

Returns 202 Accepted with the job id:

{
  "id": "job_01HY3K4M7QR9VP2N8WYJF5GTB"
}

Use id with the Jobs API to retrieve status and the result.

Retrieve a Screening Job

GET /api/v1/jobs/{id}

Returns the current job status and, when status is succeeded, the screening result. Documented in full on the Jobs API page.

Succeeded Response

{
  "id": "job_01HY3K4M7QR9VP2N8WYJF5GTB",
  "type": "screen_analysis",
  "status": "succeeded",
  "createdAt": "2026-04-15T12:00:00Z",
  "updatedAt": "2026-04-15T12:00:12Z",
  "result": {
    "type": "analysis.screen.result",
    "riskScore": 75,
    "findings": [
      {
        "priority": "p1",
        "title": "Missing provisional credit disclosure",
        "details": "The content states that provisional credit cannot be provided until the investigation is completed. Under Regulation E, financial institutions must provisionally credit the consumer's account within 10 business days of receiving a notice of error.",
        "citations": [
          {
            "regulation": {
              "id": "01HXZ3K4M7QR9VP2N8WYJF5GTB",
              "category": "regulation",
              "title": "Electronic Fund Transfers",
              "authorities": ["cfpb"],
              "jurisdictions": ["us-federal"],
              "description": "Regulation E error-resolution requirements for financial institutions, including investigation timelines and provisional credit obligations.",
              "updatedAt": "2026-04-09T00:00:00Z",
              "sourceUrl": "https://www.ecfr.gov/current/title-12/chapter-X/part-1005/section-1005.11"
            },
            "chunks": [
              {
                "text": "If the financial institution is unable to complete its investigation within 10 business days...",
                "startOffset": 12450,
                "endOffset": null
              }
            ]
          }
        ]
      }
    ]
  },
  "error": null
}

Screen Analysis Result

The result payload on a succeeded screening job contains a type discriminator, an overall risk score, and a list of findings, each backed by regulatory citations.

Field	Type	Description
type	string	Result type discriminator. Always analysis.screen.result for screen-analysis jobs.
riskScore	integer	Overall compliance risk score (0–100). 0–20: Limited. 21–40: Low. 41–60: Moderate. 61–80: High. 81–100: Critical.
findings	Finding[]	List of compliance findings, ordered by severity. May be empty when riskScore is low.

Finding

Each finding is a discrete compliance observation with supporting citations.

Field	Type	Description
priority	string	Severity level. p1: Blocking — high-confidence, high-severity; content should not be used as written. p2: Material — credible concern requiring review and likely revision. p3: Advisory — lower-severity issue or drafting improvement.
title	string	Concise name of the compliance finding
details	string	Explanation of the compliance concern, how it relates to the applicable regulation, and the risk it presents
citations	Citation[]	Regulatory citations that support this finding

Citation

Each citation ties a regulation to one or more text excerpts that support the finding.

Field	Type	Description
regulation	Regulation Object	Document-level provenance for the cited regulation
chunks	CitationChunk[]	Text excerpts from this regulation that support the finding

Citation Chunk

Each chunk is a text excerpt from the cited regulation.

Field	Type	Description
text	string	Raw text of the regulatory excerpt
startOffset	integer or null	Character offset of the excerpt within the regulation’s plain text. null when the offset is unavailable.
endOffset	integer or null	End character offset of the excerpt. null when the offset is unavailable.

The excerpt and offsets point into the same plain text served by the Read Regulation Content API for the returned regulation.id.

Job Lifecycle

• status: "running" — result and error are both null
• status: "succeeded" — result is populated, error is null
• status: "failed" — result is null, error is { code, message }

See the Jobs API for the full envelope and error shape.

Non-goals

Screen Analysis does not edit or rewrite the submitted text. It does not return redline diffs, replacement copy, workflow routing, or remediation actions in v1. Those can be added later as separate Analysis jobs, for example under /api/v1/analysis/redline.