> ## Documentation Index
> Fetch the complete documentation index at: https://docs.uselayerup.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Output Schema & Write-Back

> The structured JSON output payload produced by Layerup AI Agents — nine top-level objects, fully machine-readable — and the write-back integration patterns for delivering it to your systems of record.

# 6 — Output schema & write-back — structured payload design & systems-of-record integration.

The Layerup AI Agent produces a fully structured JSON payload upon completion of each case. This payload is the machine-readable representation of every dimension of the agent's analysis — recommendation, confidence, evidence, flags, and open questions. Your downstream systems of record consume this payload via API or direct S3 read, using whichever integration pattern fits your existing architecture.

***

## 6.1  Output payload structure — nine top-level objects

The output JSON payload is designed to be human-reviewable at the operator console and machine-readable at the systems-of-record integration layer simultaneously.

```json theme={null}
{
  "case_metadata": { ... },
  "ai_recommendation": { ... },
  "occupation_analysis": { ... },
  "financial_analysis": { ... },
  "medical_analysis": { ... },
  "requirements": [ ... ],
  "evidence_citations": [ ... ],
  "open_questions": [ ... ],
  "escalation_flag": { ... }
}
```

### `case_metadata`

Traceability envelope for the case. Every field required to reconstruct the agent's state at the time of processing.

| field                   | description                                                                                   |
| ----------------------- | --------------------------------------------------------------------------------------------- |
| `case_id`               | Unique case identifier, correlated with your intake system.                                   |
| `applicant_id`          | Anonymised / pseudonymised applicant identifier as configured.                                |
| `processing_timestamps` | ISO 8601 timestamps for intake, processing start, and completion, with millisecond precision. |
| `agent_version`         | Semantic version of the Layerup agent container image (e.g., `1.4.2`).                        |
| `aop_version`           | Semantic version of the Agent Operating Procedure active at time of processing.               |
| `model_version`         | Model identifier and version for the foundation model invoked, per reasoning step.            |

### `ai_recommendation`

The agent's top-level underwriting recommendation and confidence posture.

| field               | description                                                                                                                                   |
| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `decision`          | One of: `Approve` · `Defer Pending Requirements` · `Decline` · `Escalate to Senior Underwriter`                                               |
| `confidence_score`  | 0–100 integer. Cases below your configured threshold (default: 75) automatically receive `Escalate to Senior Underwriter`.                    |
| `reasoning_summary` | Natural-language summary of the reasoning chain that produced the recommendation. Evidence-grounded and cross-referenced to source documents. |

### `occupation_analysis`

| field                     | description                                                                                             |
| ------------------------- | ------------------------------------------------------------------------------------------------------- |
| `submitted_occupation`    | Occupation as stated by the applicant.                                                                  |
| `resolved_classification` | Resolved occupation class under your classification manual.                                             |
| `mismatch_flags`          | Discrepancies between submitted occupation and evidence in supporting documents, with severity ratings. |
| `duty_mix_breakdown`      | Percentage breakdown of manual, supervisory, and clerical duty components, where determinable.          |
| `occupation_risk_score`   | Relative risk score under your configured occupation class table.                                       |

### `financial_analysis`

| field                             | description                                                                                                                                    |
| --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `income_sources`                  | Extracted income streams with source document citations.                                                                                       |
| `income_quality_score`            | Documentation sufficiency score across all income sources.                                                                                     |
| `documentation_sufficiency_score` | Overall financial documentation adequacy rating.                                                                                               |
| `yoy_trends`                      | Year-over-year income trends where multi-year documentation is available.                                                                      |
| `financial_flags`                 | Specific financial anomalies with severity scores (e.g., implausible YTD amounts, missing documentation, inconsistent income representations). |

### `medical_analysis`

| field                     | description                                                                                                       |
| ------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| `medical_history_summary` | Evidence-grounded narrative summary of the applicant's medical history as extracted from all available documents. |
| `risk_drivers`            | Identified medical underwriting risk drivers with severity ratings (Low · Moderate · High).                       |
| `identified_medications`  | Medication list extracted from Rx history and APS documents.                                                      |
| `flagged_inconsistencies` | Conflicts or anomalies across medical documents with severity scores.                                             |
| `missing_records`         | Records expected under the AOP configuration but not found in the submitted document set.                         |

### `requirements`

Ordered list of requirements the agent determines cannot be waived given available documentation. Each requirement object contains:

* The specific requirement (e.g., "Attending Physician Statement from treating cardiologist").
* The agent's evidence-grounded reasoning for why it is required.
* A suggested due date, if applicable under your AOP configuration.

### `evidence_citations`

For every extracted data point and every flag raised, a structured citation object references the source with precision:

| field             | description                                                        |
| ----------------- | ------------------------------------------------------------------ |
| `source_document` | Document filename as received in the intake packet.                |
| `page_number`     | Page number within the document.                                   |
| `section`         | Section or region identifier within the page.                      |
| `extracted_text`  | Verbatim extracted text snippet supporting the data point or flag. |
| `ocr_confidence`  | OCR confidence score for this extraction, where applicable.        |

<Note>
  Evidence citations are attached to every data point — not just flags. This means your underwriting team can trace any value in the recommendation back to the exact text in the exact page of the exact document from which it was extracted.
</Note>

### `open_questions`

Natural-language list of questions the agent determines remain unanswered after reviewing all available documents. Each open question is grounded in a specific evidence gap — the agent does not generate speculative questions beyond what the document set and AOP configuration define as required.

### `escalation_flag`

| field                | description                                                                                                                          |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `escalated`          | Boolean. `true` if the agent is routing the case to senior underwriter review.                                                       |
| `escalation_reasons` | Structured list of specific reasons (low confidence · critical extraction failure · edge case outside AOP · specific rule triggers). |
| `escalation_routing` | Queue or routing target for the escalated case, as configured in the AOP.                                                            |

***

## 6.2  Write-back integration patterns

Your IT team integrates the agent's output payload using whichever of the following patterns fits your existing system architecture. The agent supports all three simultaneously — you select the appropriate pattern per downstream consumer.

<CardGroup cols={2}>
  <Card title="S3 Drop + Lambda Consumer" icon="aws">
    The agent writes the output JSON to a designated S3 output prefix. An S3 event trigger invokes a Lambda function that reads the payload and updates your policy administration system or CRM via its internal API. Recommended for teams already using event-driven Lambda patterns for system-of-record updates.
  </Card>

  <Card title="Direct API Callback" icon="webhook">
    The agent POSTs the completed output payload to a designated internal HTTPS endpoint (e.g., your internal microservice endpoint within the VPC) upon case completion. The endpoint must be within the VPC and reachable without public internet routing. Recommended for synchronous CRM integration patterns.
  </Card>

  <Card title="Queue-Based Handoff" icon="layer-group">
    The agent writes a completion notification to an SQS queue (AWS) or Service Bus topic (Azure), allowing your downstream system to poll and consume at its own pace. Recommended for downstream systems with their own processing schedules or rate limits.
  </Card>

  <Card title="Direct S3 Read" icon="database">
    Your downstream system reads the output JSON directly from the designated S3 output prefix on a schedule or in response to the SQS completion notification. Simplest integration pattern for systems that already have S3 read capabilities.
  </Card>
</CardGroup>

```mermaid theme={null}
flowchart LR
  AGT[Agent Container] --> PAYLOAD[Output JSON Payload<br/>Structured + evidence-cited]
  PAYLOAD --> S3OUT[S3 Output Bucket]
  S3OUT -->|S3 event| LMB[Lambda Consumer<br/>→ Policy Admin API]
  S3OUT -->|direct read| SOR1[Policy Admin System]
  AGT -->|POST callback| SVC[Internal Microservice<br/>within VPC]
  AGT -->|completion event| SQS[SQS / Service Bus<br/>Completion Queue]
  SQS --> SOR2[CRM / DMS]

  classDef out fill:#f4f4f2,stroke:#111,color:#111;
  class PAYLOAD,S3OUT out;
```

*Fig. A6.1 — Write-back integration patterns. All patterns route output exclusively within your VPC boundary. No output copy is sent to Layerup's infrastructure.*