API reference: Billy

All Billy tools are read-only and are called via tools/call over POST /billy/mcp. The connector is connected with an access token (Billy’s permanent, organization-scoped token, no OAuth). See Forbind Billy.

Endpoint: https://mcp.consile.ai/billy/mcp. Billy is its own named connector with only its own tools. The transport namespaces each tool as billy__<tool> (e.g. billy__get_invoice). The tables below use the bare tool names; in a tools/call request always send the namespaced name, as in the examples. A bare name returns Unknown tool.

This connector is read-only: it only reads from Billy and has no tool that creates, changes or deletes anything. All 17 tools are listed with readOnlyHint: true, destructiveHint: false and openWorldHint: false.

Besides the 17 Billy tools, tools/list on this endpoint also returns the system tool connect_account (no arguments). It returns { connect_url, instructions }: a link, valid for 10 minutes, that the user opens in a browser to connect, or replace, the Billy access token for this endpoint.

Shared conventions

No organizationId

Billy’s access token is organization-scoped: one token maps to exactly one Billy company, so no tool takes an organizationId. The token itself scopes every request. get_organization is the health-check that tells you which company the connected token belongs to. A customer with several Billy companies adds one portal per company in the Consile portal and connects each with that company’s own token. Portal N (N ≥ 2) is its own MCP connector at https://mcp.consile.ai/billy-N/mcp (for example billy-2), with tools namespaced billy-2__<tool>. Add each URL to your MCP client separately. After a portal is removed, another portal’s URL and tool prefix can change (for example from billy-3 to billy-2). Check the portal URLs in the Consile portal and update your client.

Pagination

List tools return a compact { items, pagination } envelope. total is the filtered total, and hasMore is true while page is below pageCount.

// list_* response
{
  "items": [ ... ],
  "pagination": { "page": 1, "pageSize": 50, "pageCount": 9, "total": 412, "hasMore": true }
}

integer

default:"1"

1-based page number.

integer

default:"50"

Rows per page. Default is 50 on every list tool except list_currencies (default 200). The maximum is 1000.

Amounts, ids and dates

Billy amounts are floats in major units: 1200 means 1200.00 DKK. Never divide by 100. On invoices, bills and lines the taxMode field (incl/excl) governs whether the amount already includes VAT. Interpret VAT via list_tax_rates.

string

All Billy ids (invoiceId, billId, contactId, accountId, daybookId, transactionId, …) are opaque strings, never integers.

string (YYYY-MM-DD)

Date-only, no time or zone. minEntryDate/maxEntryDate are inclusive bounds on the invoice and bill lists.

Embedded children

get_invoice embeds its lines + customer contact and returns a downloadUrl (the invoice PDF link). get_bill embeds its lines + supplier contact. list_transactions, get_transaction embed the balanced postings. These get-one tools are already self-contained, so no follow-up call is needed.

Error contract

Upstream failures come back as a normal tool result with isError: true. Billy’s status code and error body are not passed to the client.

Cause	Result
Billy rejects the access token (for example a wrong token, or one deleted in Billy)	`Billy rejected the access token; reconnect required`. Create a new token in Billy and reconnect (portal, or `connect_account`).
Token valid but without access to the resource	`Tool invocation failed.` Reconnecting the same token does not help.
Billy’s rate limit	`Tool invocation failed.` Wait a moment and try again.
Any other upstream error, or no answer in time	`Tool invocation failed.`

Invalid arguments (for example a date not in YYYY-MM-DD, or pageSize above 1000) also return isError: true with Tool invocation failed., so validate arguments before calling. Other isError texts on this endpoint:

You are not subscribed to billy… when the account has no Billy subscription.
billy is not connected yet. Connect it here: <url> when the account subscribes but no token is connected.
A seat message when the signed-in user has no seat on Billy (an administrator assigns seats under Team in the portal).
Unknown tool. for a tool name that is not on this endpoint, including an unprefixed name or another connector’s tool.

See Errors & limits.

Organization & reference

Tool	Description	Key arguments	Returns
`get_organization`	The Billy company this token is connected to: name, base currency, CVR/registration number and address. The “which company am I connected to?” health-check.	(none)	`{ count, organizations[] }`
`list_products`	The product/service catalogue: name, account, prices, VAT.	`q?`, `page`, `pageSize`	`{ items, pagination }`
`list_tax_rates`	The organization’s VAT/tax rates (momssatser); interpret `tax`/`taxRateId` on invoices, bills and lines.	`page`, `pageSize`	`{ items, pagination }`
`list_sales_tax_returns`	VAT return periods (momsangivelser) with period bounds and status.	`page`, `pageSize`	`{ items, pagination }`
`list_currencies`	Currencies Billy knows (id = ISO code, e.g. DKK); reference for `currencyId`/`exchangeRate`.	`page`, `pageSize` (default `200`)	`{ items, pagination }`

Sales: invoices (accounts receivable)

Tool	Description	Key arguments	Returns
`list_invoices`	Sales invoices, sorted newest first (by entry date).	`state?` (`draft`/`approved`), `isPaid?`, `contactId?`, `minEntryDate?`, `maxEntryDate?`, `q?`, `page`, `pageSize`	`{ items, pagination }`
`get_invoice`	Full invoice by id with lines + customer embedded, plus `downloadUrl` (PDF link).	`invoiceId`	invoice object

Invoice state is draft or approved; approved is a finalised invoice (a one-way door in Billy).

Purchases: bills (accounts payable)

Tool	Description	Key arguments	Returns
`list_bills`	Supplier bills (kreditorer), sorted newest first (by entry date).	`state?` (`draft`/`approved`/`voided`), `isPaid?`, `contactId?` (supplier), `minEntryDate?`, `maxEntryDate?`, `q?`, `page`, `pageSize`	`{ items, pagination }`
`get_bill`	Full bill by id with lines + supplier embedded.	`billId`	bill object

Contacts

Billy keeps one contact register for both customers and suppliers. The isCustomer/isSupplier flags split them; registrationNo carries the CVR.

Tool	Description	Key arguments	Returns
`list_contacts`	Search/list the merged customer + supplier register.	`isCustomer?`, `isSupplier?`, `q?`, `page`, `pageSize`	`{ items, pagination }`
`get_contact`	Full single contact: customer/supplier flags, CVR (`registrationNo`), EAN, address, payment terms.	`contactId`	contact object

Finance / general ledger

Tool	Description	Key arguments	Returns
`list_accounts`	The chart of accounts (kontoplan): account number, name, group, VAT rate, bank-account flags.	`q?`, `page`, `pageSize`	`{ items, pagination }`
`list_postings`	Double-entry ledger postings (raw kontokort). Scope to one account via `accountId`. Each posting has amount, side (debit/credit) and a link to its transaction/voucher.	`accountId?`, `page`, `pageSize`	`{ items, pagination }`
`list_transactions`	Voucher-level transactions (bilag) with their balanced postings embedded.	`page`, `pageSize`	`{ items, pagination }`
`get_transaction`	One voucher/transaction (bilag) by id with its balanced postings embedded.	`transactionId`	transaction object
`list_daybook_transactions`	Daybook (kladde) entries; `state=draft` returns the entries awaiting posting.	`daybookId?`, `state?` (`draft`/`approved`/`voided`), `page`, `pageSize`	`{ items, pagination }`
`list_bank_payments`	Bank payments used to settle invoices/bills: the reconciliation view of money in and out.	`page`, `pageSize`	`{ items, pagination }`

Code examples

{
  "name": "billy__list_invoices",
  "arguments": { "isPaid": false, "pageSize": 100 }
}

{
  "name": "billy__get_invoice",
  "arguments": { "invoiceId": "AbCd1234..." }
}

{
  "name": "billy__list_postings",
  "arguments": { "accountId": "XyZ9876...", "pageSize": 200 }
}

Call get_organization after connecting to check the connection. If Billy rejects the token (for example a wrong token, or one deleted in Billy), the call returns Billy rejected the access token; reconnect required. See Errors & limits.

Introduction

Connect an MCP client

API reference

API reference: Billy

Shared conventions

No organizationId

Amounts, ids and dates

Embedded children

Error contract

Organization & reference

Sales: invoices (accounts receivable)

Purchases: bills (accounts payable)

Contacts

Finance / general ledger

Code examples

​Shared conventions

​No organizationId

​Pagination

​Amounts, ids and dates

​Embedded children

​Error contract

​Organization & reference

​Sales: invoices (accounts receivable)

​Purchases: bills (accounts payable)

​Contacts

​Finance / general ledger

​Code examples

Shared conventions

No organizationId

Pagination

Amounts, ids and dates

Embedded children

Error contract

Organization & reference

Sales: invoices (accounts receivable)

Purchases: bills (accounts payable)

Contacts

Finance / general ledger

Code examples