MCP reference / Billing

Billing and invoice tools

Six tools covering the ledger of billable entries and the invoices issued from it. Voiding is a reversal that stays on the ledger, not a delete.

How to read this

Each tool below lists its arguments exactly as the input schema declares them — the type, whether it is required, and the permitted values where the schema fixes them. There are no argument descriptions: the schemas carry types, not prose, and inventing a sentence per argument would be writing fiction about a contract.

practiceId is never an argument. It comes from your token, and the write paths strip it if a client sends one anyway.

Every example is a complete tools/call request with this tool's required arguments filled in. Errors are returned inside a 200 response with isError set — see the MCP overview for that envelope, and the full catalogue for every tool at a glance.

Billing and invoices

The ledger of billable entries, and the invoices issued from it.

list_billing_entries

Read-onlyOwner only

List billing entries across the whole practice, optionally bounded by a date range (the practice's own days, both included). Use list_patient_billing_entries for one patient, and for what a patient owes.

Arguments

Tool	Type	Required?
from	string	Optional
to	string	Optional

Example call

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

Result

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "structuredContent": {
      "status": 200,
      "ok": true,
      "data": { "...": "the requested records" }
    }
  }
}

Errors

Code	Status	When
validation_failed	400	An argument is missing, of the wrong type, or outside its allowed values.
forbidden	403	The caller is not an owner of the practice.
unauthorized	401	The bearer token is missing, invalid or expired.

get_billing_entry

Read-onlyAny member

Read a single billing entry by id.

Arguments

Tool	Type	Required?
entryId	string	Required

Example call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_billing_entry",
    "arguments": {
      "entryId": "0f1c7a2e-...."
    }
  }
}

Result

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "structuredContent": {
      "status": 200,
      "ok": true,
      "data": { "...": "the requested records" }
    }
  }
}

Errors

Code	Status	When
validation_failed	400	An argument is missing, of the wrong type, or outside its allowed values.
not_found	404	The id does not exist in your practice. A malformed id looks identical.
unauthorized	401	The bearer token is missing, invalid or expired.

get_invoice

Read-onlyAny member

Read an issued invoice and its frozen line items. Use get_patient_invoice_preview for the unissued draft.

Arguments

Tool	Type	Required?
invoiceId	string	Required

Example call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_invoice",
    "arguments": {
      "invoiceId": "0f1c7a2e-...."
    }
  }
}

Result

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "structuredContent": {
      "status": 200,
      "ok": true,
      "data": { "...": "the requested records" }
    }
  }
}

Errors

Code	Status	When
validation_failed	400	An argument is missing, of the wrong type, or outside its allowed values.
not_found	404	The id does not exist in your practice. A malformed id looks identical.
unauthorized	401	The bearer token is missing, invalid or expired.

get_appointment_charge

Read-onlyAny member

Read what charging an appointment would take: whether it can be charged, and the catalog service matching it, with its id and price. Use it before charging an appointment with write_billing_entry.

Arguments

Tool	Type	Required?
appointmentId	string	Required

Example call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_appointment_charge",
    "arguments": {
      "appointmentId": "0f1c7a2e-...."
    }
  }
}

Result

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "structuredContent": {
      "status": 200,
      "ok": true,
      "data": { "...": "the requested records" }
    }
  }
}

Errors

Code	Status	When
validation_failed	400	An argument is missing, of the wrong type, or outside its allowed values.
not_found	404	The id does not exist in your practice. A malformed id looks identical.
unauthorized	401	The bearer token is missing, invalid or expired.

write_billing_entry

WritesCan deleteAny member

Create, update or void a billing entry. action=create requires patientId; update and void require entryId. Voiding is a reversal, not a delete — the entry stays on the ledger marked void. A receipt entry records a payment and gets a payment number (HCRM-0001); it is not a document. Receipts and tax invoices are issued with write_invoice.

Arguments

Tool	Type	Required?
action	create \| update \| void	Required
entryId	string	Optional
patientId	string	Optional
type	charge \| credit \| receipt	Optional
amountMinor	integer	Optional
serviceId	string	Optional
appointmentId	string	Optional
serviceDate	string	Optional
notes	string	Optional
reason	string	Optional

Example call

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

Result

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "structuredContent": {
      "status": 200,
      "ok": true,
      "data": { "...": "the written record" }
    }
  }
}

Errors

Code	Status	When
validation_failed	400	An argument is missing, of the wrong type, or outside its allowed values.
not_found	404	The id does not exist in your practice. A malformed id looks identical.
unauthorized	401	The bearer token is missing, invalid or expired.

write_invoice

WritesCan deleteAny member

Issue an invoice for a patient's unbilled entries (action=issue, requires patientId) or void an issued one (action=void, requires invoiceId). Issuing freezes the current line items.

Arguments

Tool	Type	Required?
action	issue \| void	Required
patientId	string	Optional
kind	receipt \| invoice	Optional
entryIds	array	Optional
invoiceId	string	Optional
reason	string	Optional

Example call

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

Result

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "structuredContent": {
      "status": 200,
      "ok": true,
      "data": { "...": "the written record" }
    }
  }
}

Errors

Code	Status	When
validation_failed	400	An argument is missing, of the wrong type, or outside its allowed values.
not_found	404	The id does not exist in your practice. A malformed id looks identical.
unauthorized	401	The bearer token is missing, invalid or expired.

Common questions

Patient records are encrypted in transit and at rest, files are stored privately and served through short-lived signed links, and every change is written to an audit log. Staff accounts sign in with passkeys rather than shared passwords.

Yes. Every list in HyperCRM exports to CSV from the app, and your files can be downloaded at any time. Your practice data belongs to you, and there is no export fee or waiting period — on either plan, during the trial, and after you cancel.

HyperCRM is paid software. Every practice starts with a 30-day free trial of the full Complete plan, with no card required. After that, plans start at €19 and €29 a month excluding VAT, banded by how many practitioners you have. Every price is printed on the pricing page rather than quoted on a call.