--- title: "Retrieve benefit letter" method: GET path: "/v1/links/{link_id}/benefit_letters/{benefit_letter_id}/" tags: ["Benefit Letters"] --- # Retrieve benefit letter `GET /v1/links/{link_id}/benefit_letters/{benefit_letter_id}/` ## Request - Base URL: `https://prod.truv.com` - URL: `https://prod.truv.com/v1/links/{link_id}/benefit_letters/{benefit_letter_id}/` - Auth: API key in header `X-Access-Client-Id` and API key in header `X-Access-Secret` The endpoint returns a benefit letter with the values read from it in `fields`. `document_type` says which shape `fields` has; for `VA_BENEFIT_LETTER`, the only type returned today, it carries the combined evaluation, the effective date of the award, and the gross and net monthly benefit amounts. Every field is read from the letter and is never derived. The VA combines rated conditions with its own table and rounds to the nearest ten (38 CFR 4.25), so individual ratings do not add up to `combined_evaluation`, and the letter prints only the combined figure. A field is `null` when the letter did not state that line. `0` and `"0.00"` are real values and are returned as such, so an absent line is always distinguishable from a zero one. The rating and the amounts are independent: a benefit can be waived, offset against military retired pay, apportioned or withheld, so a veteran at 100 percent can be paid 0.00. The letter prints no deduction lines, so a difference between `gross_benefit_amount` and `net_amount_paid` is reported but never explained. Both amounts are monthly and in US dollars. The letter states neither — VA disability compensation is paid monthly in US dollars for every letter — so the response carries no currency and no cadence field. ## Response `200` - BenefitLetterRetrieve: A benefit letter of a link. `document_type` says which letter it is and which shape its `fields` take on retrieve. - `id` string: Benefit letter ID - `document_type` 'VA_BENEFIT_LETTER' | 'SSA_BENEFIT_LETTER': Benefit letter type. It decides the shape of `fields` on retrieve. `VA_BENEFIT_LETTER` is the VA Benefit Verification letter, whose fields are described by `VaBenefitLetterFields`. `SSA_BENEFIT_LETTER` is reserved for the Social Security benefit letter; none are returned yet, and its `fields` will be documented when they are. - `file` string, uri, nullable: Link to the file the letter was read from - `md5sum` string, nullable: MD5 checksum of the file - `created_at` string, date-time: Time the letter was first read - `updated_at` string, date-time: Time the values read from the letter last changed - `fields` VaBenefitLetterFields: Disability benefit details read from the veteran's VA Benefit Verification letter. Each field carries one line of the letter; a line the letter did not state is `null`. - `combined_evaluation` integer, nullable: Combined disability evaluation, as a whole-number percentage. `0` is a valid evaluation — a service-connected condition can be evaluated at 0 percent — so a missing line is returned as `null`, never as `0`. Read from the letter, never derived: the VA combines rated conditions with its own table (38 CFR 4.25) and prints only the combined figure. A percentage alone does not settle eligibility: under 38 CFR 4.16(a) a veteran below 100 percent can still be rated totally disabled, which turns on the individual ratings — a single disability at 60 percent or more, or one at 40 percent or more with a combined 70 percent or more — and on a rating-agency finding of unemployability. The letter prints none of that. - `effective_date` string, date, nullable: Date the award took effect. This is not the date the letter was issued, and an evaluation does not expire, so this is the only field that says how current the evaluation is. - `gross_benefit_amount` string, decimal, nullable: Gross benefit amount, as the letter prints it under Gross Benefit Amount. `"0.00"` is a real amount, so a missing line is returned as `null`. - `net_amount_paid` string, decimal, nullable: Net amount paid to the veteran, as the letter prints it under Net Amount Paid. Can be lower than `gross_benefit_amount`; the letter prints no deduction lines, so the difference is reported and not explained. `"0.00"` is a real amount — benefits get waived, offset against military retired pay, apportioned or withheld while the evaluation stands — so a missing line is returned as `null`. ## Other responses - `401`: HTTP 401 Unauthorized - `403`: HTTP 403 Forbidden - `404`: HTTP 404 Not Found. The link does not exist, or it holds no benefit letter with this ID. ## Changes - **2026-10-02** `38a16006d88a`: 1 info - endpoint added [Operation history](https://skmtc.dev/truv/apis/truv-api/changes/v1/links/:link_id/benefit_letters/:benefit_letter_id/get.md) --- [API](https://skmtc.dev/truv/apis/truv-api.md) - [All operations](https://skmtc.dev/truv/apis/truv-api/llms.txt) - [OpenAPI document](https://skmtc.dev/truv/apis/truv-api/revisions/e20fd88e9371?raw)