`get_vouchers`

Read-only

Calls GET /api/vouchers as the signed-in person · REST reference

List vouchers, org-scoped unless the caller is platform staff

Returns a BARE ARRAY, not an envelope — its siblings GET /api/vouchers/batches and GET /api/vouchers/batch-requests answer { data, count } for the same class of thing. Security: a voucher row carries the beneficiary's issuedToEmail, so a caller who is not platform staff sees only rows whose assignedToOrgId or claimedByOrgId is an org in which it holds a voucher feature (hospital.vouchers.transition, hospital.vouchers.redeem, hospital.vouchers.request, hospital.reports.view or distributor.reports.generate). A caller holding a voucher feature in no organization is refused 403 before any DAL call. That boundary is the DAL's orgScope, applied inside the query before SKIP/LIMIT and resolved from the caller's OWN forwarded token against the graph. A full page is therefore a full page: asking for limit rows returns limit of them whenever that many exist within the boundary.

Arguments

Argument	Type	Description
`state`query	string	Exact voucher state to filter on.
`serviceType`query	string
`limit`query	integer	Page size, parsed with parseInt. A non-numeric value reaches the DAL as null, so the DAL's own default page size (20) applies rather than this default.
`offset`query	integer	Same parseInt treatment as `limit`.

Example call

A client sends this over the MCP session; Claude and other agents build it for you. The values are placeholders — the shape is real.

json

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_vouchers",
    "arguments": {}
  }
}

Result

On success (HTTP 200) the tool returns one text item holding the API's JSON, pretty-printed.

The vouchers on this page that the caller may read, as the DAL's ListVouchers selection returns them.

json

[
  {
    "claimAmount": 1,
    "clawbackStatus": "REQUESTED",
    "code": "string",
    "currency": "string",
    "expiresAt": 1,
    "id": "11111111-1111-4111-8111-111111111111",
    "openClawbackStatus": "REQUESTED",
    "printStatus": "NOT_PRINTED",
    "state": "ACTIVE",
    "value": 1,
    "assignedToOrgId": "11111111-1111-4111-8111-111111111111",
    "batchId": "11111111-1111-4111-8111-111111111111",
    "claimedByOrgId": "11111111-1111-4111-8111-111111111111",
    "creditedAmount": 1
  }
]

Fields

Field	Type	Description
`[].assignedToOrgId`	string (uuid) \| null	The org holding the voucher to distribute it — a distributor or the platform.
`[].batchId`	string (uuid) \| null
`[].claimAmount`	integer \| null	The value of the voucher's claim in CENTS — the only money a voucher is shown as worth, derived by the backend (`claimAmount`, backend/src/domain/claimInvoice.ts), not a DAL field. Null until the claim is submitted, and while a CLAIMED voucher's invoice waits on the AI or a reviewer; a CLAIMED voucher's validated covered amount, capped as approval caps it; from APPROVED on, what approval credited (`creditedAmount`). Never the face value (`value`).
`[].claimedByOrgId`	string (uuid) \| null	The clinic that took the voucher at verify; null while no clinic has.
`[].clawbackStatus`	"REQUESTED" \| "APPROVED" \| "EXECUTING" \| "RECOVERED" \| "PARTIALLY_RECOVERED" \| "WRITTEN_OFF" \| … (7 values)	The status of the latest payout clawback against a voucher, resolved ones included — what the voucher's (or its payout's) clawback chip says. Null when there is none. DENIED is never reported, nor a REQUESTED clawback Pawsitive Future filed: until it is approved it is Pawsitive Future's own deliberation.
`[].code`	string
`[].creditedAmount`	integer \| null	CENTS approval credited the claiming clinic; null before approval.
`[].currency`	string
`[].expiresAt`	integer	Epoch MILLISECONDS.
`[].id`	string (uuid)
`[].issuedToEmail`	string \| null	The beneficiary's address — the reason every voucher read is org-scoped.
`[].maxPayout`	integer \| null	The voucher's catalog cap in CENTS; null when it has none and its face value caps it.
`[].openClawbackStatus`	"REQUESTED" \| "APPROVED" \| "EXECUTING" \| "PARTIALLY_RECOVERED" \| "WRITTEN_OFF" \| null	The status of the voucher's open payout clawback, newest first: one being decided or collected, or one closed without all of its cash whose payouts pause has not been lifted. Null when none is — and for any voucher that is not PAID. A REQUESTED clawback Pawsitive Future filed is not reported: until it is approved it is Pawsitive Future's own deliberation.
`[].printStatus`	"NOT_PRINTED" \| "PRINT_FAILED" \| "SUBMITTED"	Whether a printer has this voucher, apart from its lifecycle state. SUBMITTED: a printer accepted a job carrying it; PRINT_FAILED: the last print carrying it failed; NOT_PRINTED: no print has covered it.
`[].procedure`	string \| null
`[].receiptValidatedAmount`	integer \| null	The covered amount the invoice was validated at, in CENTS, before any cap. Null to a reader who does not read the claiming clinic's invoice.
`[].receiptValidationStatus`	string \| null	The invoice check — PENDING, VALID or PENDING_MANUAL_REVIEW; null before an invoice.
`[].replacedByVoucherId`	string (uuid) \| null
`[].replacesVoucherId`	string (uuid) \| null
`[].serviceType`	string \| null
`[].state`	"ACTIVE" \| "APPROVED" \| "ASSIGNED" \| "AVAILABLE" \| "CLAIMED" \| "CREATED" \| … (17 values)	A voucher's lifecycle state, as the DAL's `VoucherState` enum names it.
`[].value`	integer	Face value in CENTS.
`[].workOrderId`	string \| null

When it fails

A failed call returns isError: true with the API's message as text.

400: The request was malformed or failed a guard.
403: The caller is not platform staff and holds a voucher feature in no organization.

What the model is shown

This is the tool exactly as the server lists it in tools/list. The description starts with the REST call it makes.

json

{
  "name": "get_vouchers",
  "description": "GET /api/vouchers — Returns a BARE ARRAY, not an envelope — its siblings `GET /api/vouchers/batches` and `GET /api/vouchers/batch-requests` answer `{ data, count }` for the same class of thing. Security: a voucher row carries the beneficiary's `issuedToEmail`, so a caller who is not platform staff sees only rows whose `assignedToOrgId` or `claimedByOrgId` is an org in which it holds a voucher feature (`hospital.vouchers.transition`, `hospital.vouchers.redeem`, `hospital.vouchers.request`, `hospital.reports.view` or `distributor.reports.generate`). A caller holding a voucher feature in no organization is refused 403 before any DAL call. That boundary is the DAL's `orgScope`, applied inside the query before SKIP/LIMIT and resolved from the caller's OWN forwarded token against the graph. A full page is therefore a full page: asking for `limit` rows returns `limit` of them whenever that many exist within the boundary.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "state": {
        "type": "string",
        "description": "Exact voucher state to filter on."
      },
      "serviceType": {
        "type": "string"
      },
      "limit": {
        "type": "string",
        "description": "Page size, parsed with parseInt. A non-numeric value reaches the DAL as null, so the DAL's own default page size (20) applies rather than this default."
      },
      "offset": {
        "type": "string",
        "description": "Same parseInt treatment as `limit`."
      }
    }
  },
  "annotations": {
    "readOnlyHint": true,
    "openWorldHint": false
  }
}