post_vouchers_by_id_claim
Calls POST /api/vouchers/{id}/claim as the signed-in person · REST reference
Claim step 3 — submit the claim
Transitions PERFORMED_PENDING_CLAIM → CLAIMED, which places the voucher in the PFF approval queue. A work-order id is mandatory here (the "no work order, no claim" guarantee), and so is the invoice: the PDF of the work done must already be STORED (POST /api/vouchers/{id}/receipt), else 409 — a claim reaches PFF only with the document it is paid on. The acting clinic is the one that took the voucher (claimedByOrgId); a body orgId is not read, any other clinic is refused with 403, and the DAL write refuses a clinic that is not that one. Requires execute:RedeemVoucherCommand (hospital.vouchers.redeem) IN that clinic — the person who submits a claim may be a different person from the one who verifies at the front desk — and runs as the caller at the DAL. Answers 201, unlike the other two claim steps which answer 200, although it creates no new resource and returns no Location header.
Arguments
| Argument | Type | Description | |
|---|---|---|---|
idpath | string (uuid) | required | Voucher id. |
bodyJSON | object | required | The request body, as a JSON object. Its fields are listed below. |
Fields of body
| Field | Type | Description | |
|---|---|---|---|
notes | string | Accepted and forwarded to the service, which DISCARDS it — no notes field is persisted by this step. | |
procedure | string | Optional here; OVERWRITES the procedure recorded at step 2 when supplied. | |
workOrderId | string | required | The clinic's work-order reference. Missing or empty answers 400. |
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.
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "post_vouchers_by_id_claim",
"arguments": {
"id": "11111111-1111-4111-8111-111111111111",
"body": {
"workOrderId": "string",
"notes": "string",
"procedure": "string"
}
}
}
}Result
On success (HTTP 201) the tool returns one text item holding the API's JSON, pretty-printed.
The voucher after the transition, as the DAL's TransitionVoucher selection returns it.
{
"code": "string",
"currency": "string",
"expiresAt": 1,
"id": "11111111-1111-4111-8111-111111111111",
"state": "ACTIVE",
"value": 1,
"assignedToOrgId": "11111111-1111-4111-8111-111111111111",
"batchId": "11111111-1111-4111-8111-111111111111",
"issuedAt": 1,
"issuedToEmail": "string",
"issuedToPhone": "string",
"maxPayout": 1,
"procedure": "string",
"replacedByVoucherId": "11111111-1111-4111-8111-111111111111"
}Fields
| Field | Type | Description |
|---|---|---|
assignedToOrgId | string (uuid) | null | |
batchId | string (uuid) | null | |
code | string | |
currency | string | |
expiresAt | integer | Epoch MILLISECONDS. |
id | string (uuid) | |
issuedAt | integer | null | Epoch MILLISECONDS. |
issuedToEmail | string | null | |
issuedToPhone | string | null | |
maxPayout | integer | null | Catalog face-value cap in CENTS. |
procedure | string | null | |
replacedByVoucherId | string (uuid) | null | The voucher the DAL minted to replace this one in its batch, if any. |
serviceType | string | null | |
species | 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. |
voidReason | string | null |
When it fails
A failed call returns isError: true with the API's message as text. A change the person declines, or lets time out, also comes back this way and nothing changes.
400The request was malformed or failed a guard.
403Authenticated, but the caller holds none of the required permissions.
404No such resource — or none this caller may see.
409The resource is not in a state that allows this operation.
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.
{
"name": "post_vouchers_by_id_claim",
"description": "POST /api/vouchers/{id}/claim — Transitions PERFORMED_PENDING_CLAIM → CLAIMED, which places the voucher in the PFF approval queue. A work-order id is mandatory here (the \"no work order, no claim\" guarantee), and so is the invoice: the PDF of the work done must already be STORED (`POST /api/vouchers/{id}/receipt`), else 409 — a claim reaches PFF only with the document it is paid on. The acting clinic is the one that took the voucher (`claimedByOrgId`); a body `orgId` is not read, any other clinic is refused with 403, and the DAL write refuses a clinic that is not that one. Requires `execute:RedeemVoucherCommand` (`hospital.vouchers.redeem`) IN that clinic — the person who submits a claim may be a different person from the one who verifies at the front desk — and runs as the caller at the DAL. Answers 201, unlike the other two claim steps which answer 200, although it creates no new resource and returns no Location header.\n\nThis changes data. The person is asked to confirm it before it runs, and nothing happens if they decline.",
"inputSchema": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Voucher id."
},
"body": {
"type": "string",
"description": "The JSON request body: { notes: string (Accepted and forwarded to the service, which DISCARDS it — no notes field is persisted ...); procedure: string (Optional here; OVERWRITES the procedure recorded at step 2 when supplied.); workOrderId*: string (The clinic's work-order reference.) }"
}
},
"required": [
"id",
"body"
]
},
"annotations": {
"readOnlyHint": false,
"destructiveHint": true,
"idempotentHint": false,
"openWorldHint": false
}
}