---
title: "Read an award letter"
method: POST
path: "/v1/tools/awardlens"
---

# Read an award letter

`POST /v1/tools/awardlens`

## Request

- Base URL: `https://api.counselorai.app`
- URL: `https://api.counselorai.app/v1/tools/awardlens`
- Auth: HTTP bearer

Break down one to three financial aid award letters: what is grant, what is loan, what is work-study that has to be earned, what the supported net price is, and what renewal conditions are buried in the language. Identifies missing facts and questions for the aid office. With more than one letter it compares them side by side. Read-only.

## Headers

- `Idempotency-Key` string
- `X-Max-Credits` integer

## Request body

- object
  - `studentName` string: The student this is about. Used in the output text.
  - `letter1` string, required: First award letter, pasted as plain text.
  - `letter2` string: Second award letter, to compare against the first.
  - `letter3` string: Third award letter.
  - `scorecardData` string[]: Optional College Scorecard lines to ground the comparison: acceptance rate, graduation rate, average net price. Include the original Letter number and school/campus; unverified caller-supplied context.

## Response `200`

Tool output

- object
  - `request_id` string
  - `tool` string
  - `output` object
    - `text` string, required: The generated output.
    - `meta` object: Pipeline metadata (pipeline, verify status, fix pass).
    - `verification` object: Whether a model verify pass checked this text, and its verdict.
      - `checked` boolean
      - `method` string, nullable
      - `status` 'PASS' | 'FAIL' | 'null', nullable
      - `score` integer, nullable
      - `fix_applied` boolean, nullable
    - `grounding` object: What the generation was anchored to. fact_sheet is the exact ground truth the verify pass checked dollar figures, names, and dates against; null for tools without a fact-grounded verify pass.
      - `fact_sheet` string, nullable
      - `fields_reflected_in_prompt` string[]
      - `fields_mapped_or_transformed` string[]
      - `fields_not_reflected` string[]
    - `input_fidelity` string: 'strict': this lane never truncates silently; an over-limit input is rejected with a validation error, so the output was built on exactly what was sent.
  - `billing` object
    - `status` 'settled' | 'pending'
    - `credits_charged` integer, nullable
    - `credits_remaining` integer, nullable

## Other responses

- `402`: Insufficient credits or approved spending limit exceeded. Inspect error.code.
- `429`: Rate limited. Retry after the Retry-After header.

---

[API](https://skmtc.dev/counselorai/apis/counselorai-api.md) · [All operations](https://skmtc.dev/counselorai/apis/counselorai-api/llms.txt) · [OpenAPI document](https://skmtc.dev/counselorai/apis/counselorai-api/revisions/1d93eed35463?raw)