Pawsitive Future Pawsitive FutureDeveloper docs

post_vouchers_batch_requests

Changes data · you confirm first

Calls POST /api/vouchers/batch-requests as the signed-in person · REST reference

Ask PFF for a batch of vouchers

Files a request as a batch held in the REQUESTED status. Reserves NO voucher-pool budget — the pool gate runs when PFF decides, so an affordable request can stop being affordable before it is reviewed. The requesting org must be one in which the caller holds execute:RequestVoucherBatchCommand — never merely one it belongs to. A body orgId naming any other org answers 403; with no orgId, the one org where the caller holds it is used, and a caller holding it in more than one must name which (400). A caller holding a platform voucher permission (staff have no org of their own to request for) is not held to its own orgs: its orgId is used as sent; with none named its first membership is used, and with no membership either the answer is 400.

Arguments

ArgumentTypeDescription
bodyJSONobjectrequiredThe request body, as a JSON object. Its fields are listed below.

Fields of body

FieldTypeDescription
justificationstringFree-text rationale shown to the PFF reviewer.
neededByinteger | stringEpoch MILLISECONDS or a Date.parse-able string. Omitted leaves it unset; an unparseable string becomes 180 days from now rather than an error.
orgIdstring (uuid)Requesting org. Must be one where the caller holds execute:RequestVoucherBatchCommand (else 403), unless the caller holds a platform voucher permission. Required when the caller holds that permission in more than one org.
procedurestring
quantityintegerrequiredVouchers asked for. Outside 1..10000 answers 400.
serviceTypestring | null
sexstring
speciesstring
type"DIGITAL" | "PHYSICAL"Anything but the literal PHYSICAL is treated as DIGITAL.

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": "post_vouchers_batch_requests",
    "arguments": {
      "body": {
        "quantity": 1,
        "justification": "string",
        "neededBy": 1,
        "orgId": "11111111-1111-4111-8111-111111111111",
        "procedure": "string",
        "serviceType": "string",
        "sex": "string",
        "species": "string",
        "type": "DIGITAL"
      }
    }
  }
}
Confirmation
The client shows the person the exact request and waits. Nothing runs until they tick Make this change. See Reading and changing.

Result

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

The request was filed. Nothing is minted and no budget is held.

json
{
  "batchId": "11111111-1111-4111-8111-111111111111",
  "batchNumber": "string",
  "estimatedValue": 1,
  "quantity": 1,
  "status": "REQUESTED",
  "orgId": "11111111-1111-4111-8111-111111111111"
}

Fields

FieldTypeDescription
batchIdstring (uuid)
batchNumberstring
estimatedValueintegerEstimated total face value in CENTS if approved in full. An estimate only — the value is fixed when PFF approves.
orgIdstring (uuid) | nullThe batch's assignedTo — the org the request was actually filed for.
quantityinteger
status"REQUESTED"

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.

400

The request was malformed or failed a guard.

403

Authenticated, but the caller holds none of the required permissions.

404

No such resource — or none this caller may see.

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": "post_vouchers_batch_requests",
  "description": "POST /api/vouchers/batch-requests — Files a request as a batch held in the REQUESTED status. Reserves NO voucher-pool budget — the pool gate runs when PFF decides, so an affordable request can stop being affordable before it is reviewed. The requesting org must be one in which the caller holds `execute:RequestVoucherBatchCommand` — never merely one it belongs to. A body `orgId` naming any other org answers 403; with no `orgId`, the one org where the caller holds it is used, and a caller holding it in more than one must name which (400). A caller holding a platform voucher permission (staff have no org of their own to request for) is not held to its own orgs: its `orgId` is used as sent; with none named its first membership is used, and with no membership either the answer is 400.\n\nThis changes data. The person is asked to confirm it before it runs, and nothing happens if they decline.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "body": {
        "type": "string",
        "description": "The JSON request body: { justification: string (Free-text rationale shown to the PFF reviewer.); neededBy: integer or string (Epoch MILLISECONDS or a Date.parse-able string.); orgId: string (Requesting org.); procedure: string; quantity*: integer (Vouchers asked for.); serviceType: string; sex: string; species: string; type: one of \"DIGITAL\" | \"PHYSICAL\" (Anything but the literal `PHYSICAL` is treated as `DIGITAL`.) }"
      }
    },
    "required": [
      "body"
    ]
  },
  "annotations": {
    "readOnlyHint": false,
    "destructiveHint": true,
    "idempotentHint": false,
    "openWorldHint": false
  }
}