How an agent requests or buys a report
Read the offer
GET /products returns the report types, prices and the consent text with its SHA-256.
Find the building
GET /address/search gives the municipality and street; POST /buildings/resolve identifies the building and returns a resolutionToken.
Talk to the person
For the free report, show them the consent text and wait until they accept it. For a paid one, also tell them you are buying it on their behalf, with their email address, and that this means accepting the terms and losing the right of withdrawal.
Request or buy the report
POST /reports/free returns jobId, statusToken and the private preview link; POST /reports/purchase also returns checkoutUrl, the Stripe payment page.
Pay, for a paid report
The agent or the person pays at checkoutUrl before it expires, after about 30 minutes. Nothing is generated without payment.
Wait and hand over the link
GET /jobs/{jobId} follows the payment and the report; once it is ready, the agent gives the link to the person. Paid reports are also emailed.
What is available today and what is not
What can an agent do with HOUSINGFAX?
An assistant such as ChatGPT or Claude, or your own program, can answer with HOUSINGFAX data when someone asks how to check a home in Spain before buying it: which reports exist and what they cost (€0, €11 and €19, VAT included), what each one checks, whether the province is covered and which building sits at an address. With the person's permission, it can also request their free report or buy them a paid one.
The free report is a web preview with the traffic light of every check, without a PDF. The essential report and the complete report with building condition include the web report and a PDF, and an agent can buy them with POST /reports/purchase: it accepts the terms on the person's behalf, gives their email address and gets a Stripe payment page, where either the agent or the person pays. They can also be bought on the website. The complete report can only be ordered when the building inspection (ITE or IEE in Spanish) is on the regional register; the POST /buildings/resolve response says so in ieeAvailability and availableTiers.
Service endpoints
API: https://housingfax.com/api/agent/v1. Read operations, free report creation and paid report purchases in JSON, without authentication. Contract agent-api-1.1.0; every operation accepts language (es, en, de, nl or fr) and answers in that language.
MCP server: https://housingfax.com/mcp, over Streamable HTTP and without sign-in. OpenAPI 3.1 description of the API: https://housingfax.com/openapi.json.
curl examples
Report types, prices and consent text: curl -s "https://housingfax.com/api/agent/v1/products?language=en"
The 22 checks: curl -s "https://housingfax.com/api/agent/v1/checks?language=en"
Coverage for a municipality: curl -s "https://housingfax.com/api/agent/v1/coverage?municipality=Estepona&language=en"
Municipalities in a province (29 is Málaga): curl -s "https://housingfax.com/api/agent/v1/address/search?kind=municipality&provinceCode=29&q=marbella&language=en"
Identify a building by its cadastral reference (replace the placeholder with a real 14-character reference): curl -s -X POST "https://housingfax.com/api/agent/v1/buildings/resolve" -H "Content-Type: application/json" -d '{"language":"en","cadastralReference":"{14-character reference}","scope":"building"}'
To request the free report, POST /reports/free takes language, the resolutionToken from the previous step, consent: true, consentStatementSha256 (the SHA-256 of the consent text returned by GET /products, exactly as you showed it to the person) and, if the person wants an email when it is ready, email. It answers 202 with jobId, statusToken and the private link. The exact parameters of each operation are in the OpenAPI file.
To buy a paid report, POST /reports/purchase takes language, tier (simple for the essential report or complete for the complete one), the resolutionToken from POST /buildings/resolve or, if a free report is already ready, freeReport with its jobId and statusToken (the paid report then reuses its sources), email (required: the receipt, the link and the withdrawal confirmation go there), consent: true, consentStatementSha256, termsVersion (the one returned by GET /products), acceptTerms: true and waiveWithdrawalRight: true. Example: curl -s -X POST "https://housingfax.com/api/agent/v1/reports/purchase" -H "Content-Type: application/json" -d '{"language":"en","tier":"simple","resolutionToken":"{resolutionToken}","email":"{the person's email}","consent":true,"consentStatementSha256":"{SHA-256 of the consent text}","termsVersion":"{termsVersion}","acceptTerms":true,"waiveWithdrawalRight":true}'
The purchase answers 201 with orderId, status: awaiting_payment, the price including VAT, checkoutUrl (the Stripe payment page, which expires after about 30 minutes; checkoutExpiresAt gives the exact time), jobId, statusToken and reportUrl, the private link to the report. Nothing is generated until Stripe confirms the payment; the report is then ready within minutes and the link is also emailed. Promo codes are not accepted.
Report status (the statusToken goes in the Authorization header, never in the URL): curl -s "https://housingfax.com/api/agent/v1/jobs/{jobId}?language=en" -H "Authorization: Bearer {statusToken}"
For a purchase, the status goes through awaiting_payment, payment_received, queued, in_progress and ready; if nobody pays in time it ends as payment_expired, and if the payment is refunded, as refunded.
MCP server tools
get_products (GET /products): report types, prices with VAT, free report limits and the consent text the person has to accept.
list_checks (GET /checks): the 22 checks, each with its question and the report it belongs to.
check_coverage (GET /coverage): whether a province or municipality is covered; the foral territories and Navarre come back with their status spelled out.
search_address (GET /address/search): municipalities in a province and then streets in a municipality, from the official street directory.
resolve_building (POST /buildings/resolve): identifies the building from an address or a cadastral reference and returns a resolutionToken; if there are several homes, it asks you to pick one or the whole building.
create_free_report (POST /reports/free): requests the free report with the person's consent and returns jobId, statusToken and the private link.
get_report_status (GET /jobs/{jobId}): report status and, once ready, its private link.
purchase_report (POST /reports/purchase): buys a paid report: the agent accepts on the person's behalf, with their email, and gets the Stripe payment page, the jobId and the statusToken.
The usual order is get_products, check_coverage, search_address, resolve_building, create_free_report and get_report_status; to buy, purchase_report instead of create_free_report, or after it to move from the free report to a paid one. Each tool description says when recommending the report makes sense and which limits to mention.
Limits and errors
The agent channel allows 50 free reports a day in total, and the website's free report limits also apply: 2 per email address every 14 days, a cap per IP address and a global daily cap. Agent requests join the same queue as the website, with no priority.
Each client also has a per-minute limit: 60 requests to /products and /checks, 30 to /coverage and /address/search, 12 to /buildings/resolve, 3 to /reports/free, 3 to /reports/purchase and 60 to the MCP server. Purchases do not count towards the free report's daily cap, but they share the queue: if it is full, the API answers 503 before opening the payment.
When a limit is reached the API answers 429 with a Retry-After header and a retryAfterSeconds field; if the queue is full or an official source is not responding, 503 with the same data. Every error carries a stable code (for example AGENT_DAILY_CAPACITY_REACHED or OUTSIDE_REPORT_COVERAGE) and none of the request data. An unknown parameter returns 400.
The resolutionToken expires after a few minutes (resolutionExpiresInSeconds tells you how many) and the statusToken is the only way to check the status: keep it when you create the report and send it in the Authorization: Bearer header, never in the URL.
Terms of use
For the free report, consent comes from the person: before creating it, show them the text returned by get_products and wait until they accept it.
For a purchase, the agent accepts that same text on the person's behalf (data processing and immediate execution, with the loss of the right of withdrawal) together with the terms in force. Whoever delegates to an agent is bound by what it accepts and pays for, under the "Contracting through an agent" clause of the terms linked below: explain this to the person before buying. In both cases the server compares the SHA-256 with the current text and records that the request came through the agent channel, with the version of the terms accepted.
The report is private: it comes back as a tokenised, non-indexed link that the agent hands to that person and does not publish. Do not use the API to build pages about individual buildings or to claim that a given building does or does not have aluminosis. Likelihoods are given as levels in words (very low, low, moderate, high, very high), never as percentages.
When a source does not respond or there is no data, the check shows ○ no data with the reason; that is not a negative result. Navarre is not covered yet, and in Álava, Bizkaia and Gipuzkoa the report covers the whole building. HOUSINGFAX brings together what the official registers say and tells you what to look into: the report does not replace a technical inspection of the building, a valuation or legal advice.
How to add it to ChatGPT
According to OpenAI's guide, your own MCP connectors are added in developer mode, available on the web for Plus, Pro, Business, Enterprise and Education accounts; in company workspaces an admin has to allow it first.
1. In Settings → Security and login, turn on Developer mode. 2. Open ChatGPT Plugins and select the + button. 3. Enter a name (HOUSINGFAX) and a description. 4. Under Connection, choose the public endpoint and enter https://housingfax.com/mcp; the server needs no authentication. 5. Create the connection and review the tools it finds. 6. In a new conversation, add HOUSINGFAX from the + menu and ask for it by name.
ChatGPT asks for confirmation before write actions such as create_free_report or purchase_report: check the data before you accept.
How to add it to Claude
According to Anthropic's guide, custom connectors using remote MCP work in Claude, Cowork and Claude Desktop on the Free, Pro, Max, Team and Enterprise plans; the Free plan is limited to one.
Individual account: 1. Go to Customize → Connectors. 2. Click + and then Add custom connector. 3. Enter https://housingfax.com/mcp. 4. Leave Advanced settings empty, because the server does not use OAuth. 5. Click Add. On Team and Enterprise the owner adds it under Organization settings → Connectors → Add → Custom → Web, and each member connects it under Customize → Connectors.
To use it in a conversation, click + at the bottom left, open Connectors and switch HOUSINGFAX on.
Contact
If you are building HOUSINGFAX into an agent or need more capacity than the daily cap, write to [email protected]. Please do not send addresses, cadastral references or report links by email.
Short answers
Do I need a key or an account to use the API?
No. The API and the MCP server work without sign-up or a key. To prevent abuse there is a daily cap on the channel plus the free report limits.
Can an agent buy the essential or the complete report?
Yes. With purchase_report or POST /reports/purchase, the agent accepts the terms and the loss of the right of withdrawal on the person's behalf, gives their email address and gets a Stripe payment page; the agent or the person pays. Whoever delegates is bound by what the agent accepts, under the "Contracting through an agent" clause of the terms. The essential report costs €11 and the complete report with building condition €19, VAT included; the complete one only when a building inspection is on record.
What does the agent get when it requests or buys a report?
For the free report, a jobId, a statusToken and the private link to the preview. For a purchase, also the orderId and the Stripe payment page, and the private report link is emailed as well. The link opens once the status is ready; the agent hands it to the person, does not receive the report content and does not publish it.
What happens when the daily limit is reached?
The API answers 429 with Retry-After, which says how many seconds to wait. The channel cap is 50 free reports a day, plus 2 per email address every 14 days.
Does it cover all of Spain?
It covers the provinces of the national Cadastre and, in Álava, Bizkaia and Gipuzkoa, the whole building through their own foral cadastres. Navarre is not covered yet. check_coverage tells you for each province or municipality.
Official sources you can consult
The links let you review the primary source. Their inclusion does not widen their purpose or turn a piece of context into a diagnosis.