# Mast API: reference

Version 1.0.2. Base address: `https://api.mastfinance.io/api/v1`. How to authenticate, the
conventions, the refusals every call can meet and how to read changes are in the [guide](https://mastfinance.io/developers/guide.md).

## Account

The key calling and the company it acts in.

### The key calling and its company

`GET /ext/me`

Right: none, any key · 300 calls a minute · MCP tool: `mast_whoami`

The first call to make with a new key. It asks no right, so it tells a key that works from one that does not before any other call is tried.

**Answers** `200` with a [KeyAndCompany](#keyandcompany). The key and its company.

### The company and its fiscal years

`GET /ext/company`

Right: Company Profile, read · 300 calls a minute · MCP tool: `mast_get_company`

What a reader needs before the books: the base currency, the fiscal years, the VAT registration and today’s accounting day.

**Answers** `200` with a [Company](#company). The company.

**Refusals of its own**

| Status | Code | Meaning |
|---|---|---|
| 404 | `EXT_COMPANY_NOT_FOUND` | The key's company no longer exists. |

## Customers

The company’s customers, addressed by the back office’s own reference.

### The customers changed since a moment

`GET /ext/customers`

Right: Customer, read · 300 calls a minute · MCP tool: `mast_list_customers`

Every customer of the company, yours and the ones people made in Mast (`externalRef` null), oldest change first. A customer deleted in Mast drops out of the list.

**Query**

| Field | Type | Required | What it is |
|---|---|---|---|
| `updatedSince` | instant (ISO 8601) |  | An instant with its offset (`2026-11-18T08:00:00Z`): only what changed at or after it. Left out, everything. |
| `cursor` | string |  | The `nextCursor` of the page before, to read the next one; null there means the list is read to its end. A value that is no cursor, or a cursor of another list, is refused. (min length 1, max length 500) |
| `limit` | integer |  | How many rows a page holds at most: 50 when left out, never more than 100. (at least 1, at most 100, default `50`) |

**Answers** `200`. A page of customers.

| Field | Type | Always there | What it is |
|---|---|---|---|
| `data` | list of [Customer](#customer) | yes | The rows of this page, oldest change first. |
| `nextCursor` | string or null | yes | Pass it back as `cursor` to read the next page. Null when there is nothing more for now. |

**Refusals of its own**

| Status | Code | Meaning |
|---|---|---|
| 400 | `EXT_CURSOR_INVALID` | This cursor is not one this list gave: start again without it. |

### Make a customer

`POST /ext/customers`

Right: Customer, create · 60 calls a minute

Makes a customer under your own id. To make it or change it in one call whatever its state, use `PUT /ext/customers/{externalRef}`.

**Body**

| Field | Type | Required | What it is |
|---|---|---|---|
| `externalRef` | string | yes | The id your own system gives the resource. Unique per company for each kind of resource. Mast stores it as you send it, less the spaces around it (`crm-1042 ` is `crm-1042`) and any NUL character, which Mast takes out of every text of a body (in a path, a NUL is refused). (min length 1, max length 100) |
| `type` | one of `business`, `individual` | yes | `business` for a company, named by `companyName`; `individual` for a person, named by `firstName` and `lastName`. |
| `email` | string (email) | yes | The address invoices and reminders are sent to. Every customer of Mast has one. (max length 254) |
| `address` | object | yes | The billing address: what the customer's invoices print. |
| `address.street` | string | yes | Street and number, on one line. (min length 1, max length 200) |
| `address.postalCode` | string | yes | min length 1, max length 20 |
| `address.city` | string | yes | min length 1, max length 100 |
| `address.country` | string or null |  | The country's name, as the customer's card in Mast writes it ("France", "Germany"). Left out, the company's own country. (min length 1, max length 100) |
| `companyName` | string or null |  | Required for a business. (min length 1, max length 200) |
| `firstName` | string or null |  | Required for an individual. (min length 1, max length 100) |
| `lastName` | string or null |  | Required for an individual. (min length 1, max length 100) |
| `phone` | string or null |  | Mast keeps it in its international form, without spaces (`+41440000000`), and serves it so. Null or an empty string removes it. (max length 30) |
| `language` | one of `de`, `fr`, `it`, `en` |  | The language the customer's invoices and reminders are written in. Left out on a create, the company's own. |
| `vatNumber` | string or null |  | The customer's VAT number, in its country's format (`CHE-123.456.789 MWST`, `DE123456789`). Null or an empty string removes it. (max length 30) |
| `registrationNumber` | string or null |  | Its commercial-register number (a UID, or a foreign registry's id). Null or an empty string removes it. (max length 100) |
| `defaultDiscountPercent` | number |  | The discount Mast holds for this customer, in percent; 0 for none. An invoice takes it only when it says `applyCustomerDefaultDiscount`. (at least 0, at most 100) |
| `paymentTermsDays` | number |  | Its net payment terms in whole days, 0 for due on receipt. An invoice that names no terms takes them. 30 when never set. |

**Answers** `201` with a [Customer](#customer). The customer made.

**Refusals of its own**

| Status | Code | Meaning |
|---|---|---|
| 400 | `EXT_CUSTOMER_INVALID` | This customer is not valid. The answer does not say which field Mast’s own rules refused: compare what you sent with the fields above. |
| 409 | `EXT_CUSTOMER_EXISTS` | A customer with this externalRef already exists in the company: update it with PATCH or PUT. |
| 409 | `EXT_CUSTOMER_ARCHIVED` | The customer with this externalRef was archived in Mast: restore it there, or use another reference. |
| 409 | `CUSTOMER_NAME_EXISTS` | If that customer was made in Mast, give it your reference with `PATCH /ext/customers/by-id/{id}` rather than making a second one. For example: « A customer named "Muster Handel AG" with the same billing address and email address already exists. Change one of the three, or edit the existing entry. » |

### A customer, by your reference

`GET /ext/customers/{externalRef}`

Right: Customer, read · 300 calls a minute · MCP tool: `mast_get_customer`

**In the path**

| Field | Type | Required | What it is |
|---|---|---|---|
| `externalRef` | string | yes | Your own id of the resource, as you gave it when you made it. (min length 1, max length 100) |

**Answers** `200` with a [Customer](#customer). The customer.

**Refusals of its own**

| Status | Code | Meaning |
|---|---|---|
| 404 | `EXT_CUSTOMER_NOT_FOUND` | No customer of the company has this reference. |

### Make or change a customer

`PUT /ext/customers/{externalRef}`

Right: Customer, edit and create · 60 calls a minute · MCP tool: `mast_save_customer`

The call a sync makes: when the company has no customer under this reference it is made, and the body must then hold what a creation needs (type, name, e-mail, address); else the fields given are changed and the others stay. Safe to repeat.

**In the path**

| Field | Type | Required | What it is |
|---|---|---|---|
| `externalRef` | string | yes | Your own id of the resource, as you gave it when you made it. (min length 1, max length 100) |

**Body**

| Field | Type | Required | What it is |
|---|---|---|---|
| `type` | one of `business`, `individual` |  | `business` for a company, named by `companyName`; `individual` for a person, named by `firstName` and `lastName`. |
| `email` | string (email) |  | The address invoices and reminders are sent to. Every customer of Mast has one. (max length 254) |
| `address` | object |  | The billing address: what the customer's invoices print. |
| `address.street` | string | yes | Street and number, on one line. (min length 1, max length 200) |
| `address.postalCode` | string | yes | min length 1, max length 20 |
| `address.city` | string | yes | min length 1, max length 100 |
| `address.country` | string or null |  | The country's name, as the customer's card in Mast writes it ("France", "Germany"). Left out, the company's own country. (min length 1, max length 100) |
| `companyName` | string or null |  | Required for a business. (min length 1, max length 200) |
| `firstName` | string or null |  | Required for an individual. (min length 1, max length 100) |
| `lastName` | string or null |  | Required for an individual. (min length 1, max length 100) |
| `phone` | string or null |  | Mast keeps it in its international form, without spaces (`+41440000000`), and serves it so. Null or an empty string removes it. (max length 30) |
| `language` | one of `de`, `fr`, `it`, `en` |  | The language the customer's invoices and reminders are written in. Left out on a create, the company's own. |
| `vatNumber` | string or null |  | The customer's VAT number, in its country's format (`CHE-123.456.789 MWST`, `DE123456789`). Null or an empty string removes it. (max length 30) |
| `registrationNumber` | string or null |  | Its commercial-register number (a UID, or a foreign registry's id). Null or an empty string removes it. (max length 100) |
| `defaultDiscountPercent` | number |  | The discount Mast holds for this customer, in percent; 0 for none. An invoice takes it only when it says `applyCustomerDefaultDiscount`. (at least 0, at most 100) |
| `paymentTermsDays` | number |  | Its net payment terms in whole days, 0 for due on receipt. An invoice that names no terms takes them. 30 when never set. |

**Answers** `200` with a [Customer](#customer). The customer, changed. Answers `201` with the same body when it makes it: The reference was new: the customer was made.

**Refusals of its own**

| Status | Code | Meaning |
|---|---|---|
| 400 | `EXT_CUSTOMER_INVALID` | This customer is not valid. The answer does not say which field Mast’s own rules refused: compare what you sent with the fields above. |
| 409 | `EXT_CUSTOMER_ARCHIVED` | The customer with this externalRef was archived in Mast: restore it there, or use another reference. |
| 409 | `CUSTOMER_NAME_EXISTS` | If that customer was made in Mast, give it your reference with `PATCH /ext/customers/by-id/{id}` rather than making a second one. For example: « A customer named "Muster Handel AG" with the same billing address and email address already exists. Change one of the three, or edit the existing entry. » |
| 422 | `EXT_CUSTOMER_INCOMPLETE` | No customer has this externalRef yet, and making one takes its type, its name, its e-mail address and its address. |

### Change a customer

`PATCH /ext/customers/{externalRef}`

Right: Customer, edit · 60 calls a minute

Changes the fields given; a field left out stays as it is.

**In the path**

| Field | Type | Required | What it is |
|---|---|---|---|
| `externalRef` | string | yes | Your own id of the resource, as you gave it when you made it. (min length 1, max length 100) |

**Body**

| Field | Type | Required | What it is |
|---|---|---|---|
| `type` | one of `business`, `individual` |  | `business` for a company, named by `companyName`; `individual` for a person, named by `firstName` and `lastName`. |
| `email` | string (email) |  | The address invoices and reminders are sent to. Every customer of Mast has one. (max length 254) |
| `address` | object |  | The billing address: what the customer's invoices print. |
| `address.street` | string | yes | Street and number, on one line. (min length 1, max length 200) |
| `address.postalCode` | string | yes | min length 1, max length 20 |
| `address.city` | string | yes | min length 1, max length 100 |
| `address.country` | string or null |  | The country's name, as the customer's card in Mast writes it ("France", "Germany"). Left out, the company's own country. (min length 1, max length 100) |
| `companyName` | string or null |  | Required for a business. (min length 1, max length 200) |
| `firstName` | string or null |  | Required for an individual. (min length 1, max length 100) |
| `lastName` | string or null |  | Required for an individual. (min length 1, max length 100) |
| `phone` | string or null |  | Mast keeps it in its international form, without spaces (`+41440000000`), and serves it so. Null or an empty string removes it. (max length 30) |
| `language` | one of `de`, `fr`, `it`, `en` |  | The language the customer's invoices and reminders are written in. Left out on a create, the company's own. |
| `vatNumber` | string or null |  | The customer's VAT number, in its country's format (`CHE-123.456.789 MWST`, `DE123456789`). Null or an empty string removes it. (max length 30) |
| `registrationNumber` | string or null |  | Its commercial-register number (a UID, or a foreign registry's id). Null or an empty string removes it. (max length 100) |
| `defaultDiscountPercent` | number |  | The discount Mast holds for this customer, in percent; 0 for none. An invoice takes it only when it says `applyCustomerDefaultDiscount`. (at least 0, at most 100) |
| `paymentTermsDays` | number |  | Its net payment terms in whole days, 0 for due on receipt. An invoice that names no terms takes them. 30 when never set. |

**Answers** `200` with a [Customer](#customer). The customer, changed.

**Refusals of its own**

| Status | Code | Meaning |
|---|---|---|
| 400 | `EXT_CUSTOMER_INVALID` | This customer is not valid. The answer does not say which field Mast’s own rules refused: compare what you sent with the fields above. |
| 404 | `EXT_CUSTOMER_NOT_FOUND` | No customer of the company has this reference. |
| 409 | `CUSTOMER_NAME_EXISTS` | If that customer was made in Mast, give it your reference with `PATCH /ext/customers/by-id/{id}` rather than making a second one. For example: « A customer named "Muster Handel AG" with the same billing address and email address already exists. Change one of the three, or edit the existing entry. » |

### A customer, by Mast’s id

`GET /ext/customers/by-id/{id}`

Right: Customer, read · 300 calls a minute

For a customer made in Mast, which has no `externalRef`.

**In the path**

| Field | Type | Required | What it is |
|---|---|---|---|
| `id` | string | yes | Mast’s own id of the resource: the `id` every read returns. (min length 1, max length 100) |

**Answers** `200` with a [Customer](#customer). The customer.

**Refusals of its own**

| Status | Code | Meaning |
|---|---|---|
| 404 | `EXT_CUSTOMER_NOT_FOUND` | No customer of the company has this reference. |

### Give a customer your reference, by Mast’s id

`PATCH /ext/customers/by-id/{id}`

Right: Customer, edit · 60 calls a minute

For a customer that is already in Mast with no `externalRef`, because a person made or imported it there. The call gives it your own id: `PUT /ext/customers/{externalRef}` then finds that customer and changes it, and an invoice can name it (`customerExternalRef`). It also changes the reference a customer holds, and `null` takes it away. The reference it already holds changes nothing. No other field is changed here: once the customer holds your reference, change it by that.

**In the path**

| Field | Type | Required | What it is |
|---|---|---|---|
| `id` | string | yes | Mast’s own id of the resource: the `id` every read returns. (min length 1, max length 100) |

**Body**

| Field | Type | Required | What it is |
|---|---|---|---|
| `externalRef` | string or null | yes | Your own id for this customer: from then on it is addressed by it (`/ext/customers/{externalRef}`), and an invoice names it by it (`customerExternalRef`). Unique per company. Null takes away the one it holds. (min length 1, max length 100) |

**Answers** `200` with a [Customer](#customer). The customer, with the reference it now holds.

**Refusals of its own**

| Status | Code | Meaning |
|---|---|---|
| 404 | `EXT_CUSTOMER_NOT_FOUND` | No customer of the company has this reference. |
| 409 | `EXT_CUSTOMER_EXISTS` | A customer with this externalRef already exists in the company: update it with PATCH or PUT. |
| 409 | `EXT_CUSTOMER_ARCHIVED` | The customer with this externalRef was archived in Mast: restore it there, or use another reference. |

## Products

What the company sells, addressed by the back office’s own reference.

### The products changed since a moment

`GET /ext/products`

Right: Product, read · 300 calls a minute · MCP tool: `mast_list_products`

Every product of the company, yours and the ones people made in Mast, oldest change first. A product deleted in Mast drops out of the list.

**Query**

| Field | Type | Required | What it is |
|---|---|---|---|
| `updatedSince` | instant (ISO 8601) |  | An instant with its offset (`2026-11-18T08:00:00Z`): only what changed at or after it. Left out, everything. |
| `cursor` | string |  | The `nextCursor` of the page before, to read the next one; null there means the list is read to its end. A value that is no cursor, or a cursor of another list, is refused. (min length 1, max length 500) |
| `limit` | integer |  | How many rows a page holds at most: 50 when left out, never more than 100. (at least 1, at most 100, default `50`) |

**Answers** `200`. A page of products.

| Field | Type | Always there | What it is |
|---|---|---|---|
| `data` | list of [Product](#product) | yes | The rows of this page, oldest change first. |
| `nextCursor` | string or null | yes | Pass it back as `cursor` to read the next page. Null when there is nothing more for now. |

**Refusals of its own**

| Status | Code | Meaning |
|---|---|---|
| 400 | `EXT_CURSOR_INVALID` | This cursor is not one this list gave: start again without it. |

### Make a product

`POST /ext/products`

Right: Product, create · 60 calls a minute

Makes a product under your own id. To make it or change it in one call whatever its state, use `PUT /ext/products/{externalRef}`.

**Body**

| Field | Type | Required | What it is |
|---|---|---|---|
| `externalRef` | string | yes | The id your own system gives the resource. Unique per company for each kind of resource. Mast stores it as you send it, less the spaces around it (`crm-1042 ` is `crm-1042`) and any NUL character, which Mast takes out of every text of a body (in a path, a NUL is refused). (min length 1, max length 100) |
| `type` | one of `good`, `service` | yes | `good` for something delivered, `service` for work done. |
| `name` | string | yes | The name an invoice line of this product prints. (min length 1, max length 200) |
| `unitPrice` | number | yes | The selling price of one unit, without VAT unless an invoice says its prices include it. A line may always name its own. (at least 0, at most 99999999.99) |
| `code` | string or null |  | The product's own code, printed beside its name. Null removes it. (min length 1, max length 50) |
| `description` | string or null |  | A note on the product in Mast. Null removes it. (max length 2000) |
| `costPrice` | number |  | What one unit costs the company; 0 when never set. (at least 0, at most 99999999.99) |
| `currency` | string |  | The ISO 4217 code its prices are in, one of the currencies Mast offers: AUD, BGN, BRL, CAD, CHF, CNY, CZK, DKK, EUR, GBP, HKD, HRK, HUF, IDR, ILS, INR, ISK, JPY, KRW, MAD, MXN, MYR, NOK, NZD, PHP, PLN, RON, RUB, SEK, SGD, THB, TRY, USD, ZAR. Left out on a create, the company's base currency. An invoice line that takes the product's price takes the number as it is, in the invoice's own currency: nothing is converted. (min length 3, max length 3) |
| `unit` | string or null |  | What a quantity counts (`h`, `pcs`, `kg`). Null removes it. (min length 1, max length 50) |
| `accountCode` | string or null |  | The number of the revenue account, in the company's chart, that a line of this product is booked to. Null removes it. (min length 1, max length 20) |
| `vatRateCode` | string or null |  | One of the company's VAT codes (`CH_STD`): the rate a line of this product takes when it names none. Null removes it. (min length 1, max length 40) |

**Answers** `201` with a [Product](#product). The product made.

**Refusals of its own**

| Status | Code | Meaning |
|---|---|---|
| 400 | `EXT_PRODUCT_INVALID` | This product is not valid. The answer does not say which field Mast’s own rules refused: compare what you sent with the fields above. |
| 409 | `EXT_PRODUCT_EXISTS` | A product with this externalRef already exists in the company: update it with PATCH or PUT. |
| 409 | `EXT_PRODUCT_ARCHIVED` | The product with this externalRef was archived in Mast: restore it there, or use another reference. |
| 422 | `EXT_PRODUCT_ACCOUNT_UNKNOWN` | No active account of the company's chart has this accountCode. |
| 422 | `EXT_PRODUCT_VAT_RATE_UNKNOWN` | No VAT rate the company sells at today has this vatRateCode. |

### A product, by your reference

`GET /ext/products/{externalRef}`

Right: Product, read · 300 calls a minute · MCP tool: `mast_get_product`

**In the path**

| Field | Type | Required | What it is |
|---|---|---|---|
| `externalRef` | string | yes | Your own id of the resource, as you gave it when you made it. (min length 1, max length 100) |

**Answers** `200` with a [Product](#product). The product.

**Refusals of its own**

| Status | Code | Meaning |
|---|---|---|
| 404 | `EXT_PRODUCT_NOT_FOUND` | No product of the company has this reference. |

### Make or change a product

`PUT /ext/products/{externalRef}`

Right: Product, edit and create · 60 calls a minute · MCP tool: `mast_save_product`

When the company has no product under this reference it is made, and the body must then hold what a creation needs (type, name, unit price); else the fields given are changed and the others stay. Safe to repeat.

**In the path**

| Field | Type | Required | What it is |
|---|---|---|---|
| `externalRef` | string | yes | Your own id of the resource, as you gave it when you made it. (min length 1, max length 100) |

**Body**

| Field | Type | Required | What it is |
|---|---|---|---|
| `type` | one of `good`, `service` |  | `good` for something delivered, `service` for work done. |
| `name` | string |  | The name an invoice line of this product prints. (min length 1, max length 200) |
| `unitPrice` | number |  | The selling price of one unit, without VAT unless an invoice says its prices include it. A line may always name its own. (at least 0, at most 99999999.99) |
| `code` | string or null |  | The product's own code, printed beside its name. Null removes it. (min length 1, max length 50) |
| `description` | string or null |  | A note on the product in Mast. Null removes it. (max length 2000) |
| `costPrice` | number |  | What one unit costs the company; 0 when never set. (at least 0, at most 99999999.99) |
| `currency` | string |  | The ISO 4217 code its prices are in, one of the currencies Mast offers: AUD, BGN, BRL, CAD, CHF, CNY, CZK, DKK, EUR, GBP, HKD, HRK, HUF, IDR, ILS, INR, ISK, JPY, KRW, MAD, MXN, MYR, NOK, NZD, PHP, PLN, RON, RUB, SEK, SGD, THB, TRY, USD, ZAR. Left out on a create, the company's base currency. An invoice line that takes the product's price takes the number as it is, in the invoice's own currency: nothing is converted. (min length 3, max length 3) |
| `unit` | string or null |  | What a quantity counts (`h`, `pcs`, `kg`). Null removes it. (min length 1, max length 50) |
| `accountCode` | string or null |  | The number of the revenue account, in the company's chart, that a line of this product is booked to. Null removes it. (min length 1, max length 20) |
| `vatRateCode` | string or null |  | One of the company's VAT codes (`CH_STD`): the rate a line of this product takes when it names none. Null removes it. (min length 1, max length 40) |

**Answers** `200` with a [Product](#product). The product, changed. Answers `201` with the same body when it makes it: The reference was new: the product was made.

**Refusals of its own**

| Status | Code | Meaning |
|---|---|---|
| 400 | `EXT_PRODUCT_INVALID` | This product is not valid. The answer does not say which field Mast’s own rules refused: compare what you sent with the fields above. |
| 409 | `EXT_PRODUCT_ARCHIVED` | The product with this externalRef was archived in Mast: restore it there, or use another reference. |
| 422 | `EXT_PRODUCT_ACCOUNT_UNKNOWN` | No active account of the company's chart has this accountCode. |
| 422 | `EXT_PRODUCT_VAT_RATE_UNKNOWN` | No VAT rate the company sells at today has this vatRateCode. |
| 422 | `EXT_PRODUCT_INCOMPLETE` | No product has this externalRef yet, and making one takes its type, its name and its unit price. |

### Change a product

`PATCH /ext/products/{externalRef}`

Right: Product, edit · 60 calls a minute

Changes the fields given; a field left out stays as it is.

**In the path**

| Field | Type | Required | What it is |
|---|---|---|---|
| `externalRef` | string | yes | Your own id of the resource, as you gave it when you made it. (min length 1, max length 100) |

**Body**

| Field | Type | Required | What it is |
|---|---|---|---|
| `type` | one of `good`, `service` |  | `good` for something delivered, `service` for work done. |
| `name` | string |  | The name an invoice line of this product prints. (min length 1, max length 200) |
| `unitPrice` | number |  | The selling price of one unit, without VAT unless an invoice says its prices include it. A line may always name its own. (at least 0, at most 99999999.99) |
| `code` | string or null |  | The product's own code, printed beside its name. Null removes it. (min length 1, max length 50) |
| `description` | string or null |  | A note on the product in Mast. Null removes it. (max length 2000) |
| `costPrice` | number |  | What one unit costs the company; 0 when never set. (at least 0, at most 99999999.99) |
| `currency` | string |  | The ISO 4217 code its prices are in, one of the currencies Mast offers: AUD, BGN, BRL, CAD, CHF, CNY, CZK, DKK, EUR, GBP, HKD, HRK, HUF, IDR, ILS, INR, ISK, JPY, KRW, MAD, MXN, MYR, NOK, NZD, PHP, PLN, RON, RUB, SEK, SGD, THB, TRY, USD, ZAR. Left out on a create, the company's base currency. An invoice line that takes the product's price takes the number as it is, in the invoice's own currency: nothing is converted. (min length 3, max length 3) |
| `unit` | string or null |  | What a quantity counts (`h`, `pcs`, `kg`). Null removes it. (min length 1, max length 50) |
| `accountCode` | string or null |  | The number of the revenue account, in the company's chart, that a line of this product is booked to. Null removes it. (min length 1, max length 20) |
| `vatRateCode` | string or null |  | One of the company's VAT codes (`CH_STD`): the rate a line of this product takes when it names none. Null removes it. (min length 1, max length 40) |

**Answers** `200` with a [Product](#product). The product, changed.

**Refusals of its own**

| Status | Code | Meaning |
|---|---|---|
| 400 | `EXT_PRODUCT_INVALID` | This product is not valid. The answer does not say which field Mast’s own rules refused: compare what you sent with the fields above. |
| 404 | `EXT_PRODUCT_NOT_FOUND` | No product of the company has this reference. |
| 422 | `EXT_PRODUCT_ACCOUNT_UNKNOWN` | No active account of the company's chart has this accountCode. |
| 422 | `EXT_PRODUCT_VAT_RATE_UNKNOWN` | No VAT rate the company sells at today has this vatRateCode. |

### A product, by Mast’s id

`GET /ext/products/by-id/{id}`

Right: Product, read · 300 calls a minute

For a product made in Mast, which has no `externalRef`.

**In the path**

| Field | Type | Required | What it is |
|---|---|---|---|
| `id` | string | yes | Mast’s own id of the resource: the `id` every read returns. (min length 1, max length 100) |

**Answers** `200` with a [Product](#product). The product.

**Refusals of its own**

| Status | Code | Meaning |
|---|---|---|
| 404 | `EXT_PRODUCT_NOT_FOUND` | No product of the company has this reference. |

### Give a product your reference, by Mast’s id

`PATCH /ext/products/by-id/{id}`

Right: Product, edit · 60 calls a minute

For a product that is already in Mast with no `externalRef`, because a person made or imported it there. The call gives it your own id: `PUT /ext/products/{externalRef}` then finds that product and changes it, and an invoice line can name it (`productExternalRef`). It also changes the reference a product holds, and `null` takes it away. The reference it already holds changes nothing. No other field is changed here: once the product holds your reference, change it by that.

**In the path**

| Field | Type | Required | What it is |
|---|---|---|---|
| `id` | string | yes | Mast’s own id of the resource: the `id` every read returns. (min length 1, max length 100) |

**Body**

| Field | Type | Required | What it is |
|---|---|---|---|
| `externalRef` | string or null | yes | Your own id for this product: from then on it is addressed by it (`/ext/products/{externalRef}`), and an invoice line names it by it (`productExternalRef`). Unique per company. Null takes away the one it holds. (min length 1, max length 100) |

**Answers** `200` with a [Product](#product). The product, with the reference it now holds.

**Refusals of its own**

| Status | Code | Meaning |
|---|---|---|
| 404 | `EXT_PRODUCT_NOT_FOUND` | No product of the company has this reference. |
| 409 | `EXT_PRODUCT_EXISTS` | A product with this externalRef already exists in the company: update it with PATCH or PUT. |
| 409 | `EXT_PRODUCT_ARCHIVED` | The product with this externalRef was archived in Mast: restore it there, or use another reference. |

## Invoices

Draft, issue, send and read customer invoices.

### The invoices changed since a moment

`GET /ext/invoices`

Right: Customer Invoices, read · 300 calls a minute · MCP tool: `mast_list_invoices`

Every invoice of the company, yours and the ones people made in Mast, oldest change first, by `status` when asked. `include=lines` adds each invoice’s lines. An invoice that becomes overdue does not change, so a read by `updatedSince` does not serve it again for that: `overdue` is judged on the day of the read. A page ends early past 2,000 lines, counted whether or not `include=lines` asks for them (the figures are worked out from them), never inside a document: follow `nextCursor`.

**Query**

| Field | Type | Required | What it is |
|---|---|---|---|
| `updatedSince` | instant (ISO 8601) |  | An instant with its offset (`2026-11-18T08:00:00Z`): only what changed at or after it. Left out, everything. |
| `cursor` | string |  | The `nextCursor` of the page before, to read the next one; null there means the list is read to its end. A value that is no cursor, or a cursor of another list, is refused. (min length 1, max length 500) |
| `limit` | integer |  | How many rows a page holds at most: 50 when left out, never more than 100. (at least 1, at most 100, default `50`) |
| `include` | one of `lines` |  | `lines`: each document comes with its lines. Left out, `lines` is null and the page is lighter. |
| `status` | any |  | Only the documents in one of these states, separated by commas: draft, open, overdue, partially_paid, paid, cancelled, paid_in_provider, refunded_in_provider, paid_outside_provider. |

**Answers** `200`. A page of invoices.

| Field | Type | Always there | What it is |
|---|---|---|---|
| `data` | list of [Invoice](#invoice) | yes | The rows of this page, oldest change first. |
| `nextCursor` | string or null | yes | Pass it back as `cursor` to read the next page. Null when there is nothing more for now. |

**Refusals of its own**

| Status | Code | Meaning |
|---|---|---|
| 400 | `EXT_CURSOR_INVALID` | This cursor is not one this list gave: start again without it. |

### Make a draft invoice

`POST /ext/invoices`

Right: Customer Invoices, create · 60 calls a minute · MCP tool: `mast_create_invoice_draft`

Makes a **draft** for one of your customers, under your own id. A draft has no official number and no journal entry: it takes both when it is issued (`…/validate`, or `…/send`). A line names a product by `productExternalRef` and takes its name, price and VAT rate where it gives none of its own, or is free text with its own price. Mast applies no discount the call does not name: give the line’s `discountPercent`, the document’s `discountPercent` or `discountAmount`, or ask for the customer’s default with `applyCustomerDefaultDiscount`.

**Body**

| Field | Type | Required | What it is |
|---|---|---|---|
| `externalRef` | string | yes | The id your own system gives the resource. Unique per company for each kind of resource. Mast stores it as you send it, less the spaces around it (`crm-1042 ` is `crm-1042`) and any NUL character, which Mast takes out of every text of a body (in a path, a NUL is refused). (min length 1, max length 100) |
| `customerExternalRef` | string | yes | The externalRef of the customer the invoice is for. (min length 1, max length 100) |
| `lines` | list of object | yes | The lines, in the order the invoice prints them: one at least. (min items 1, max items 1000) |
| `lines[].quantity` | number | yes | How many units the line bills; below zero for a line that takes something off. Never zero. Times the unit price, at most 999999999999.99 either way. (at least -999999999999.99, at most 999999999999.99) |
| `lines[].description` | string or null |  | The line's words. Required unless the line names a product, whose name it then takes; beside a product, they follow its name. (min length 1, max length 2000) |
| `lines[].unit` | string or null |  | What the quantity counts (`h`, `pcs`). Left out, the product's unit, else `pcs`. (min length 1, max length 20) |
| `lines[].unitPrice` | number or null |  | The price of one unit, without VAT unless the invoice says `priceIncludesVat`. Required unless the line names a product, whose price it then takes as the number it is, in the invoice's currency, whatever the product's currency (nothing is converted): a price agreed with this customer is simply the price sent. (at least 0, at most 999999999999.99) |
| `lines[].discountPercent` | number or null |  | The line's own discount, in percent. (at least 0, at most 100) |
| `lines[].vatRatePercent` | number or null |  | The line's VAT rate, in percent (8.1, 2.6, 0). May be left out when `vatRateCode` names a rate, or when the line's product has one. (at least 0, at most 100) |
| `lines[].vatRateCode` | string or null |  | One of the company's VAT codes, as its VAT settings list them (`CH_STD`, `EXP_GOODS`): the line takes that rate. A `vatRatePercent` beside it must agree. (min length 1, max length 40) |
| `lines[].productExternalRef` | string or null |  | The externalRef of a product: the line is that product's, takes its name, price, unit and VAT rate where it names none, and is booked to its revenue account. Its price is taken as the number it is, in the invoice's currency: a product priced 100 in EUR gives 100.00 on an invoice in CHF, so give a line of an invoice in another currency its own `unitPrice`. (min length 1, max length 100) |
| `lines[].productCode` | string or null |  | A product code to print on the line. Left out, the product's own. (min length 1, max length 100) |
| `lines[].revenueAccountCode` | string or null |  | The number of the revenue account, in the company's chart, this line is booked to. Left out, the product's, else the company's default. (min length 1, max length 20) |
| `lines[].costCenterCode` | string or null |  | The code of one of the company's cost centres, which the line's revenue is filed under. (min length 1, max length 50) |
| `lines[].comment` | string or null |  | A note printed under the line. (max length 2000) |
| `lines[].supplyPeriodStart` | string or null |  | When this line was supplied, if not when the invoice says: its first day (YYYY-MM-DD). |
| `lines[].supplyPeriodEnd` | string or null |  | The last day of this line's own supply period (YYYY-MM-DD); left out, its first day. |
| `issueDate` | string |  | The day the invoice is dated (YYYY-MM-DD). Left out on a create, today. |
| `dueDate` | string or null |  | The day it is due (YYYY-MM-DD). Left out or null, the issue date plus the payment terms. |
| `paymentTermsDays` | integer |  | The net payment terms in days, 0 for due on receipt. Left out on a create, the customer's own terms. (at least 0, at most 365) |
| `paymentTermsText` | string or null |  | The payment terms in words, printed on the invoice. (max length 500) |
| `supplyPeriodStart` | string or null |  | The time of supply, when it is not the issue date: its first day (YYYY-MM-DD). It decides the VAT rate and is printed. |
| `supplyPeriodEnd` | string or null |  | The last day of the supply period (YYYY-MM-DD); left out, its first day. |
| `currency` | string |  | The ISO 4217 code the invoice is in, one of the currencies Mast offers: AUD, BGN, BRL, CAD, CHF, CNY, CZK, DKK, EUR, GBP, HKD, HRK, HUF, IDR, ILS, INR, ISK, JPY, KRW, MAD, MXN, MYR, NOK, NZD, PHP, PLN, RON, RUB, SEK, SGD, THB, TRY, USD, ZAR. Left out on a create, the company's base currency. (min length 3, max length 3) |
| `language` | one of `de`, `fr`, `it`, `en` |  | The language the invoice is written in. Left out on a create, the customer's language. |
| `reference` | string or null |  | Your customer's own reference (an order number), printed on the invoice. (max length 200) |
| `title` | string or null |  | A title printed above the lines. (max length 200) |
| `introText` | string or null |  | A text printed between the title and the lines. (max length 5000) |
| `notes` | string or null |  | A text printed under the totals. (max length 5000) |
| `footerText` | string or null |  | A text printed at the foot of the invoice. (max length 5000) |
| `priceIncludesVat` | boolean |  | True when the unit prices sent include VAT, which Mast then backs out of each line. False when left out. |
| `discountPercent` | number or null |  | A discount on the whole invoice, in percent, taken after each line's own. Not beside `discountAmount`. (at least 0, at most 100) |
| `discountAmount` | number or null |  | A discount on the whole invoice, as an amount of its currency. One above what the lines come to is not refused: it is taken as the whole of them, the invoice comes to 0.00, and it can be issued so. Not beside `discountPercent`. (at least 0, at most 999999999999.99) |
| `applyCustomerDefaultDiscount` | boolean |  | True: the draft takes the customer's default discount, when the call names no discount of its own. Left out, Mast applies no discount the call did not ask for. |

**Answers** `201` with an [Invoice](#invoice). The draft, with its lines and its totals.

**Refusals of its own**

| Status | Code | Meaning |
|---|---|---|
| 400 | `EXT_INVOICE_INVALID` | This invoice is not valid. The answer does not say which field Mast’s own rules refused: compare what you sent with the fields above. |
| 400 | `INVOICE_TOTAL_NEGATIVE` | The lines and the discounts come to less than zero, and an invoice bills. To take an amount back from a customer, make a credit note in Mast on the invoice it corrects. For example: « Invoice has a negative total (-108.10). To take an amount back from a customer, issue a credit note on the invoice it corrects. » |
| 409 | `EXT_INVOICE_EXISTS` | An invoice with this externalRef already exists in the company. |
| 422 | `EXT_INVOICE_CUSTOMER_UNKNOWN` | No customer has this customerExternalRef in the company: make it first (PUT /ext/customers/{externalRef}). |
| 422 | `EXT_INVOICE_PRODUCT_UNKNOWN` | No product has this productExternalRef in the company: make it first (PUT /ext/products/{externalRef}). |
| 422 | `EXT_INVOICE_VAT_RATE_UNKNOWN` | No VAT rate the company sells at on the invoice's day has this vatRateCode: name one of its VAT codes, or give vatRatePercent. |
| 422 | `EXT_INVOICE_VAT_RATE_MISMATCH` | vatRatePercent is not the rate vatRateCode names: send one of the two, or the two in agreement. |
| 422 | `EXT_INVOICE_VAT_RATE_MISSING` | This line names no VAT rate and its product has none of its own: give vatRatePercent or vatRateCode. |
| 422 | `EXT_INVOICE_COST_CENTER_UNKNOWN` | No cost centre of the company has this costCenterCode. |

### An invoice with its lines, by your reference

`GET /ext/invoices/{externalRef}`

Right: Customer Invoices, read · 300 calls a minute · MCP tool: `mast_get_invoice`

Its number, its state, what it bills line by line and what is still owed.

**In the path**

| Field | Type | Required | What it is |
|---|---|---|---|
| `externalRef` | string | yes | Your own id of the resource, as you gave it when you made it. (min length 1, max length 100) |

**Answers** `200` with an [Invoice](#invoice). The invoice, with its lines.

**Refusals of its own**

| Status | Code | Meaning |
|---|---|---|
| 404 | `EXT_INVOICE_NOT_FOUND` | No invoice of the company has this reference. |

### Change a draft

`PATCH /ext/invoices/{externalRef}`

Right: Customer Invoices, edit · 60 calls a minute · MCP tool: `mast_update_invoice_draft`

While the invoice is a draft: the fields given replace the draft’s, and `lines` given replace every line. A change of discount or of `priceIncludesVat` reprices the invoice, so it comes with the lines. A change that brings the total below zero is taken, and the draft is then refused when it is issued (`INVOICE_TOTAL_NEGATIVE`). An issued invoice is not changed: it is corrected by a credit note.

**In the path**

| Field | Type | Required | What it is |
|---|---|---|---|
| `externalRef` | string | yes | Your own id of the resource, as you gave it when you made it. (min length 1, max length 100) |

**Body**

| Field | Type | Required | What it is |
|---|---|---|---|
| `issueDate` | string |  | The day the invoice is dated (YYYY-MM-DD). Left out on a create, today. |
| `dueDate` | string or null |  | The day it is due (YYYY-MM-DD). Left out or null, the issue date plus the payment terms. |
| `paymentTermsDays` | integer |  | The net payment terms in days, 0 for due on receipt. Left out on a create, the customer's own terms. (at least 0, at most 365) |
| `paymentTermsText` | string or null |  | The payment terms in words, printed on the invoice. (max length 500) |
| `supplyPeriodStart` | string or null |  | The time of supply, when it is not the issue date: its first day (YYYY-MM-DD). It decides the VAT rate and is printed. |
| `supplyPeriodEnd` | string or null |  | The last day of the supply period (YYYY-MM-DD); left out, its first day. |
| `currency` | string |  | The ISO 4217 code the invoice is in, one of the currencies Mast offers: AUD, BGN, BRL, CAD, CHF, CNY, CZK, DKK, EUR, GBP, HKD, HRK, HUF, IDR, ILS, INR, ISK, JPY, KRW, MAD, MXN, MYR, NOK, NZD, PHP, PLN, RON, RUB, SEK, SGD, THB, TRY, USD, ZAR. Left out on a create, the company's base currency. (min length 3, max length 3) |
| `language` | one of `de`, `fr`, `it`, `en` |  | The language the invoice is written in. Left out on a create, the customer's language. |
| `reference` | string or null |  | Your customer's own reference (an order number), printed on the invoice. (max length 200) |
| `title` | string or null |  | A title printed above the lines. (max length 200) |
| `introText` | string or null |  | A text printed between the title and the lines. (max length 5000) |
| `notes` | string or null |  | A text printed under the totals. (max length 5000) |
| `footerText` | string or null |  | A text printed at the foot of the invoice. (max length 5000) |
| `priceIncludesVat` | boolean |  | True when the unit prices sent include VAT, which Mast then backs out of each line. False when left out. |
| `discountPercent` | number or null |  | A discount on the whole invoice, in percent, taken after each line's own. Not beside `discountAmount`. (at least 0, at most 100) |
| `discountAmount` | number or null |  | A discount on the whole invoice, as an amount of its currency. One above what the lines come to is not refused: it is taken as the whole of them, the invoice comes to 0.00, and it can be issued so. Not beside `discountPercent`. (at least 0, at most 999999999999.99) |
| `customerExternalRef` | string |  | The externalRef of another customer to bill the draft to. (min length 1, max length 100) |
| `lines` | list of object |  | New lines, which replace every line of the draft. A change of discount or of `priceIncludesVat` comes with them. (min items 1, max items 1000) |
| `lines[].quantity` | number | yes | How many units the line bills; below zero for a line that takes something off. Never zero. Times the unit price, at most 999999999999.99 either way. (at least -999999999999.99, at most 999999999999.99) |
| `lines[].description` | string or null |  | The line's words. Required unless the line names a product, whose name it then takes; beside a product, they follow its name. (min length 1, max length 2000) |
| `lines[].unit` | string or null |  | What the quantity counts (`h`, `pcs`). Left out, the product's unit, else `pcs`. (min length 1, max length 20) |
| `lines[].unitPrice` | number or null |  | The price of one unit, without VAT unless the invoice says `priceIncludesVat`. Required unless the line names a product, whose price it then takes as the number it is, in the invoice's currency, whatever the product's currency (nothing is converted): a price agreed with this customer is simply the price sent. (at least 0, at most 999999999999.99) |
| `lines[].discountPercent` | number or null |  | The line's own discount, in percent. (at least 0, at most 100) |
| `lines[].vatRatePercent` | number or null |  | The line's VAT rate, in percent (8.1, 2.6, 0). May be left out when `vatRateCode` names a rate, or when the line's product has one. (at least 0, at most 100) |
| `lines[].vatRateCode` | string or null |  | One of the company's VAT codes, as its VAT settings list them (`CH_STD`, `EXP_GOODS`): the line takes that rate. A `vatRatePercent` beside it must agree. (min length 1, max length 40) |
| `lines[].productExternalRef` | string or null |  | The externalRef of a product: the line is that product's, takes its name, price, unit and VAT rate where it names none, and is booked to its revenue account. Its price is taken as the number it is, in the invoice's currency: a product priced 100 in EUR gives 100.00 on an invoice in CHF, so give a line of an invoice in another currency its own `unitPrice`. (min length 1, max length 100) |
| `lines[].productCode` | string or null |  | A product code to print on the line. Left out, the product's own. (min length 1, max length 100) |
| `lines[].revenueAccountCode` | string or null |  | The number of the revenue account, in the company's chart, this line is booked to. Left out, the product's, else the company's default. (min length 1, max length 20) |
| `lines[].costCenterCode` | string or null |  | The code of one of the company's cost centres, which the line's revenue is filed under. (min length 1, max length 50) |
| `lines[].comment` | string or null |  | A note printed under the line. (max length 2000) |
| `lines[].supplyPeriodStart` | string or null |  | When this line was supplied, if not when the invoice says: its first day (YYYY-MM-DD). |
| `lines[].supplyPeriodEnd` | string or null |  | The last day of this line's own supply period (YYYY-MM-DD); left out, its first day. |

**Answers** `200` with an [Invoice](#invoice). The draft, changed.

**Refusals of its own**

| Status | Code | Meaning |
|---|---|---|
| 400 | `EXT_INVOICE_INVALID` | This invoice is not valid. The answer does not say which field Mast’s own rules refused: compare what you sent with the fields above. |
| 404 | `EXT_INVOICE_NOT_FOUND` | No invoice of the company has this reference. |
| 409 | `EXT_INVOICE_NOT_DRAFT` | This invoice is issued: only a draft is changed or deleted. An issued invoice is corrected by a credit note. |
| 422 | `EXT_INVOICE_LINES_REQUIRED` | A change of discount or of priceIncludesVat reprices the invoice: send its lines with it. |
| 422 | `EXT_INVOICE_CUSTOMER_UNKNOWN` | No customer has this customerExternalRef in the company: make it first (PUT /ext/customers/{externalRef}). |
| 422 | `EXT_INVOICE_PRODUCT_UNKNOWN` | No product has this productExternalRef in the company: make it first (PUT /ext/products/{externalRef}). |
| 422 | `EXT_INVOICE_VAT_RATE_UNKNOWN` | No VAT rate the company sells at on the invoice's day has this vatRateCode: name one of its VAT codes, or give vatRatePercent. |
| 422 | `EXT_INVOICE_VAT_RATE_MISMATCH` | vatRatePercent is not the rate vatRateCode names: send one of the two, or the two in agreement. |
| 422 | `EXT_INVOICE_VAT_RATE_MISSING` | This line names no VAT rate and its product has none of its own: give vatRatePercent or vatRateCode. |
| 422 | `EXT_INVOICE_COST_CENTER_UNKNOWN` | No cost centre of the company has this costCenterCode. |

### Drop a draft

`DELETE /ext/invoices/{externalRef}`

Right: Customer Invoices, delete · 60 calls a minute · MCP tool: `mast_delete_invoice_draft`

Deletes a draft, whose reference is then free again. An issued invoice is never deleted.

**In the path**

| Field | Type | Required | What it is |
|---|---|---|---|
| `externalRef` | string | yes | Your own id of the resource, as you gave it when you made it. (min length 1, max length 100) |

**Answers** `204`. Dropped.

**Refusals of its own**

| Status | Code | Meaning |
|---|---|---|
| 404 | `EXT_INVOICE_NOT_FOUND` | No invoice of the company has this reference. |
| 409 | `EXT_INVOICE_NOT_DRAFT` | This invoice is issued: only a draft is changed or deleted. An issued invoice is corrected by a credit note. |

### Issue a draft

`POST /ext/invoices/{externalRef}/validate`

Right: Customer Invoices, post · 60 calls a minute

Issues the invoice: it takes its official number in the company’s series and its journal entry, written under the key’s name. This cannot be undone by the API: an issued invoice is corrected by a credit note in Mast. Send an `Idempotency-Key`. The books’ own rules can refuse it (a closed period, an account the company has not mapped), with the code the app itself answers.

**In the path**

| Field | Type | Required | What it is |
|---|---|---|---|
| `externalRef` | string | yes | Your own id of the resource, as you gave it when you made it. (min length 1, max length 100) |

**Answers** `200` with an [Invoice](#invoice). The invoice, issued.

**Refusals of its own**

| Status | Code | Meaning |
|---|---|---|
| 400 | `INVOICE_TOTAL_NEGATIVE` | The lines and the discounts come to less than zero, and an invoice bills. To take an amount back from a customer, make a credit note in Mast on the invoice it corrects. For example: « Invoice has a negative total (-108.10). To take an amount back from a customer, issue a credit note on the invoice it corrects. » |
| 404 | `EXT_INVOICE_NOT_FOUND` | No invoice of the company has this reference. |

### E-mail the invoice to the customer

`POST /ext/invoices/{externalRef}/send`

Right: Customer Invoices, post · 60 calls a minute

Sends the invoice with its PDF by the sender the company chose under Settings › Email Configuration (its own Microsoft 365 mailbox, or, where the account is offered it, Mast in the company’s name), to the customer’s address unless `recipient` names another, in the words of the company’s « invoice sent » template unless `subject` and `message` are given. A draft is issued on its way out, so the call asks the right to issue. Everything that can refuse the send is checked before anything is issued. A send to the same recipients within a minute of one that went out sends nothing more and answers `deduplicated: true`; one made while another send of the invoice is still running is refused. Later, a send goes out again: send an `Idempotency-Key`.

**In the path**

| Field | Type | Required | What it is |
|---|---|---|---|
| `externalRef` | string | yes | Your own id of the resource, as you gave it when you made it. (min length 1, max length 100) |

**Body**

| Field | Type | Required | What it is |
|---|---|---|---|
| `recipient` | string (email) |  | The address the invoice goes to. Left out, the customer's e-mail address in Mast. (max length 320) |
| `ccRecipient` | string (email) |  | An address that receives a copy. (max length 320) |
| `subject` | string |  | The e-mail's subject. Left out, the subject of the company's « invoice sent » template, in the customer's language. (min length 1, max length 300) |
| `message` | string |  | The e-mail's text, plain, its line breaks kept. Left out, the text of the company's « invoice sent » template. (min length 1, max length 20000) |

**Answers** `200` with an [InvoiceSendResult](#invoicesendresult). The invoice as it stands after the send, and who it went to.

**Refusals of its own**

| Status | Code | Meaning |
|---|---|---|
| 400 | `INVOICE_CANCELLED_CANNOT_BE_SENT` | This invoice can no longer be sent or recorded as sent. Its cancellation reversed the journal entry, so nothing is owed on it. |
| 400 | `INVOICE_TOTAL_NEGATIVE` | The lines and the discounts come to less than zero, and an invoice bills. To take an amount back from a customer, make a credit note in Mast on the invoice it corrects. For example: « Invoice has a negative total (-108.10). To take an amount back from a customer, issue a credit note on the invoice it corrects. » |
| 403 | `INVOICE_EMAIL_SENDING_DISABLED_YOUR_ORGANIZATION_SETTINGS` | Invoice email sending is disabled in your organization settings. |
| 404 | `EXT_INVOICE_NOT_FOUND` | No invoice of the company has this reference. |
| 409 | `INVOICE_SEND_IN_FLIGHT` | This invoice is already being sent — wait for the send in progress to finish. |
| 409 | `EMAIL_NO_SENDER_SET_UP` | This company cannot send e-mail yet. Under Settings > Email Configuration, connect a Microsoft 365 mailbox, or let Mast send in the company's name. |
| 409 | `EMAIL_MAST_SENDER_NOT_AVAILABLE` | Sending by Mast in the company's name is not open for this account. Connect a Microsoft 365 mailbox under Settings > Email Configuration, or ask Mast to open it. |
| 409 | `EMAIL_MAST_SENDER_DEMO_ACCOUNT` | A demo or test account sends no real e-mail, so Mast cannot send its documents. |
| 409 | `EMAIL_MAST_SENDER_NO_REPLY_ADDRESS` | Mast sends in the company's name only once a reply address is set, under Settings > Email Configuration. |
| 422 | `EXT_INVOICE_NO_RECIPIENT` | The customer has no e-mail address in Mast: name the recipient. |
| 422 | `EXT_INVOICE_EMAIL_TEMPLATE_MISSING` | The company has no active « invoice sent » e-mail template: give the subject and the message. |
| 429 | `EMAIL_MAST_SENDER_DAILY_LIMIT` | Mast has sent the number of e-mails it sends for one company in a day. Sending resumes tomorrow. |
| 502 | `EXT_INVOICE_SEND_FAILED` | The company's mailbox did not send the e-mail. What the mailbox answered is not passed on: try again later, or send the PDF yourself. |
| 503 | `EMAIL_NO_ACCOUNT_CONNECTED` | No email account connected. Please connect your Microsoft 365 mailbox in Settings. |

### The invoice as a PDF

`GET /ext/invoices/{externalRef}/pdf`

Right: Customer Invoices, read · 60 calls a minute

The document as the customer receives it, with its QR-bill where the company issues one. A key gets one PDF at a time: a call while a PDF it asked for is still being made, or while Mast makes as many PDFs for the API as it makes at once, is answered `429 RATE_LIMITED` with `Retry-After`.

**In the path**

| Field | Type | Required | What it is |
|---|---|---|---|
| `externalRef` | string | yes | Your own id of the resource, as you gave it when you made it. (min length 1, max length 100) |

**Answers** `200`. The PDF file.

**Refusals of its own**

| Status | Code | Meaning |
|---|---|---|
| 404 | `EXT_INVOICE_NOT_FOUND` | No invoice of the company has this reference. |

### An invoice with its lines, by Mast’s id

`GET /ext/invoices/by-id/{id}`

Right: Customer Invoices, read · 300 calls a minute · MCP tool: `mast_get_invoice_by_id`

For an invoice made in Mast, which has no `externalRef`.

**In the path**

| Field | Type | Required | What it is |
|---|---|---|---|
| `id` | string | yes | Mast’s own id of the resource: the `id` every read returns. (min length 1, max length 100) |

**Answers** `200` with an [Invoice](#invoice). The invoice, with its lines.

**Refusals of its own**

| Status | Code | Meaning |
|---|---|---|
| 404 | `EXT_INVOICE_NOT_FOUND` | No invoice of the company has this reference. |

### The PDF of an invoice, by Mast’s id

`GET /ext/invoices/by-id/{id}/pdf`

Right: Customer Invoices, read · 60 calls a minute

A key gets one PDF at a time: a call while a PDF it asked for is still being made, or while Mast makes as many PDFs for the API as it makes at once, is answered `429 RATE_LIMITED` with `Retry-After`.

**In the path**

| Field | Type | Required | What it is |
|---|---|---|---|
| `id` | string | yes | Mast’s own id of the resource: the `id` every read returns. (min length 1, max length 100) |

**Answers** `200`. The PDF file.

**Refusals of its own**

| Status | Code | Meaning |
|---|---|---|
| 404 | `EXT_INVOICE_NOT_FOUND` | No invoice of the company has this reference. |

## Credit notes

The credit notes issued against invoices, read only.

### The credit notes changed since a moment

`GET /ext/credit-notes`

Right: Customer Credit Notes, read · 300 calls a minute · MCP tool: `mast_list_credit_notes`

The company’s credit notes, oldest change first, by `status` when asked, with their lines on `include=lines`. Their amounts are below zero, so invoices and credit notes add up to what was invoiced. Credit notes are made in Mast; the API reads them. A page ends early past 2,000 lines, counted whether or not `include=lines` asks for them (the figures are worked out from them), never inside a document: follow `nextCursor`.

**Query**

| Field | Type | Required | What it is |
|---|---|---|---|
| `updatedSince` | instant (ISO 8601) |  | An instant with its offset (`2026-11-18T08:00:00Z`): only what changed at or after it. Left out, everything. |
| `cursor` | string |  | The `nextCursor` of the page before, to read the next one; null there means the list is read to its end. A value that is no cursor, or a cursor of another list, is refused. (min length 1, max length 500) |
| `limit` | integer |  | How many rows a page holds at most: 50 when left out, never more than 100. (at least 1, at most 100, default `50`) |
| `include` | one of `lines` |  | `lines`: each document comes with its lines. Left out, `lines` is null and the page is lighter. |
| `status` | any |  | Only the documents in one of these states, separated by commas: draft, open, paid, cancelled. |

**Answers** `200`. A page of credit notes.

| Field | Type | Always there | What it is |
|---|---|---|---|
| `data` | list of [CreditNote](#creditnote) | yes | The rows of this page, oldest change first. |
| `nextCursor` | string or null | yes | Pass it back as `cursor` to read the next page. Null when there is nothing more for now. |

**Refusals of its own**

| Status | Code | Meaning |
|---|---|---|
| 400 | `EXT_CURSOR_INVALID` | This cursor is not one this list gave: start again without it. |

### A credit note with its lines, by your reference

`GET /ext/credit-notes/{externalRef}`

Right: Customer Credit Notes, read · 300 calls a minute

**In the path**

| Field | Type | Required | What it is |
|---|---|---|---|
| `externalRef` | string | yes | Your own id of the resource, as you gave it when you made it. (min length 1, max length 100) |

**Answers** `200` with a [CreditNote](#creditnote). The credit note, with its lines.

**Refusals of its own**

| Status | Code | Meaning |
|---|---|---|
| 404 | `EXT_CREDIT_NOTE_NOT_FOUND` | No credit note of the company has this reference. |

### A credit note with its lines, by Mast’s id

`GET /ext/credit-notes/by-id/{id}`

Right: Customer Credit Notes, read · 300 calls a minute · MCP tool: `mast_get_credit_note_by_id`

**In the path**

| Field | Type | Required | What it is |
|---|---|---|---|
| `id` | string | yes | Mast’s own id of the resource: the `id` every read returns. (min length 1, max length 100) |

**Answers** `200` with a [CreditNote](#creditnote). The credit note, with its lines.

**Refusals of its own**

| Status | Code | Meaning |
|---|---|---|
| 404 | `EXT_CREDIT_NOTE_NOT_FOUND` | No credit note of the company has this reference. |

## Payments

What customers paid against invoices, read only.

### The payments received, changed since a moment

`GET /ext/payments`

Right: Cash Allocation, read · 300 calls a minute · MCP tool: `mast_list_payments`

What customers paid against invoices, one row per payment: its day, its amount, its invoice, how it was recorded. `invoiceId` or `invoiceExternalRef` narrows the read to one invoice. A payment cancelled in Mast drops out of the list.

**Query**

| Field | Type | Required | What it is |
|---|---|---|---|
| `updatedSince` | instant (ISO 8601) |  | An instant with its offset (`2026-11-18T08:00:00Z`): only what changed at or after it. Left out, everything. |
| `cursor` | string |  | The `nextCursor` of the page before, to read the next one; null there means the list is read to its end. A value that is no cursor, or a cursor of another list, is refused. (min length 1, max length 500) |
| `limit` | integer |  | How many rows a page holds at most: 50 when left out, never more than 100. (at least 1, at most 100, default `50`) |
| `invoiceId` | string |  | Only the payments of this invoice, by Mast's id of it. (min length 1, max length 100) |
| `invoiceExternalRef` | string |  | Only the payments of this invoice, by your own reference of it. (min length 1, max length 100) |

**Answers** `200`. A page of payments.

| Field | Type | Always there | What it is |
|---|---|---|---|
| `data` | list of [Payment](#payment) | yes | The rows of this page, oldest change first. |
| `nextCursor` | string or null | yes | Pass it back as `cursor` to read the next page. Null when there is nothing more for now. |

**Refusals of its own**

| Status | Code | Meaning |
|---|---|---|
| 400 | `EXT_CURSOR_INVALID` | This cursor is not one this list gave: start again without it. |
| 404 | `EXT_INVOICE_NOT_FOUND` | No invoice of the company has this reference. |

## Accounting

The chart of accounts, the journal and the trial balance, read only.

### The chart of accounts

`GET /ext/accounts`

Right: Chart of Accounts, read · 300 calls a minute · MCP tool: `mast_list_accounts`

The accounts and headings of the chart changed since a moment, oldest change first. A small chart fits one or two pages.

**Query**

| Field | Type | Required | What it is |
|---|---|---|---|
| `updatedSince` | instant (ISO 8601) |  | An instant, ISO 8601 with its offset (2026-11-19T06:00:00Z). Only the accounts and headings changed at or after it are served, oldest change first. Left out: all of them. |
| `cursor` | string |  | The nextCursor of the page before, to read the page after it. Left out: the first page. A value that is no cursor, or a cursor of another list, is refused. (min length 1, max length 500) |
| `limit` | integer |  | How many rows a page holds at most, 1 to 100. Left out: 50. (at least 1, at most 100, default `50`) |

**Answers** `200`. A page of accounts.

| Field | Type | Always there | What it is |
|---|---|---|---|
| `data` | list of [Account](#account) | yes | The rows of this page, oldest change first. |
| `nextCursor` | string or null | yes | Pass it back as `cursor` to read the next page. Null when there is nothing more for now. |

**Refusals of its own**

| Status | Code | Meaning |
|---|---|---|
| 400 | `EXT_CURSOR_INVALID` | This cursor is not one this list gave: start again without it. |

### Journal entries, with their lines

`GET /ext/journal-entries`

Right: Journal Entries, read · 300 calls a minute · MCP tool: `mast_list_journal_entries`

The booked entries posted or reversed since a moment, each with all its lines, oldest change first. A posted entry never changes; when it is reversed it comes again, marked `reversed`, and the entry that takes it back comes as a new one. `from`, `to` and `accountCode` narrow the read. A page ends early past 5,000 lines.

**Query**

| Field | Type | Required | What it is |
|---|---|---|---|
| `updatedSince` | instant (ISO 8601) |  | An instant, ISO 8601 with its offset (2026-11-19T06:00:00Z). Only the journal entries posted or reversed at or after it are served, oldest change first. Left out: all of them. |
| `cursor` | string |  | The nextCursor of the page before, to read the page after it. Left out: the first page. A value that is no cursor, or a cursor of another list, is refused. (min length 1, max length 500) |
| `limit` | integer |  | How many rows a page holds at most, 1 to 100. Left out: 50. (at least 1, at most 100, default `50`) |
| `from` | string |  | A day, YYYY-MM-DD. Only the entries dated on or after it are served. |
| `to` | string |  | A day, YYYY-MM-DD, on or after from. Only the entries dated on or before it are served. |
| `accountCode` | string |  | The code of an account of the chart. Only the entries with a line on it are served, each with all its lines. (min length 1, max length 128) |

**Answers** `200`. A page of entries.

| Field | Type | Always there | What it is |
|---|---|---|---|
| `data` | list of [JournalEntry](#journalentry) | yes | The rows of this page, oldest change first. |
| `nextCursor` | string or null | yes | Pass it back as `cursor` to read the next page. Null when there is nothing more for now. |

**Refusals of its own**

| Status | Code | Meaning |
|---|---|---|
| 400 | `EXT_CURSOR_INVALID` | This cursor is not one this list gave: start again without it. |
| 422 | `EXT_JOURNAL_ENTRY_ACCOUNT_UNKNOWN` | No account of the company's chart has this accountCode. |

### The trial balance between two days

`GET /ext/trial-balance`

Right: Financial Statement, read · 60 calls a minute · MCP tool: `mast_get_trial_balance`

Per account: what it held when the period starts, the period’s debits and credits, and what it holds on its last day, in the base currency. Computed by the service behind Mast’s own Trial Balance, so the figures are the ones the app shows for the same days.

**Query**

| Field | Type | Required | What it is |
|---|---|---|---|
| `from` | string | yes | The period's first day, YYYY-MM-DD. |
| `to` | string | yes | The period's last day, YYYY-MM-DD, on or after from. |
| `closingPeriod` | one of `true`, `false` |  | true for the year-end closing view: only the entries booked in the closing period are its movements, and it ends on the closed position. false or left out: the operating view, which leaves out the closing period of the fiscal year it ends in. |

**Answers** `200` with a [TrialBalance](#trialbalance). The trial balance.

## Banking

Bank accounts and their lines, read only.

### Bank accounts, with their balances

`GET /ext/bank-accounts`

Right: Bank Accounts, read · 300 calls a minute · MCP tool: `mast_list_bank_accounts`

**Query**

| Field | Type | Required | What it is |
|---|---|---|---|
| `updatedSince` | instant (ISO 8601) |  | An instant, ISO 8601 with its offset (2026-11-19T06:00:00Z). Only the bank accounts changed at or after it are served, oldest change first. Left out: all of them. |
| `cursor` | string |  | The nextCursor of the page before, to read the page after it. Left out: the first page. A value that is no cursor, or a cursor of another list, is refused. (min length 1, max length 500) |
| `limit` | integer |  | How many rows a page holds at most, 1 to 100. Left out: 50. (at least 1, at most 100, default `50`) |

**Answers** `200`. A page of bank accounts.

| Field | Type | Always there | What it is |
|---|---|---|---|
| `data` | list of [BankAccount](#bankaccount) | yes | The rows of this page, oldest change first. |
| `nextCursor` | string or null | yes | Pass it back as `cursor` to read the next page. Null when there is nothing more for now. |

**Refusals of its own**

| Status | Code | Meaning |
|---|---|---|
| 400 | `EXT_CURSOR_INVALID` | This cursor is not one this list gave: start again without it. |
| 403 | `EXT_BANK_DATA_TWO_FACTOR_ACCOUNT` | This account requires two-step verification at sign-in, which an API key cannot give: its bank accounts and bank lines are not served to a key. Every other call of the API answers. |

### Bank lines

`GET /ext/bank-transactions`

Right: Bank Statement, read · 300 calls a minute · MCP tool: `mast_list_bank_transactions`

The lines of the company’s bank accounts changed since a moment, oldest change first. `bankAccountId`, `from` and `to` narrow the read. A line changes when it is reconciled, excluded or parked, and comes again then.

**Query**

| Field | Type | Required | What it is |
|---|---|---|---|
| `updatedSince` | instant (ISO 8601) |  | An instant, ISO 8601 with its offset (2026-11-19T06:00:00Z). Only the bank lines changed at or after it are served, oldest change first. Left out: all of them. |
| `cursor` | string |  | The nextCursor of the page before, to read the page after it. Left out: the first page. A value that is no cursor, or a cursor of another list, is refused. (min length 1, max length 500) |
| `limit` | integer |  | How many rows a page holds at most, 1 to 100. Left out: 50. (at least 1, at most 100, default `50`) |
| `from` | string |  | A day, YYYY-MM-DD. Only the lines booked on or after it are served. |
| `to` | string |  | A day, YYYY-MM-DD, on or after from. Only the lines booked on or before it are served. |
| `bankAccountId` | string |  | The id of a bank account of the company (GET /ext/bank-accounts). Only its lines are served. (min length 1, max length 128) |

**Answers** `200`. A page of bank lines.

| Field | Type | Always there | What it is |
|---|---|---|---|
| `data` | list of [BankTransaction](#banktransaction) | yes | The rows of this page, oldest change first. |
| `nextCursor` | string or null | yes | Pass it back as `cursor` to read the next page. Null when there is nothing more for now. |

**Refusals of its own**

| Status | Code | Meaning |
|---|---|---|
| 400 | `EXT_CURSOR_INVALID` | This cursor is not one this list gave: start again without it. |
| 403 | `EXT_BANK_DATA_TWO_FACTOR_ACCOUNT` | This account requires two-step verification at sign-in, which an API key cannot give: its bank accounts and bank lines are not served to a key. Every other call of the API answers. |
| 422 | `EXT_BANK_TRANSACTION_ACCOUNT_UNKNOWN` | No bank account of the company has this bankAccountId. |

## Purchases

Suppliers, addressed by the back office’s own reference, and their bills, read only.

### Suppliers

`GET /ext/suppliers`

Right: Supplier, read · 300 calls a minute · MCP tool: `mast_list_suppliers`

The company’s suppliers changed since a moment, yours and the ones people made in Mast (`externalRef` null), oldest change first. A deleted supplier drops out of the list.

**Query**

| Field | Type | Required | What it is |
|---|---|---|---|
| `updatedSince` | instant (ISO 8601) |  | An instant, ISO 8601 with its offset (2026-11-19T06:00:00Z). Only the suppliers changed at or after it are served, oldest change first. Left out: all of them. |
| `cursor` | string |  | The nextCursor of the page before, to read the page after it. Left out: the first page. A value that is no cursor, or a cursor of another list, is refused. (min length 1, max length 500) |
| `limit` | integer |  | How many rows a page holds at most, 1 to 100. Left out: 50. (at least 1, at most 100, default `50`) |

**Answers** `200`. A page of suppliers.

| Field | Type | Always there | What it is |
|---|---|---|---|
| `data` | list of [Supplier](#supplier) | yes | The rows of this page, oldest change first. |
| `nextCursor` | string or null | yes | Pass it back as `cursor` to read the next page. Null when there is nothing more for now. |

**Refusals of its own**

| Status | Code | Meaning |
|---|---|---|
| 400 | `EXT_CURSOR_INVALID` | This cursor is not one this list gave: start again without it. |

### Make a supplier

`POST /ext/suppliers`

Right: Supplier, create · 60 calls a minute

Makes a supplier under your own id. To make it or change it in one call whatever its state, use `PUT /ext/suppliers/{externalRef}`. Mast’s own rules on the VAT status refuse a number its country does not write, a registered supplier without one, and a number beside a status that takes none, each 400 under a code of its own (`SUPPLIER_CH_VAT_NUMBER_REQUIRED`, `SUPPLIER_CH_VAT_NUMBER_FORMAT`, `SUPPLIER_CH_VAT_NUMBER_FORBIDDEN`, and their like). No call writes the supplier’s bank account, its accounting defaults, its categories or its blacklist mark: a field naming one is dropped, and what the supplier held stays as it was.

**Body**

| Field | Type | Required | What it is |
|---|---|---|---|
| `externalRef` | string | yes | The id your own system gives the resource. Unique per company for each kind of resource. Mast stores it as you send it, less the spaces around it (`crm-1042 ` is `crm-1042`) and any NUL character, which Mast takes out of every text of a body (in a path, a NUL is refused). (min length 1, max length 100) |
| `name` | string | yes | The supplier's name: what its bills, the payment runs and Mast's lists show. Two live suppliers of a company never share one. (min length 1, max length 200) |
| `vatStatus` | one of `registered`, `foreign_registered`, `foreign_not_registered`, `not_registered` | yes | Its VAT standing in the VAT territory of the company's own country: `registered` (registered there, from inside it), `foreign_registered` (registered there, from abroad), `foreign_not_registered` (abroad, not registered there) or `not_registered` (inside it, not registered). The first two take `vatNumber` and require it, the last two refuse one. `unknown`, which a read answers for a supplier saved before Mast asked for the status, is never written. |
| `businessType` | one of `corporation_company`, `sole_proprietorship`, `nonprofit_association`, `government_public`, `other` |  | Its legal form: `corporation_company` (a company), `sole_proprietorship`, `nonprofit_association`, `government_public` (an administration) or `other`. Left out of a create, `corporation_company`. |
| `address` | object |  | Where the supplier is. A part left out stays as it is. |
| `address.street` | string or null |  | Street and number, on one line. Null or an empty string removes it. (max length 200) |
| `address.postalCode` | string or null |  | Null or an empty string removes it. (max length 20) |
| `address.city` | string or null |  | Null or an empty string removes it. (max length 100) |
| `address.country` | string or null |  | The country's name, as the supplier's card in Mast writes it ("France", "Germany"). Left out of a create, or null there, the company's own country; left out of a change, or null, the one the supplier holds. (min length 1, max length 100) |
| `registrationNumber` | string or null |  | Its number in the commercial register (a UID, or a foreign registry's id), as you record it. Null or an empty string removes it. (max length 100) |
| `email` | string (email) or null |  | The address its correspondence goes to. Null removes it. (max length 254) |
| `phone` | string or null |  | Its phone number in its international form, + and its country calling code first (`+41 44 000 00 00`). Mast keeps it without spaces (`+41440000000`) and serves it so. Null or an empty string removes it. (max length 30) |
| `vatNumber` | string or null |  | Its VAT number in the VAT territory of the company's own country, in any spelling that country writes it in (`CHE-123.456.789 MWST`): Mast checks it as that country does, keeps it compact and serves it so (`CHE123456789`). With `registered` and `foreign_registered` only. Null or an empty string removes it. (max length 40) |
| `foreignTaxId` | string or null |  | A supplier's own tax id in its country abroad (`DE123456789`). Null or an empty string removes it. (max length 40) |
| `foreignTaxIdCountry` | string or null |  | The country that gave `foreignTaxId`, ISO 3166-1 alpha-2 (`DE`). Null removes it. |
| `currency` | string |  | The ISO 4217 code its bills default to, one of the currencies Mast offers: AUD, BGN, BRL, CAD, CHF, CNY, CZK, DKK, EUR, GBP, HKD, HRK, HUF, IDR, ILS, INR, ISK, JPY, KRW, MAD, MXN, MYR, NOK, NZD, PHP, PLN, RON, RUB, SEK, SGD, THB, TRY, USD, ZAR. Left out of a create, the company's base currency. (min length 3, max length 3) |
| `paymentTermsDays` | number |  | Its net payment terms in whole days, 0 for due on receipt. 30 when a create leaves them out. |

**Answers** `201` with a [Supplier](#supplier). The supplier made.

**Refusals of its own**

| Status | Code | Meaning |
|---|---|---|
| 400 | `EXT_SUPPLIER_INVALID` | This supplier is not valid. The answer does not say which field Mast’s own rules refused: compare what you sent with the fields above. |
| 409 | `EXT_SUPPLIER_EXISTS` | A supplier with this externalRef already exists in the company: update it with PATCH or PUT. |
| 409 | `EXT_SUPPLIER_ARCHIVED` | The supplier with this externalRef was archived in Mast: restore it there, or use another reference. |
| 409 | `SUPPLIER_NAME_EXISTS` | If that supplier was made in Mast, give it your reference with `PATCH /ext/suppliers/by-id/{id}` rather than making a second one. For example: « A supplier named "Muster Bureau AG" already exists. Give this one a different name, or edit the existing entry. » |
| 409 | `SUPPLIER_EMAIL_EXISTS` | Another supplier of the company has this e-mail address. For example: « Supplier with email compta@muster-bureau.example already exists » |
| 409 | `SUPPLIER_PHONE_EXISTS` | Another supplier of the company has this phone number. For example: « Supplier with phone +41440000000 already exists » |

### A supplier, by your reference

`GET /ext/suppliers/{externalRef}`

Right: Supplier, read · 300 calls a minute · MCP tool: `mast_get_supplier`

**In the path**

| Field | Type | Required | What it is |
|---|---|---|---|
| `externalRef` | string | yes | Your own id of the resource, as you gave it when you made it. (min length 1, max length 100) |

**Answers** `200` with a [Supplier](#supplier). The supplier.

**Refusals of its own**

| Status | Code | Meaning |
|---|---|---|
| 404 | `EXT_SUPPLIER_NOT_FOUND` | No supplier of the company has this reference. |

### Make or change a supplier

`PUT /ext/suppliers/{externalRef}`

Right: Supplier, edit and create · 60 calls a minute · MCP tool: `mast_save_supplier`

The call a sync makes: when the company has no supplier under this reference it is made, and the body must then hold what a creation needs (name, VAT status); else the fields given are changed and the others stay. Safe to repeat. Mast’s own rules on the VAT status refuse a number its country does not write, a registered supplier without one, and a number beside a status that takes none, each 400 under a code of its own (`SUPPLIER_CH_VAT_NUMBER_REQUIRED`, `SUPPLIER_CH_VAT_NUMBER_FORMAT`, `SUPPLIER_CH_VAT_NUMBER_FORBIDDEN`, and their like). No call writes the supplier’s bank account, its accounting defaults, its categories or its blacklist mark: a field naming one is dropped, and what the supplier held stays as it was.

**In the path**

| Field | Type | Required | What it is |
|---|---|---|---|
| `externalRef` | string | yes | Your own id of the resource, as you gave it when you made it. (min length 1, max length 100) |

**Body**

| Field | Type | Required | What it is |
|---|---|---|---|
| `name` | string |  | The supplier's name: what its bills, the payment runs and Mast's lists show. Two live suppliers of a company never share one. (min length 1, max length 200) |
| `vatStatus` | one of `registered`, `foreign_registered`, `foreign_not_registered`, `not_registered` |  | Its VAT standing in the VAT territory of the company's own country: `registered` (registered there, from inside it), `foreign_registered` (registered there, from abroad), `foreign_not_registered` (abroad, not registered there) or `not_registered` (inside it, not registered). The first two take `vatNumber` and require it, the last two refuse one. `unknown`, which a read answers for a supplier saved before Mast asked for the status, is never written. |
| `businessType` | one of `corporation_company`, `sole_proprietorship`, `nonprofit_association`, `government_public`, `other` |  | Its legal form: `corporation_company` (a company), `sole_proprietorship`, `nonprofit_association`, `government_public` (an administration) or `other`. Left out of a create, `corporation_company`. |
| `address` | object |  | Where the supplier is. A part left out stays as it is. |
| `address.street` | string or null |  | Street and number, on one line. Null or an empty string removes it. (max length 200) |
| `address.postalCode` | string or null |  | Null or an empty string removes it. (max length 20) |
| `address.city` | string or null |  | Null or an empty string removes it. (max length 100) |
| `address.country` | string or null |  | The country's name, as the supplier's card in Mast writes it ("France", "Germany"). Left out of a create, or null there, the company's own country; left out of a change, or null, the one the supplier holds. (min length 1, max length 100) |
| `registrationNumber` | string or null |  | Its number in the commercial register (a UID, or a foreign registry's id), as you record it. Null or an empty string removes it. (max length 100) |
| `email` | string (email) or null |  | The address its correspondence goes to. Null removes it. (max length 254) |
| `phone` | string or null |  | Its phone number in its international form, + and its country calling code first (`+41 44 000 00 00`). Mast keeps it without spaces (`+41440000000`) and serves it so. Null or an empty string removes it. (max length 30) |
| `vatNumber` | string or null |  | Its VAT number in the VAT territory of the company's own country, in any spelling that country writes it in (`CHE-123.456.789 MWST`): Mast checks it as that country does, keeps it compact and serves it so (`CHE123456789`). With `registered` and `foreign_registered` only. Null or an empty string removes it. (max length 40) |
| `foreignTaxId` | string or null |  | A supplier's own tax id in its country abroad (`DE123456789`). Null or an empty string removes it. (max length 40) |
| `foreignTaxIdCountry` | string or null |  | The country that gave `foreignTaxId`, ISO 3166-1 alpha-2 (`DE`). Null removes it. |
| `currency` | string |  | The ISO 4217 code its bills default to, one of the currencies Mast offers: AUD, BGN, BRL, CAD, CHF, CNY, CZK, DKK, EUR, GBP, HKD, HRK, HUF, IDR, ILS, INR, ISK, JPY, KRW, MAD, MXN, MYR, NOK, NZD, PHP, PLN, RON, RUB, SEK, SGD, THB, TRY, USD, ZAR. Left out of a create, the company's base currency. (min length 3, max length 3) |
| `paymentTermsDays` | number |  | Its net payment terms in whole days, 0 for due on receipt. 30 when a create leaves them out. |

**Answers** `200` with a [Supplier](#supplier). The supplier, changed. Answers `201` with the same body when it makes it: The reference was new: the supplier was made.

**Refusals of its own**

| Status | Code | Meaning |
|---|---|---|
| 400 | `EXT_SUPPLIER_INVALID` | This supplier is not valid. The answer does not say which field Mast’s own rules refused: compare what you sent with the fields above. |
| 409 | `EXT_SUPPLIER_ARCHIVED` | The supplier with this externalRef was archived in Mast: restore it there, or use another reference. |
| 409 | `SUPPLIER_NAME_EXISTS` | If that supplier was made in Mast, give it your reference with `PATCH /ext/suppliers/by-id/{id}` rather than making a second one. For example: « A supplier named "Muster Bureau AG" already exists. Give this one a different name, or edit the existing entry. » |
| 409 | `SUPPLIER_EMAIL_EXISTS` | Another supplier of the company has this e-mail address. For example: « Supplier with email compta@muster-bureau.example already exists » |
| 409 | `SUPPLIER_PHONE_EXISTS` | Another supplier of the company has this phone number. For example: « Supplier with phone +41440000000 already exists » |
| 422 | `EXT_SUPPLIER_INCOMPLETE` | No supplier has this externalRef yet, and making one takes its name and its VAT status. |

### Change a supplier

`PATCH /ext/suppliers/{externalRef}`

Right: Supplier, edit · 60 calls a minute

Changes the fields given; a field left out stays as it is. Mast’s own rules on the VAT status refuse a number its country does not write, a registered supplier without one, and a number beside a status that takes none, each 400 under a code of its own (`SUPPLIER_CH_VAT_NUMBER_REQUIRED`, `SUPPLIER_CH_VAT_NUMBER_FORMAT`, `SUPPLIER_CH_VAT_NUMBER_FORBIDDEN`, and their like). No call writes the supplier’s bank account, its accounting defaults, its categories or its blacklist mark: a field naming one is dropped, and what the supplier held stays as it was.

**In the path**

| Field | Type | Required | What it is |
|---|---|---|---|
| `externalRef` | string | yes | Your own id of the resource, as you gave it when you made it. (min length 1, max length 100) |

**Body**

| Field | Type | Required | What it is |
|---|---|---|---|
| `name` | string |  | The supplier's name: what its bills, the payment runs and Mast's lists show. Two live suppliers of a company never share one. (min length 1, max length 200) |
| `vatStatus` | one of `registered`, `foreign_registered`, `foreign_not_registered`, `not_registered` |  | Its VAT standing in the VAT territory of the company's own country: `registered` (registered there, from inside it), `foreign_registered` (registered there, from abroad), `foreign_not_registered` (abroad, not registered there) or `not_registered` (inside it, not registered). The first two take `vatNumber` and require it, the last two refuse one. `unknown`, which a read answers for a supplier saved before Mast asked for the status, is never written. |
| `businessType` | one of `corporation_company`, `sole_proprietorship`, `nonprofit_association`, `government_public`, `other` |  | Its legal form: `corporation_company` (a company), `sole_proprietorship`, `nonprofit_association`, `government_public` (an administration) or `other`. Left out of a create, `corporation_company`. |
| `address` | object |  | Where the supplier is. A part left out stays as it is. |
| `address.street` | string or null |  | Street and number, on one line. Null or an empty string removes it. (max length 200) |
| `address.postalCode` | string or null |  | Null or an empty string removes it. (max length 20) |
| `address.city` | string or null |  | Null or an empty string removes it. (max length 100) |
| `address.country` | string or null |  | The country's name, as the supplier's card in Mast writes it ("France", "Germany"). Left out of a create, or null there, the company's own country; left out of a change, or null, the one the supplier holds. (min length 1, max length 100) |
| `registrationNumber` | string or null |  | Its number in the commercial register (a UID, or a foreign registry's id), as you record it. Null or an empty string removes it. (max length 100) |
| `email` | string (email) or null |  | The address its correspondence goes to. Null removes it. (max length 254) |
| `phone` | string or null |  | Its phone number in its international form, + and its country calling code first (`+41 44 000 00 00`). Mast keeps it without spaces (`+41440000000`) and serves it so. Null or an empty string removes it. (max length 30) |
| `vatNumber` | string or null |  | Its VAT number in the VAT territory of the company's own country, in any spelling that country writes it in (`CHE-123.456.789 MWST`): Mast checks it as that country does, keeps it compact and serves it so (`CHE123456789`). With `registered` and `foreign_registered` only. Null or an empty string removes it. (max length 40) |
| `foreignTaxId` | string or null |  | A supplier's own tax id in its country abroad (`DE123456789`). Null or an empty string removes it. (max length 40) |
| `foreignTaxIdCountry` | string or null |  | The country that gave `foreignTaxId`, ISO 3166-1 alpha-2 (`DE`). Null removes it. |
| `currency` | string |  | The ISO 4217 code its bills default to, one of the currencies Mast offers: AUD, BGN, BRL, CAD, CHF, CNY, CZK, DKK, EUR, GBP, HKD, HRK, HUF, IDR, ILS, INR, ISK, JPY, KRW, MAD, MXN, MYR, NOK, NZD, PHP, PLN, RON, RUB, SEK, SGD, THB, TRY, USD, ZAR. Left out of a create, the company's base currency. (min length 3, max length 3) |
| `paymentTermsDays` | number |  | Its net payment terms in whole days, 0 for due on receipt. 30 when a create leaves them out. |

**Answers** `200` with a [Supplier](#supplier). The supplier, changed.

**Refusals of its own**

| Status | Code | Meaning |
|---|---|---|
| 400 | `EXT_SUPPLIER_INVALID` | This supplier is not valid. The answer does not say which field Mast’s own rules refused: compare what you sent with the fields above. |
| 404 | `EXT_SUPPLIER_NOT_FOUND` | No supplier of the company has this reference. |
| 409 | `SUPPLIER_NAME_EXISTS` | If that supplier was made in Mast, give it your reference with `PATCH /ext/suppliers/by-id/{id}` rather than making a second one. For example: « A supplier named "Muster Bureau AG" already exists. Give this one a different name, or edit the existing entry. » |
| 409 | `SUPPLIER_EMAIL_EXISTS` | Another supplier of the company has this e-mail address. For example: « Supplier with email compta@muster-bureau.example already exists » |
| 409 | `SUPPLIER_PHONE_EXISTS` | Another supplier of the company has this phone number. For example: « Supplier with phone +41440000000 already exists » |

### A supplier, by Mast’s id

`GET /ext/suppliers/by-id/{id}`

Right: Supplier, read · 300 calls a minute

For a supplier made in Mast, which has no `externalRef` until you give it one.

**In the path**

| Field | Type | Required | What it is |
|---|---|---|---|
| `id` | string | yes | Mast’s own id of the resource: the `id` every read returns. (min length 1, max length 100) |

**Answers** `200` with a [Supplier](#supplier). The supplier.

**Refusals of its own**

| Status | Code | Meaning |
|---|---|---|
| 404 | `EXT_SUPPLIER_NOT_FOUND` | No supplier of the company has this reference. |

### Give a supplier your reference, by Mast’s id

`PATCH /ext/suppliers/by-id/{id}`

Right: Supplier, edit · 60 calls a minute

For a supplier that is already in Mast with no `externalRef`, because a person made or imported it there. The call gives it your own id: `PUT /ext/suppliers/{externalRef}` then finds that supplier and changes it. It also changes the reference a supplier holds, and `null` takes it away. The reference it already holds changes nothing. No other field is changed here: once the supplier holds your reference, change it by that.

**In the path**

| Field | Type | Required | What it is |
|---|---|---|---|
| `id` | string | yes | Mast’s own id of the resource: the `id` every read returns. (min length 1, max length 100) |

**Body**

| Field | Type | Required | What it is |
|---|---|---|---|
| `externalRef` | string or null | yes | Your own id for this supplier: from then on it is addressed by it (`/ext/suppliers/{externalRef}`). Unique per company. Null takes away the one it holds. (min length 1, max length 100) |

**Answers** `200` with a [Supplier](#supplier). The supplier, with the reference it now holds.

**Refusals of its own**

| Status | Code | Meaning |
|---|---|---|
| 404 | `EXT_SUPPLIER_NOT_FOUND` | No supplier of the company has this reference. |
| 409 | `EXT_SUPPLIER_EXISTS` | A supplier with this externalRef already exists in the company: update it with PATCH or PUT. |
| 409 | `EXT_SUPPLIER_ARCHIVED` | The supplier with this externalRef was archived in Mast: restore it there, or use another reference. |

### Supplier bills, with their lines

`GET /ext/bills`

Right: Supplier Bills, read · 300 calls a minute · MCP tool: `mast_list_bills`

The bills and suppliers’ credit notes the Bills page lists, changed since a moment, each with its lines: status, days, amounts, what is paid and what is owed. An expense claim is never served. `from` and `to` narrow the read by invoice date. A page ends early past 2,000 lines, never inside a bill: follow `nextCursor`.

**Query**

| Field | Type | Required | What it is |
|---|---|---|---|
| `updatedSince` | instant (ISO 8601) |  | An instant, ISO 8601 with its offset (2026-11-19T06:00:00Z). Only the supplier bills and credit notes changed at or after it are served, oldest change first. Left out: all of them. |
| `cursor` | string |  | The nextCursor of the page before, to read the page after it. Left out: the first page. A value that is no cursor, or a cursor of another list, is refused. (min length 1, max length 500) |
| `limit` | integer |  | How many rows a page holds at most, 1 to 100. Left out: 50. (at least 1, at most 100, default `50`) |
| `from` | string |  | A day, YYYY-MM-DD. Only the bills dated (their invoice date) on or after it are served. |
| `to` | string |  | A day, YYYY-MM-DD, on or after from. Only the bills dated (their invoice date) on or before it are served. |

**Answers** `200`. A page of bills.

| Field | Type | Always there | What it is |
|---|---|---|---|
| `data` | list of [Bill](#bill) | yes | The rows of this page, oldest change first. |
| `nextCursor` | string or null | yes | Pass it back as `cursor` to read the next page. Null when there is nothing more for now. |

**Refusals of its own**

| Status | Code | Meaning |
|---|---|---|
| 400 | `EXT_CURSOR_INVALID` | This cursor is not one this list gave: start again without it. |

## Shapes

What the calls above answer. A field marked « always there » is never left out; one that has no value is `null`.

### Account

An account of the chart, or one of its headings (`isGroup`).

| Field | Type | Always there | What it is |
|---|---|---|---|
| `id` | string | yes |  |
| `code` | string | yes | Unique in the chart: the key journal lines and the trial balance name an account by. |
| `name` | string | yes | In the company’s accounting language (`GET /ext/company`). |
| `type` | one of `asset`, `liability`, `equity`, `revenue`, `expense` | yes |  |
| `category` | string | yes | The chart’s category (`current_assets`, `operating_expenses`, …). |
| `isGroup` | boolean | yes | A heading that sums the accounts under it; it takes no line. |
| `parentCode` | string or null | yes | The code of the heading it sits under. |
| `isActive` | boolean | yes |  |
| `currency` | string | yes | ISO 4217: the currency the account is kept in. Its ledger figures stay in the base currency. |
| `isBankOrCash` | boolean | yes | A bank or cash account. |
| `subledger` | one of `customer`, `supplier`, `employee`, or null | yes | Whose balances the account is kept by: a receivables account tracks customers, a payables account suppliers. Null for none. |
| `systemRoles` | list of string | yes | The roles Mast books by that are mapped to this account (`vat_output_standard`, `current_year_result`, …), as of the read. |
| `createdAt` | instant (ISO 8601) | yes |  |
| `updatedAt` | instant (ISO 8601) | yes |  |

### BankAccount

A bank account of the company.

| Field | Type | Always there | What it is |
|---|---|---|---|
| `id` | string | yes |  |
| `name` | string | yes |  |
| `bankName` | string | yes |  |
| `accountHolder` | string or null | yes |  |
| `iban` | string or null | yes |  |
| `bic` | string or null | yes |  |
| `currency` | string | yes | ISO 4217: the currency the account is held in. |
| `type` | string or null | yes | `bank_account`, `credit_card`, … as the company filed it. |
| `status` | one of `active`, `suspended`, `closed` | yes |  |
| `ledgerAccountCode` | string or null | yes | The ledger account its lines are booked on (`GET /ext/accounts`). |
| `statementBalance` | number or null | yes | The closing balance of the latest statement Mast holds, in `currency`. |
| `statementBalanceDate` | day (YYYY-MM-DD) or null | yes | The day of that statement balance. |
| `computedBalance` | number or null | yes | The opening balance plus every movement Mast holds, in `currency`, as of the read: it also counts lines booked after the latest statement. |
| `latestTransactionDate` | day (YYYY-MM-DD) or null | yes | The booking day of the account’s latest line. |
| `createdAt` | instant (ISO 8601) | yes |  |
| `updatedAt` | instant (ISO 8601) | yes |  |

### BankTransaction

A line of a bank account.

| Field | Type | Always there | What it is |
|---|---|---|---|
| `id` | string | yes |  |
| `bankAccountId` | string | yes |  |
| `bookingDate` | day (YYYY-MM-DD) | yes |  |
| `valueDate` | day (YYYY-MM-DD) or null | yes |  |
| `amount` | number | yes | Always positive; `direction` says which way the money went. |
| `direction` | one of `in`, `out` | yes |  |
| `currency` | string | yes |  |
| `amountInBaseCurrency` | number or null | yes | `amount` in the company’s base currency; null when no rate could convert it. |
| `counterpartyName` | string or null | yes |  |
| `counterpartyAccount` | string or null | yes |  |
| `reference` | string or null | yes | The reference a person reads on the line in Mast. |
| `text` | string or null | yes | The line’s own text, as the bank wrote it. |
| `status` | one of `booked`, `pending`, `cancelled` | yes | The bank’s state of the movement. |
| `reconciliation` | one of `unreconciled`, `reconciled`, `partially_matched`, `excluded`, `parked` | yes | Where the line stands in the books. |
| `exclusion` | one of `duplicate`, `no_booking_needed`, `import`, or null | yes | How an excluded line was set aside: a person’s « Duplicate » or « No booking needed », or by an import. |
| `countsAsMovement` | boolean | yes | False for a duplicate of another line: no balance of Mast counts it. |
| `journalEntryId` | string or null | yes | The journal entry that books the line (`GET /ext/journal-entries`). |
| `createdAt` | instant (ISO 8601) | yes |  |
| `updatedAt` | instant (ISO 8601) | yes |  |

### Bill

A supplier’s bill, or a supplier’s credit note, with its lines.

| Field | Type | Always there | What it is |
|---|---|---|---|
| `id` | string | yes |  |
| `type` | one of `bill`, `credit_note` | yes |  |
| `number` | string | yes | Mast’s own number for the document. |
| `supplierInvoiceNumber` | string or null | yes | The number the supplier gave it. |
| `status` | string | yes | `inbox`, `draft`, `pending_approval`, `disputed`, `approved`, `submitted`, `posted`, `in_payment`, `payment_processed`, `partially_paid`, `paid`, `overdue`, `cancelled`, `reversed`. |
| `supplierId` | string or null | yes | The `id` of `GET /ext/suppliers`; null for a bill not filed under a supplier yet. |
| `invoiceDate` | day (YYYY-MM-DD) | yes |  |
| `bookingDate` | day (YYYY-MM-DD) or null | yes | The day it is booked on, when that is not its own date. |
| `dueDate` | day (YYYY-MM-DD) or null | yes |  |
| `currency` | string | yes |  |
| `exchangeRate` | number or null | yes | Base currency per unit of `currency`, as stored: indicative until the bill is booked, the booked rate after. Null in the base currency, and for a foreign bill no rate was found for. |
| `netAmount` | number | yes | In `currency`. |
| `vatAmount` | number | yes |  |
| `total` | number | yes |  |
| `amountPaid` | number | yes |  |
| `amountDue` | number | yes |  |
| `netAmountInBaseCurrency` | number or null | yes | `netAmount` in the company’s base currency, at `exchangeRate`; null for a foreign bill with no rate, never converted at 1 to 1. |
| `totalInBaseCurrency` | number or null | yes |  |
| `isReverseCharge` | boolean | yes | The company assesses the VAT on itself: it owes the supplier the net amount. |
| `isOpeningItem` | boolean | yes | An open payable a migration brought over: its amounts are what was still owed then, and the opening balance carries it. |
| `journalEntryId` | string or null | yes | The journal entry that books it (`GET /ext/journal-entries`). |
| `createdAt` | instant (ISO 8601) | yes |  |
| `updatedAt` | instant (ISO 8601) | yes |  |
| `lines` | list of [BillLine](#billline) | yes |  |

### BillLine

A line of a supplier’s bill.

| Field | Type | Always there | What it is |
|---|---|---|---|
| `lineNumber` | integer | yes | Its rank on the bill, from 1. |
| `description` | string | yes |  |
| `quantity` | number | yes |  |
| `unit` | string | yes |  |
| `unitPrice` | number | yes |  |
| `discountPercent` | number or null | yes |  |
| `netAmount` | number | yes | The line after its discount, without VAT, in the bill’s currency. |
| `vatCode` | string or null | yes | The VAT rate code of the line. |
| `vatRatePercent` | number | yes |  |
| `vatAmount` | number | yes |  |
| `total` | number | yes | The line with its VAT, in the bill’s currency. |
| `expenseAccountCode` | string or null | yes | The account the line is booked on (`GET /ext/accounts`). |
| `costCenterCode` | string or null | yes | The line’s one cost centre; null with none, and with several. |

### Company

The company a key acts in: what a reader needs to read its books right.

| Field | Type | Always there | What it is |
|---|---|---|---|
| `id` | string | yes |  |
| `name` | string | yes | The legal name. |
| `tradingName` | string or null | yes |  |
| `countryCode` | string or null | yes | ISO 3166-1 alpha-2: the country whose rules the books follow. |
| `baseCurrency` | string | yes | ISO 4217: the currency the ledger is kept in. Every ledger figure of the API is in it. |
| `accountingLanguage` | string | yes | The language account and journal names are written in (`en`, `fr`, `de`, `it`). |
| `timeZone` | string | yes | The IANA zone the accounting day is read in. |
| `today` | day (YYYY-MM-DD) | yes | Today’s accounting day, in `timeZone`. |
| `vat` | object | yes |  |
| `vat.registered` | boolean | yes | Whether the company is liable for VAT on `today`. |
| `vat.number` | string or null | yes |  |
| `vat.registeredFrom` | day (YYYY-MM-DD) or null | yes | The first liable day, when the company recorded one. |
| `vat.deregisteredFrom` | day (YYYY-MM-DD) or null | yes | The first day no longer liable, when the company de-registered. |
| `fiscalYears` | list of [FiscalYear](#fiscalyear) | yes | Oldest first. |

### CostCenterShare

One cost centre’s share of a journal line, within one class of cost centres.

| Field | Type | Always there | What it is |
|---|---|---|---|
| `costCenterCode` | string | yes | The cost centre’s code, as the company named it. |
| `costCenterClass` | string | yes | The class the share is filed under (`Department`, …), as it was when the line was booked. |
| `percentage` | number | yes | Of the line, in percent, as it was entered: the shares of one class add up to 100, to their rounding. |
| `amount` | number | yes | Of the line’s amount, in the base currency, always positive: the shares of one class add up to the line exactly. |

### CreditNote

A credit note. Its amounts are below zero, so the invoices and the credit notes of a period add up to what was invoiced: `total` is what it credits, `amountPaid` what of it was applied to invoices or refunded, `amountDue` the credit it still holds.

| Field | Type | Always there | What it is |
|---|---|---|---|
| `id` | string | yes |  |
| `externalRef` | string or null | yes | Your own id of the document. Null for one made in Mast. |
| `documentNumber` | string | yes | `Draft-…` until issued, then the official number. |
| `status` | one of `draft`, `open`, `paid`, `cancelled` | yes | `open` while it still holds credit, `paid` once all of it was applied or refunded. |
| `customerId` | string | yes | The customer’s id in Mast, the `id` of `GET /ext/customers`. |
| `customerExternalRef` | string or null | yes |  |
| `customerNumber` | string or null | yes |  |
| `customerName` | string or null | yes |  |
| `issueDate` | day (YYYY-MM-DD) | yes |  |
| `supplyPeriodStart` | day (YYYY-MM-DD) or null | yes | The time of supply, when it is not the issue date. |
| `supplyPeriodEnd` | day (YYYY-MM-DD) or null | yes |  |
| `language` | one of `de`, `fr`, `it`, `en`, or null | yes |  |
| `reference` | string or null | yes |  |
| `title` | string or null | yes |  |
| `introText` | string or null | yes | Printed above the lines. |
| `notes` | string or null | yes |  |
| `footerText` | string or null | yes | Printed at the foot of the document. |
| `currency` | string | yes |  |
| `priceIncludesVat` | boolean | yes | Whether the lines’ unit prices include VAT. |
| `subtotal` | number | yes | The lines after their own discounts: net, or with VAT when the prices include it. |
| `discountPercent` | number or null | yes | The discount on the whole document, when it is a percentage. |
| `discountAmount` | number | yes | The discount on the whole document, as an amount; 0 for none. |
| `netAmount` | number | yes | What the document bills, net of VAT, as its PDF prints it. |
| `vatAmount` | number | yes |  |
| `total` | number | yes |  |
| `amountPaid` | number | yes |  |
| `amountDue` | number | yes | What is still owed. |
| `vatRows` | list of [VatRow](#vatrow) | yes | The VAT per rate, adding up to `vatAmount`. |
| `invoicedNetAmount` | number or null | yes | What the document counts for in a sum of what was invoiced, net of VAT: add it over the invoices and the credit notes of a period. Null on a draft, on a cancelled document and on a credit note of a cancelled invoice. |
| `baseCurrency` | string | yes | The currency the company’s books are kept in. |
| `exchangeRate` | number or null | yes | The rate stored on the document, 1 in the base currency; null on a foreign document Mast holds no rate for. |
| `baseNetAmount` | number or null | yes | `netAmount` in the base currency at that rate; null where there is no rate, never converted at 1:1. |
| `baseVatAmount` | number or null | yes |  |
| `baseTotal` | number or null | yes |  |
| `baseAmountDue` | number or null | yes |  |
| `baseInvoicedNetAmount` | number or null | yes |  |
| `lines` | list of [DocumentLine](#documentline) or null | yes | The document’s lines. Always there on a single read; on a list only with `include=lines`, null otherwise. |
| `createdAt` | instant (ISO 8601) | yes |  |
| `updatedAt` | instant (ISO 8601) | yes |  |
| `invoiceId` | string or null | yes | The invoice it credits, when Mast knows it. |
| `invoiceExternalRef` | string or null | yes |  |
| `invoiceNumber` | string or null | yes |  |
| `creditsCancelledInvoice` | boolean | yes | True when the invoice it credits is itself cancelled: the two are out of a sum of what was invoiced together. |

### Customer

A customer of the company.

| Field | Type | Always there | What it is |
|---|---|---|---|
| `id` | string | yes |  |
| `externalRef` | string or null | yes | Your own id of the customer. Null for a customer made in Mast. |
| `number` | string | yes | Mast’s own customer number. |
| `type` | one of `business`, `individual` | yes |  |
| `name` | string | yes | The name its documents carry: the company’s, or the person’s. |
| `companyName` | string or null | yes |  |
| `firstName` | string or null | yes |  |
| `lastName` | string or null | yes |  |
| `email` | string or null | yes | The address an invoice is sent to. |
| `phone` | string or null | yes |  |
| `address` | object | yes | The billing address. |
| `address.street` | string or null | yes |  |
| `address.postalCode` | string or null | yes |  |
| `address.city` | string or null | yes |  |
| `address.country` | string or null | yes | The country’s name as Mast writes it. |
| `address.countryCode` | string or null | yes | ISO 3166-1 alpha-2; null when Mast cannot read the country’s name. |
| `language` | one of `de`, `fr`, `it`, `en`, or null | yes | The language its documents are written in. Null when Mast holds a language the API has no word for. |
| `vatNumber` | string or null | yes |  |
| `registrationNumber` | string or null | yes | Its commercial-register number (a UID, or a foreign registry’s id). |
| `defaultDiscountPercent` | number | yes | The discount Mast holds for this customer, in percent; 0 for none. An invoice takes it only when it asks (`applyCustomerDefaultDiscount`). |
| `paymentTermsDays` | integer | yes | Its net payment terms in days; 0 for due on receipt. |
| `createdAt` | instant (ISO 8601) | yes |  |
| `updatedAt` | instant (ISO 8601) | yes |  |

### DocumentLine

A line of an invoice or a credit note, as Mast holds it.

| Field | Type | Always there | What it is |
|---|---|---|---|
| `position` | integer | yes | Its place on the document, from 1. |
| `sectionTitle` | string or null | yes | The title of the section it sits in, when the document has sections. |
| `description` | string | yes | The line’s words as the document prints them. |
| `productId` | string or null | yes |  |
| `productExternalRef` | string or null | yes |  |
| `productCode` | string or null | yes |  |
| `quantity` | number | yes |  |
| `unit` | string | yes |  |
| `unitPrice` | number | yes |  |
| `discountPercent` | number or null | yes | The line’s own discount, in percent. |
| `discountAmount` | number | yes | That discount as an amount. |
| `vatRatePercent` | number | yes |  |
| `vatRateCode` | string or null | yes |  |
| `netAmount` | number | yes | After the line’s own discount, before the document’s. |
| `vatAmount` | number | yes | The VAT on that amount, before the document’s discount: the document’s own VAT, per rate, is in its `vatRows`. |
| `total` | number | yes | `netAmount` and `vatAmount` together. |
| `invoicedNetAmount` | number or null | yes | What the line counts for in a sum of lines, net of VAT: its share of what its document was issued for, so the lines of a document with a discount, or of a contract billed in stages, add up to what was invoiced. Null on a draft and on a cancelled document. |
| `invoicedQuantity` | number or null | yes | Its quantity at the same share. |
| `revenueAccountCode` | string or null | yes |  |
| `costCenterCode` | string or null | yes |  |
| `comment` | string or null | yes | A note printed under the line. |
| `supplyPeriodStart` | day (YYYY-MM-DD) or null | yes | When this line was supplied, if not when the document says. |
| `supplyPeriodEnd` | day (YYYY-MM-DD) or null | yes |  |

### FiscalYear

A fiscal year of the company.

| Field | Type | Always there | What it is |
|---|---|---|---|
| `id` | string | yes |  |
| `name` | string | yes | As the company named it (« 2026 »). |
| `startDate` | day (YYYY-MM-DD) | yes | Its first day. |
| `endDate` | day (YYYY-MM-DD) | yes | Its last day. |
| `status` | one of `open`, `closed`, `archived` | yes | `closed` and `archived` take no new entry. |

### Invoice

A customer invoice.

| Field | Type | Always there | What it is |
|---|---|---|---|
| `id` | string | yes |  |
| `externalRef` | string or null | yes | Your own id of the document. Null for one made in Mast. |
| `documentNumber` | string | yes | `Draft-…` until issued, then the official number. |
| `status` | one of `draft`, `open`, `overdue`, `partially_paid`, `paid`, `cancelled`, `paid_in_provider`, `refunded_in_provider`, `paid_outside_provider` | yes | `draft`: not issued, no official number. `open`: issued, nothing received, not due yet. `overdue`: issued, nothing received, due before today (judged on the day of the read). `partially_paid`, `paid`, `cancelled`. The three `…_provider` words are invoices a payment provider issued and collected. |
| `customerId` | string | yes | The customer’s id in Mast, the `id` of `GET /ext/customers`. |
| `customerExternalRef` | string or null | yes |  |
| `customerNumber` | string or null | yes |  |
| `customerName` | string or null | yes |  |
| `issueDate` | day (YYYY-MM-DD) | yes |  |
| `supplyPeriodStart` | day (YYYY-MM-DD) or null | yes | The time of supply, when it is not the issue date. |
| `supplyPeriodEnd` | day (YYYY-MM-DD) or null | yes |  |
| `language` | one of `de`, `fr`, `it`, `en`, or null | yes |  |
| `reference` | string or null | yes |  |
| `title` | string or null | yes |  |
| `introText` | string or null | yes | Printed above the lines. |
| `notes` | string or null | yes |  |
| `footerText` | string or null | yes | Printed at the foot of the document. |
| `currency` | string | yes |  |
| `priceIncludesVat` | boolean | yes | Whether the lines’ unit prices include VAT. |
| `subtotal` | number | yes | The lines after their own discounts: net, or with VAT when the prices include it. |
| `discountPercent` | number or null | yes | The discount on the whole document, when it is a percentage. |
| `discountAmount` | number | yes | The discount on the whole document, as an amount; 0 for none. |
| `netAmount` | number | yes | What the document bills, net of VAT, as its PDF prints it. |
| `vatAmount` | number | yes |  |
| `total` | number | yes |  |
| `amountPaid` | number | yes |  |
| `amountDue` | number | yes | What is still owed. |
| `vatRows` | list of [VatRow](#vatrow) | yes | The VAT per rate, adding up to `vatAmount`. |
| `invoicedNetAmount` | number or null | yes | What the document counts for in a sum of what was invoiced, net of VAT: add it over the invoices and the credit notes of a period. Null on a draft, on a cancelled document and on a credit note of a cancelled invoice. |
| `baseCurrency` | string | yes | The currency the company’s books are kept in. |
| `exchangeRate` | number or null | yes | The rate stored on the document, 1 in the base currency; null on a foreign document Mast holds no rate for. |
| `baseNetAmount` | number or null | yes | `netAmount` in the base currency at that rate; null where there is no rate, never converted at 1:1. |
| `baseVatAmount` | number or null | yes |  |
| `baseTotal` | number or null | yes |  |
| `baseAmountDue` | number or null | yes |  |
| `baseInvoicedNetAmount` | number or null | yes |  |
| `lines` | list of [DocumentLine](#documentline) or null | yes | The document’s lines. Always there on a single read; on a list only with `include=lines`, null otherwise. |
| `createdAt` | instant (ISO 8601) | yes |  |
| `updatedAt` | instant (ISO 8601) | yes |  |
| `stage` | one of `down_payment`, `progress`, `final`, or null | yes | The invoice of a contract billed in stages; null on any other invoice. |
| `contractNetAmount` | number or null | yes | The contract a staged invoice bills a part of; null on any other invoice. |
| `contractTotal` | number or null | yes |  |
| `dueDate` | day (YYYY-MM-DD) or null | yes |  |
| `paymentTermsDays` | integer | yes |  |
| `paymentTermsText` | string or null | yes | The payment terms in words, printed on the invoice. |
| `deliveryState` | one of `not_sent`, `sent_by_email`, `sent_by_other_channel`, `bounced`, `failed` | yes |  |
| `sentAt` | instant (ISO 8601) or null | yes | When it last went to the customer, where Mast recorded it. |
| `sentTo` | string or null | yes |  |
| `paidOn` | day (YYYY-MM-DD) or null | yes | The day its last payment came, once it is paid; null when no payment tells. |

### InvoiceSendResult

What sending an invoice answers.

| Field | Type | Always there | What it is |
|---|---|---|---|
| `invoice` | [Invoice](#invoice) | yes |  |
| `recipient` | string | yes |  |
| `deduplicated` | boolean | yes | True when the same message was sent moments ago: no second e-mail went. |

### JournalEntry

A booked journal entry, with every line.

| Field | Type | Always there | What it is |
|---|---|---|---|
| `id` | string | yes |  |
| `number` | string | yes | The entry’s number in its company (`JE-2026-00042`). |
| `date` | day (YYYY-MM-DD) | yes | The day it is booked on. |
| `description` | string or null | yes |  |
| `reference` | string or null | yes |  |
| `status` | one of `posted`, `reversed` | yes | `reversed`: another entry takes it back (`reversedBy`); both stay in the books. |
| `entryType` | string | yes | `normal`, `opening_balance`, `ytd_carryforward`, `closing_pnl`, `correction`, `vat_settlement`, … |
| `isClosingPeriod` | boolean | yes | Booked in the year-end closing period, apart from the year’s last month. |
| `isCarryForward` | boolean | yes | A year-end carry-forward of an earlier version of Mast, or the entry reversing one: it restates balances the books already hold. No balance of Mast counts it; leave it out of a sum of lines too. |
| `journal` | [JournalEntryFiling](#journalentryfiling) or null | yes |  |
| `documentType` | [JournalEntryFiling](#journalentryfiling) or null | yes |  |
| `source` | object or null | yes | What the entry books. Null for an entry a person wrote by hand. |
| `source.type` | string | yes | `invoice`, `credit_note`, `bill`, `expense`, `bank_reconciliation`, `bank_tx_gl`, `manual`, … |
| `source.documentId` | string or null | yes | The sales or purchase document it books, by its id in Mast. |
| `source.documentNumber` | string or null | yes |  |
| `source.bankTransactionId` | string or null | yes | The bank line it books: the `id` of `GET /ext/bank-transactions`. |
| `reverses` | [JournalEntryRef](#journalentryref) or null | yes | The entry this one takes back. |
| `reversedBy` | [JournalEntryRef](#journalentryref) or null | yes | The entry that takes this one back. |
| `currency` | string or null | yes | The currency of the document or bank line the entry books, when its lane records one. The lines’ debits and credits stay in the base currency. |
| `exchangeRate` | number or null | yes | The rate that foreign money was booked at: base currency per unit of `currency`. |
| `totalDebit` | number | yes | In the base currency. Equal to `totalCredit`. |
| `totalCredit` | number | yes |  |
| `postedAt` | instant (ISO 8601) or null | yes |  |
| `createdAt` | instant (ISO 8601) | yes |  |
| `updatedAt` | instant (ISO 8601) | yes | Moves when the entry is posted, and once more if it is reversed. |
| `lines` | list of [JournalEntryLine](#journalentryline) | yes |  |

### JournalEntryFiling

A journal or a document type an entry is filed under.

| Field | Type | Always there | What it is |
|---|---|---|---|
| `key` | string or null | yes | Mast’s own key (`sales`, `bank`, `customer_invoice`, …); null for one the company made. |
| `name` | string | yes | In the company’s accounting language. |

### JournalEntryLine

A line of a journal entry.

| Field | Type | Always there | What it is |
|---|---|---|---|
| `id` | string | yes |  |
| `lineNumber` | integer | yes | Its rank in the entry, from 1. |
| `accountCode` | string | yes |  |
| `description` | string or null | yes |  |
| `debit` | number | yes | In the base currency. One of `debit` and `credit` is 0. |
| `credit` | number | yes | In the base currency. |
| `costCenterCode` | string or null | yes | The code of the cost centre the line itself names; null with none, and for a line shared out between several. Read `costCenterShares` to sum by cost centre. |
| `costCenterShares` | list of [CostCenterShare](#costcentershare) | yes | How the line’s amount is shared out between cost centres: empty with none, one share at 100 for a line with one cost centre, several for a line shared out. A line can carry shares in more than one class at once: read one class at a time, each adds up to the line. |
| `lineType` | string or null | yes | How Mast files the line (`revenue_base`, `vat_output`, `vat_input`, `cost_base`, `ar`, `ap`, `other`, …); null for a line that states none. |
| `vatCode` | string or null | yes | The VAT rate code the line was booked under. |
| `vatRatePercent` | number or null | yes |  |
| `vatAmount` | number or null | yes | On a VAT line: the tax it books, in the base currency. |
| `taxableAmount` | number or null | yes | The net amount the line’s VAT is computed on, in the base currency. |
| `foreignAmount` | number or null | yes | What the line moved in its account’s own currency, when that is not the base currency: positive on a debit, negative on a credit. |
| `foreignCurrency` | string or null | yes |  |
| `counterpartyType` | one of `customer`, `supplier`, `employee`, `product`, or null | yes |  |
| `counterpartyId` | string or null | yes | The customer’s, supplier’s, employee’s or product’s id in Mast. |

### JournalEntryRef

Another entry, as an entry points to it.

| Field | Type | Always there | What it is |
|---|---|---|---|
| `id` | string | yes |  |
| `number` | string | yes |  |

### KeyAndCompany

An API key and the company it acts in.

| Field | Type | Always there | What it is |
|---|---|---|---|
| `key` | object | yes |  |
| `key.id` | string | yes | The key’s id in Mast. |
| `key.name` | string | yes | The name the key was given (« Back office »). |
| `key.displayPrefix` | string | yes | How the key starts, as Settings shows it: enough to tell it from another, never the key. |
| `key.roleName` | string | yes | The role whose rights the key holds. |
| `key.expiresAt` | instant (ISO 8601) or null | yes | When the key stops working; null for a key made never to expire. |
| `company` | object | yes |  |
| `company.id` | string | yes | The company’s id in Mast. |
| `company.name` | string | yes | The company the key acts in. A key acts in one company and no other. |
| `connection` | object |  | Present when the caller is not a key but an assistant connected by sign-in (see the MCP page): `key` then holds the assistant’s name and the role of the person who connected it. |
| `connection.level` | one of `READ`, `PREPARE` | yes | What the connection may do: READ reads, PREPARE also prepares customers, products and draft invoices. |
| `connection.connectedByName` | string | yes | The person who approved the connection, whose rights it holds. |

### Payment

A payment received against an invoice. An invoice a payment processor’s own lane settled has none: its `amountPaid` says it. A payment cancelled in Mast drops out of the list.

| Field | Type | Always there | What it is |
|---|---|---|---|
| `id` | string | yes |  |
| `paidOn` | day (YYYY-MM-DD) | yes | The day the money came: the bank line’s booking day, else the day recorded. |
| `amount` | number | yes | In the invoice’s currency. |
| `currency` | string | yes |  |
| `invoiceId` | string | yes |  |
| `invoiceExternalRef` | string or null | yes |  |
| `invoiceNumber` | string | yes |  |
| `customerId` | string | yes |  |
| `customerExternalRef` | string or null | yes |  |
| `source` | one of `bank_line`, `manual`, `processor`, or null | yes | How it was recorded: a bank line matched to the invoice, by hand, or a payment processor’s charge. Null when Mast cannot tell. |
| `bankTransactionId` | string or null | yes | The bank line’s id in Mast (`GET /ext/bank-transactions`), for a payment a bank line carries. |
| `reference` | string or null | yes |  |
| `createdAt` | instant (ISO 8601) | yes |  |
| `updatedAt` | instant (ISO 8601) | yes |  |

### Product

Something the company sells.

| Field | Type | Always there | What it is |
|---|---|---|---|
| `id` | string | yes |  |
| `externalRef` | string or null | yes | Your own id of the product. Null for a product made in Mast. |
| `number` | string | yes | Mast’s own product number. |
| `type` | one of `good`, `service` | yes |  |
| `name` | string | yes |  |
| `code` | string or null | yes |  |
| `description` | string or null | yes |  |
| `unitPrice` | number | yes | The selling price, without VAT unless the invoice says its prices include it. |
| `costPrice` | number | yes |  |
| `currency` | string | yes | The currency of its prices. An invoice line that takes the product's price takes the number as it is, in the invoice's own currency: nothing is converted. |
| `unit` | string or null | yes |  |
| `accountCode` | string or null | yes | The revenue account a line of this product is booked to. |
| `vatRateCode` | string or null | yes | The product’s own VAT rate, by its code; null when it names none. |
| `vatRatePercent` | number or null | yes | That rate, in percent. |
| `active` | boolean | yes | False once a person deactivated it in Mast. |
| `createdAt` | instant (ISO 8601) | yes |  |
| `updatedAt` | instant (ISO 8601) | yes |  |

### Supplier

A supplier of the company. No bank account is served, and none is written: a person enters it in Mast.

| Field | Type | Always there | What it is |
|---|---|---|---|
| `id` | string | yes |  |
| `externalRef` | string or null | yes | Your own id of the supplier. Null for a supplier made in Mast that was never given one. |
| `number` | string | yes | Mast’s own supplier number. |
| `name` | string | yes |  |
| `businessType` | string | yes | `corporation_company`, `sole_proprietorship`, `nonprofit_association`, `government_public`, `other`. |
| `registrationNumber` | string or null | yes | Its number in the commercial register, as the company recorded it. |
| `email` | string or null | yes |  |
| `phone` | string or null | yes |  |
| `address` | object | yes |  |
| `address.street` | string or null | yes |  |
| `address.postalCode` | string or null | yes |  |
| `address.city` | string or null | yes |  |
| `address.country` | string | yes | The country’s name as Mast writes it. |
| `vatStatus` | one of `registered`, `foreign_registered`, `foreign_not_registered`, `not_registered`, `unknown` | yes | Whether the supplier is registered for VAT in the VAT territory of the company’s own country (`registered`), abroad (`foreign_registered`), or not; `unknown` when its record does not say. |
| `vatNumber` | string or null | yes | Its VAT number in the company’s own VAT territory, for a supplier registered there. |
| `foreignTaxId` | string or null | yes | A foreign supplier’s own tax id. |
| `foreignTaxIdCountry` | string or null | yes | The country that gave that tax id (ISO 3166-1 alpha-2). |
| `currency` | string | yes | ISO 4217: the currency its bills default to. |
| `paymentTermsDays` | integer | yes |  |
| `createdAt` | instant (ISO 8601) | yes |  |
| `updatedAt` | instant (ISO 8601) | yes |  |

### TrialBalance

The figures of Mast’s own Trial Balance for the same days.

| Field | Type | Always there | What it is |
|---|---|---|---|
| `from` | day (YYYY-MM-DD) | yes |  |
| `to` | day (YYYY-MM-DD) | yes |  |
| `baseCurrency` | string | yes |  |
| `closingPeriod` | boolean | yes | True for the year-end closing view: only the closing period’s entries are its movements. |
| `balanceSheetFrom` | day (YYYY-MM-DD) or null | yes | The day asset, liability and equity accounts are summed from: the company’s first booked day, or `from` when nothing is booked. |
| `resultFrom` | day (YYYY-MM-DD) or null | yes | The day income and expense accounts are summed from: the first day of the fiscal year `from` falls in, since they restart each fiscal year. |
| `provisionalOpeningUntil` | day (YYYY-MM-DD) or null | yes | The last day of an earlier fiscal year still open: the opening balances can still change. |
| `isBalanced` | boolean | yes | The closing debits and credits agree, `unplacedPriorYearsResult` counted. |
| `unplacedPriorYearsResult` | number | yes | The result of earlier fiscal years that no row carries: 0 unless the company maps no account to the year’s result. |
| `totals` | object | yes |  |
| `totals.openingDebits` | number | yes |  |
| `totals.openingCredits` | number | yes |  |
| `totals.periodDebits` | number | yes |  |
| `totals.periodCredits` | number | yes |  |
| `totals.closingDebits` | number | yes |  |
| `totals.closingCredits` | number | yes |  |
| `accounts` | list of [TrialBalanceAccount](#trialbalanceaccount) | yes | By account code. Accounts with no balance and no movement are left out. |

### TrialBalanceAccount

One account of the trial balance. Every figure is in the base currency and signed debit minus credit (a liability, equity or income account normally reads negative); `closingBalance = openingBalance + periodDebits - periodCredits`.

| Field | Type | Always there | What it is |
|---|---|---|---|
| `accountId` | string | yes |  |
| `accountCode` | string | yes |  |
| `accountName` | string | yes |  |
| `accountType` | one of `asset`, `liability`, `equity`, `revenue`, `expense` | yes |  |
| `openingBalance` | number | yes | What the account held when the period starts. |
| `periodDebits` | number | yes | The movements dated inside the period. An opening-balance entry is none. |
| `periodCredits` | number | yes |  |
| `closingBalance` | number | yes | What the account holds on the period’s last day. |
| `priorYearsResult` | number or null | yes | On the account that carries the year’s result only: the result of earlier fiscal years not yet allocated, counted in its opening and closing balance. |

### VatRow

One VAT rate of a document: the base it taxes and its VAT, as the PDF prints them.

| Field | Type | Always there | What it is |
|---|---|---|---|
| `ratePercent` | number | yes |  |
| `netAmount` | number | yes |  |
| `vatAmount` | number | yes |  |
