post_vouchers_by_id_perform
Calls POST /api/vouchers/{id}/perform as the signed-in person · REST reference
Claim step 2 — mark the procedure performed
Transitions VERIFIED → PERFORMED_PENDING_CLAIM and records the procedure and work order. As with every claim step after verify, 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 a voucher no clinic has taken with 409. Requires execute:TransitionVoucherCommand IN that clinic, and runs as the caller at the DAL — see verify.
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 | required | What was done. Missing or empty answers 400. |
workOrderId | string | The clinic's own work-order reference. Optional here; required at step 3. |
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_perform",
"arguments": {
"id": "11111111-1111-4111-8111-111111111111",
"body": {
"procedure": "string",
"notes": "string",
"workOrderId": "string"
}
}
}
}Result
On success (HTTP 200) 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_perform",
"description": "POST /api/vouchers/{id}/perform — Transitions VERIFIED → PERFORMED_PENDING_CLAIM and records the procedure and work order. As with every claim step after verify, 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 a voucher no clinic has taken with 409. Requires `execute:TransitionVoucherCommand` IN that clinic, and runs as the caller at the DAL — see verify.\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 (What was done.); workOrderId: string (The clinic's own work-order reference.) }"
}
},
"required": [
"id",
"body"
]
},
"annotations": {
"readOnlyHint": false,
"destructiveHint": true,
"idempotentHint": false,
"openWorldHint": false
}
}