Create Screen Analysis Job

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 Get Job 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 Get Job to retrieve status and the result.

Rate Limits

Submit calls are rate-limited per API key. If the caller exceeds the limit, the endpoint responds with 429 rate_limit_exceeded and a Retry-After header indicating the number of seconds to wait before retrying. Use that header to drive client-side backoff; see Errors for the shared error envelope.

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 Get Job 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": "cmdoc_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": 12780,
                "sectionPath": "Electronic Fund Transfers > § 1005.11 > (c)(2)"
              }
            ]
          }
        ]
      }
    ]
  },
  "error": null
}

Screen Analysis Result

For the reusable object reference, see The Screen Analysis Result Object.

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 is a Regulation Citation Object tying a regulation to one or more text excerpts that support the finding.

Field	Type	Description
regulation	Regulation Summary 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	Byte offset of the excerpt within the regulation’s UTF-8 plain text. null when the offset is unavailable.
endOffset	integer or null	End byte offset of the excerpt. null when the offset is unavailable.
sectionPath	string or null	>-delimited breadcrumb showing where the chunk lives within its document (e.g., Electronic Fund Transfers > § 1005.11 > (c)(2)). Falls back to the document title for documents without extractable section structure. null when nothing could be derived.

The excerpt and offsets point into the same UTF-8 plain text served by the Get Regulation Content for the returned regulation.id — same unit, so a citation chunk’s offsets can be passed directly to the Read Content API to fetch a wider context window.

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 Get Job 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.