Keyio MCP server and API

Properties

Fields you can send

• mainPurpose: long_term, short_term or sale (bought to be sold). sale is buy-to-sell tracking: stage, target price, budget lines, financing, deeds, municipal capital-gains tax and sale price and date.
• taxRegime: es-individual, es-company or es-nonresident (with nonResidentEU when the owner resides in the EU/EEA). paymentTrackingEnabled turns on rent payment tracking for the property’s rentals; it is needed to record payments.
• SES, Mossos and Ertzaintza credentials, calendar feed links and sharing settings are never returned. The IBAN and the ID numbers of owners and representative are only shown to the owner and editors.
• Automatic SES sending (sesAutoSend) and sharing can only be changed in the app. Creating respects the plan’s property limit (403).
• Deleting is refused with 409 while there are rentals or expenses; it also deletes its documents and checklist history. It cannot be undone.

Rentals

List filters

• propertyId — Only that property’s (404 if it is not yours).
• type — long or short.
• from, to — Stays that overlap the range.

Fields you can send

• renters takes id, fullName, idNumber, address, phone and email, but only returns id and fullName. In a PATCH, a renter with a known id keeps what you leave out; an empty string clears a field; one missing from the list is removed. renterAddress is not returned (it is a home address).
• Creating on a sold property gives 409. propertyId cannot be changed.
• Deleting also removes payments, notes, documents and signing links, revokes the door code and, for a Basque booking already reported, leaves the reminder to cancel it with the Ertzaintza.

Expenses

Needs a plan with expenses.

List filters

• propertyId — Only that property’s.
• year — Fiscal year, four digits.

Fields you can send

• type is free text, but use one of the app’s categories so it counts in the tax report: Seguro, Comunidad, Impuestos, Suministros, Conservación, Reparaciones, Mobiliario, Electrodomésticos, Intereses de Hipoteca, Formalización Contrato, Defensa Jurídica, Servicios Personales, Otros. IBI is stored as Impuestos.
• A fixed asset (furniture, appliance) is a Mobiliario or Electrodomésticos expense with amortizationType "investment". The old /assets routes answer 410.
• Breakdown (companies): amount should be taxBase + vatAmount + untaxedAmount; the withholding is informative. The API stores what you send without checking the sums. payment (what bank reconciliation recorded as paid) is read-only.
• recurrence (create only): { frequency: monthly | quarterly | yearly, nextDueDate, endDate }. It creates the periods already due up to today (at most 120) and a recurring expense that is copied on each due date; the response adds recurring: { recurringExpenseId, backfilled, nextDueDate }. The expense does not store the recurrence and a PATCH does not accept it (400): change or stop it through /recurring-expenses.
• file (on create) or PUT /expenses/{id}/file attach the invoice: PDF, JPEG, PNG, WebP or GIF; replacing deletes the old one. Deleting the file keeps the expense.
• /recurring-expenses: your own only (filter propertyId). PATCH takes type, description, issuerName, issuerId, frequency, nextDueDate, lastAmount, endDate (null clears it), active and operationCategory. DELETE stops the repetition; expenses already created stay.

Invoice inbox

Needs a plan with expenses. It belongs to the account owner: invoices uploaded without a property or forwarded by email wait here until they are filed as an expense.

Fields you can send

• GET /inbox returns the invoices oldest first and the mailbox: { available, address, accountEmail, allowedSenders }. PUT /inbox/mailbox turns it on (always the same address) and takes allowedSenders; 409 when the mailbox is not available.
• POST /inbox/{id}/file takes exactly one of: expenseId (attaches the invoice to that expense, 200) or expense (the same fields as POST /expenses, creates it, 201). The invoice leaves the inbox. 409 when it has no file.
• The API never runs Keyio’s AI on the invoice: the caller (your program or your assistant) reads it and decides the property and the figures.

Documents

Of a property (/properties/{id}/documents) or of a rental (/rentals/{id}/documents), with the same routes.

Fields you can send

• documentType: contract, addendum, inventory, checkin_report, checkout_report, receipt, invoice, deposit, id_copy, insurance, deed, energy_certificate, habitability_certificate, tourist_license, house_rules, appliance_instructions, wifi_info or other. file: PDF, images, Word, Excel or OpenDocument. A rental’s are created published.
• Returned with status (draft, published, archived, pending_signature, signed), hasFile and signing (how many signers and how many signed), never links or signer details. GET of one adds file: for a signed contract, the signed PDF.
• PATCH: name, description, documentType, validityDate (null clears it) and publishedToPortal. Deleting is refused with 409 while it is pending signature, and also deletes its files.

Rent payments

Needs a plan with payments and payment tracking turned on for the property (paymentTrackingEnabled).

List filters

• year — Only that year’s charges.

Fields you can send

• Charges: for a long-term let, one per month up to next month; for a short stay, the deposit and balance or the milestones of its paymentPlan. Each has chargeType (monthly_rent, advance, balance, installment), expectedAmount, receivedAmount, status (paid, partial, pending, due, late) and its entries.
• To record a payment, name the charge with year + month, chargeType or planEntryId. It adds to what was already received: paid once the expected amount is reached, partial before. If the charge is ambiguous, the 400 lists them. method: transfer (default), cash, card, domiciliacion or other. 409 when payment tracking is off.
• A single payment is corrected or removed at …/entries/{entryId}; removing the last one deletes the record. Only whoever recorded it can delete the whole charge (403).

Rental notes

The rental’s communications log. Notes cannot be edited.

Fields you can send

• content up to 2,000 characters. type: note, call, email, whatsapp, letter, meeting or other; contactDirection: inbound or outbound. createdBy is your account’s name. Listed newest first; only its author can delete one.

Maintenance

Needs a plan with maintenance.

List filters

• propertyId — Only that property’s.
• status — open, acknowledged, in_progress, completed or cancelled.

Fields you can send

• category: plumbing, electrical, hvac, appliance, structural, cleaning or other (default); urgency: low, medium (default), high or emergency; status starts as open. notes up to 2,000 characters. linkedExpenseId (PATCH only) links an expense of the same property; null unlinks it. Completing it stamps resolvedAt.
• Up to 5 photos per request (one image per POST; 409 beyond 5); n starts at 1. photoCount is returned, never photo links. Only whoever created it can delete it (otherwise cancel it); deleting it deletes its photos.

Tax reports

Needs a plan with reports. They are estimates and always carry the disclaimer to check them with your tax adviser.

List filters

• year — Required on both.
• isRatePct — 15 or 25: corporate tax rate (report of a company-owned property).

• A property’s report has regime (IRPF, IS or IRNR), owners with their ownershipPercentage, occupancy, income, expenses by tax-return box, the irpf detail (net return, long-term letting reduction, imputed income), is or irnr, and result { deductions, netResult, estimatedTax }. Figures are for 100% of the property.
• The summary gives, per property with activity that year, income, deductible expenses, net result and estimated tax, plus the totals.

Contract templates

Needs a plan with contracts. They are yours only.

Fields you can send

• content is a TipTap document: { "type": "doc", "content": [ … ] }, the same format as the app’s editor. category: rental-contract, short-term-rental, rent-review, inventory, termination, addendum or other.