{ "openapi": "3.1.1", "info": { "title": "HOUSINGFAX agent API", "summary": "Instant home report on a flat, house or building in Spain, for AI agents and developers.", "description": "Public, unauthenticated API to explain HOUSINGFAX, check coverage, identify a building in Spain and request the report for a person, who accepts the consent text first. Every report is free: the full report with web view and PDF.\n\nThe report is a preliminary purchase due-diligence report built from public records, not a technical inspection, valuation or certificate. It never states that a building has aluminosis and never gives percentages. Unknown is not a negative: missing data is shown as \"no data\" with its reason.\n\nReports are private: the API returns a link with a token that must not be published. `POST /reports/purchase` stays in the contract for compatibility and answers 409 `NOT_FOR_SALE`.\n\nInputs are strict: an unknown or repeated parameter or field is rejected with 400 `INVALID_REQUEST`. Read operations (GET) can be called from any origin (CORS); POST operations are meant for servers and agents, not for browser pages on other sites.\n\nThe same operations are available as tools of the MCP server at https://housingfax.com/mcp.", "version": "1.3.0", "termsOfService": "https://housingfax.com/es-es/terminos", "contact": { "name": "HOUSINGFAX", "email": "ldescals.ssp@gmail.com", "url": "https://housingfax.com/es-es/contacto" } }, "externalDocs": { "description": "HOUSINGFAX for agents and developers", "url": "https://housingfax.com/es-es/api" }, "servers": [ { "url": "https://housingfax.com/api/agent/v1" } ], "security": [], "x-service-info": { "name": "HOUSINGFAX", "contract": "agent-api-1.3.0", "contact": { "email": "ldescals.ssp@gmail.com", "url": "https://housingfax.com/es-es/contacto" }, "termsOfService": "https://housingfax.com/es-es/terminos", "privacyPolicy": "https://housingfax.com/es-es/privacidad", "documentation": { "es": "https://housingfax.com/es-es/api", "en": "https://housingfax.com/en-es/api", "de": "https://housingfax.com/de-es/api", "nl": "https://housingfax.com/nl-es/api", "fr": "https://housingfax.com/fr-es/api" }, "mcpServer": "https://housingfax.com/mcp", "authentication": "none", "coverage": "Spain only; Navarre not covered yet.", "limits": { "activeClients": { "max": 40, "idleSeconds": 120 }, "reportsInProgressPerClient": 3, "capacity": "When the channel is serving its maximum of active clients, a new client gets 503 CHANNEL_AT_CAPACITY with Retry-After; clients already active go on.", "rateLimited": "Per client and per IP address; 429 with Retry-After when exceeded.", "queue": "Shared with the website, without priority." }, "payments": "None: every report is free; POST /reports/purchase answers 409 NOT_FOR_SALE." }, "paths": { "/products": { "get": { "operationId": "getProducts", "summary": "The report and its consent text", "description": "The report HOUSINGFAX generates (`productMode: free`): a single product, the full report with web view and PDF, free of charge, with the building condition assessment when the building has an IEE/ITE record. Also the capacity limits of the channel, the consent text the person must accept before a report is requested and the Terms version.", "x-mcp-tool": "get_products", "parameters": [ { "name": "language", "in": "query", "required": false, "schema": { "default": "es", "type": "string", "enum": [ "es", "en", "de", "nl", "fr" ] } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetProductsOutput" } } } }, "400": { "$ref": "#/components/responses/Error400" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "410": { "$ref": "#/components/responses/Error410" }, "422": { "$ref": "#/components/responses/Error422" }, "429": { "$ref": "#/components/responses/Error429" }, "500": { "$ref": "#/components/responses/Error500" }, "503": { "$ref": "#/components/responses/Error503" } } } }, "/checks": { "get": { "operationId": "listChecks", "summary": "The checks of the report", "description": "Every check of the report, numbered, with the question it answers and whether its source is integrated. A check without data is shown as \"no data\" with its reason, never as a pass.", "x-mcp-tool": "list_checks", "parameters": [ { "name": "language", "in": "query", "required": false, "schema": { "default": "es", "type": "string", "enum": [ "es", "en", "de", "nl", "fr" ] } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListChecksOutput" } } } }, "400": { "$ref": "#/components/responses/Error400" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "410": { "$ref": "#/components/responses/Error410" }, "422": { "$ref": "#/components/responses/Error422" }, "429": { "$ref": "#/components/responses/Error429" }, "500": { "$ref": "#/components/responses/Error500" }, "503": { "$ref": "#/components/responses/Error503" } } } }, "/coverage": { "get": { "operationId": "checkCoverage", "summary": "Coverage by province and municipality", "description": "Whether a province or municipality of Spain is covered. Navarre is not covered yet (foral adapter pending), which never means \"no risk\". Without parameters, every province.", "x-mcp-tool": "check_coverage", "parameters": [ { "name": "language", "in": "query", "required": false, "schema": { "default": "es", "type": "string", "enum": [ "es", "en", "de", "nl", "fr" ] } }, { "name": "province", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 80 } }, { "name": "municipality", "in": "query", "required": false, "schema": { "type": "string", "minLength": 2, "maxLength": 80 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckCoverageOutput" } } } }, "400": { "$ref": "#/components/responses/Error400" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "410": { "$ref": "#/components/responses/Error410" }, "422": { "$ref": "#/components/responses/Error422" }, "429": { "$ref": "#/components/responses/Error429" }, "500": { "$ref": "#/components/responses/Error500" }, "503": { "$ref": "#/components/responses/Error503" } } } }, "/address/search": { "get": { "operationId": "searchAddress", "summary": "Search municipalities and streets", "description": "Step 1 (`kind=municipality`): municipalities of a province. Step 2 (`kind=street`, with the codes of step 1): streets of a municipality. The codes feed `POST /buildings/resolve`.", "x-mcp-tool": "search_address", "parameters": [ { "name": "kind", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "municipality", "street" ] } }, { "name": "language", "in": "query", "required": false, "schema": { "default": "es", "type": "string", "enum": [ "es", "en", "de", "nl", "fr" ] } }, { "name": "provinceCode", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^\\d{2}$" } }, { "name": "q", "in": "query", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 80 } }, { "name": "municipalityDgcCode", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d{1,3}$" } }, { "name": "municipalityIneCode", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d{3}$" } }, { "name": "streetTypeCode", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[A-Z0-9]{1,4}$" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchAddressOutput" } } } }, "400": { "$ref": "#/components/responses/Error400" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "410": { "$ref": "#/components/responses/Error410" }, "422": { "$ref": "#/components/responses/Error422" }, "429": { "$ref": "#/components/responses/Error429" }, "500": { "$ref": "#/components/responses/Error500" }, "503": { "$ref": "#/components/responses/Error503" } } } }, "/buildings/resolve": { "post": { "operationId": "resolveBuilding", "summary": "Identify the building", "description": "Identifies the building by cadastral reference or by the coded address from `/address/search`. When it is resolved, returns a `resolutionToken` (valid for 15 minutes) for `POST /reports/free` and whether the building has an IEE/ITE record, which decides whether the report includes the building condition assessment. No protected cadastral data.", "x-mcp-tool": "resolve_building", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResolveBuildingInput" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResolveBuildingOutput" } } } }, "400": { "$ref": "#/components/responses/Error400" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "410": { "$ref": "#/components/responses/Error410" }, "413": { "$ref": "#/components/responses/ErrorBodyTooLarge" }, "415": { "$ref": "#/components/responses/ErrorUnsupportedMediaType" }, "422": { "$ref": "#/components/responses/Error422" }, "429": { "$ref": "#/components/responses/Error429" }, "500": { "$ref": "#/components/responses/Error500" }, "503": { "$ref": "#/components/responses/Error503" } } } }, "/reports/free": { "post": { "operationId": "createFreeReport", "summary": "Request the report", "description": "Queues the report for a resolved building, once the person has accepted the consent text of `GET /products`. Every report is free: it is the full report with web view and PDF, generated with real data. Returns a private `previewUrl` (token, not indexed) and a `statusToken` to follow it. Never publish the link.", "x-mcp-tool": "create_free_report", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateFreeReportInput" } } } }, "responses": { "202": { "description": "Accepted: the report is queued.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateFreeReportOutput" } } } }, "400": { "$ref": "#/components/responses/Error400" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "410": { "$ref": "#/components/responses/Error410" }, "413": { "$ref": "#/components/responses/ErrorBodyTooLarge" }, "415": { "$ref": "#/components/responses/ErrorUnsupportedMediaType" }, "422": { "$ref": "#/components/responses/Error422" }, "429": { "$ref": "#/components/responses/Error429" }, "500": { "$ref": "#/components/responses/Error500" }, "503": { "$ref": "#/components/responses/Error503" } } } }, "/jobs/{jobId}": { "get": { "operationId": "getJobStatus", "summary": "Status of a requested report", "description": "Status of a report requested with `POST /reports/free` (`queued`, `in_progress` and `ready`; or `failed`, `expired`). Orders opened before the service became free keep their payment states (`awaiting_payment`, `payment_received`, `payment_expired`, `refunded`). When it is `ready`, returns the private link. The `statusToken` given when the report was created goes in `Authorization: Bearer `, never in the URL.", "x-mcp-tool": "get_report_status", "parameters": [ { "name": "language", "in": "query", "required": false, "schema": { "default": "es", "type": "string", "enum": [ "es", "en", "de", "nl", "fr" ] } }, { "name": "jobId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^scr_[A-Za-z0-9_-]{22}$" } } ], "security": [ { "statusToken": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetJobStatusOutput" } } } }, "400": { "$ref": "#/components/responses/Error400" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "410": { "$ref": "#/components/responses/Error410" }, "422": { "$ref": "#/components/responses/Error422" }, "429": { "$ref": "#/components/responses/Error429" }, "500": { "$ref": "#/components/responses/Error500" }, "503": { "$ref": "#/components/responses/Error503" } } } }, "/reports/purchase": { "post": { "operationId": "purchaseReport", "summary": "Not available: every report is free", "description": "Not available: every report is free; use `POST /reports/free` (MCP tool `create_free_report`). The operation stays in the contract for compatibility and answers 409 `NOT_FOR_SALE` without creating anything.", "x-mcp-tool": "purchase_report", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseReportInput" } } } }, "responses": { "201": { "description": "Not returned while every report is free: the answer is 409 `NOT_FOR_SALE`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseReportOutput" } } } }, "400": { "$ref": "#/components/responses/Error400" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "410": { "$ref": "#/components/responses/Error410" }, "413": { "$ref": "#/components/responses/ErrorBodyTooLarge" }, "415": { "$ref": "#/components/responses/ErrorUnsupportedMediaType" }, "422": { "$ref": "#/components/responses/Error422" }, "429": { "$ref": "#/components/responses/Error429" }, "500": { "$ref": "#/components/responses/Error500" }, "503": { "$ref": "#/components/responses/Error503" } } } } }, "components": { "schemas": { "GetProductsOutput": { "type": "object", "properties": { "contract": { "type": "string", "const": "agent-api-1.3.0" }, "language": { "type": "string", "enum": [ "es", "en", "de", "nl", "fr" ] }, "productMode": { "type": "string", "enum": [ "commercial", "free" ] }, "currency": { "type": "string", "const": "EUR" }, "vatIncluded": { "type": "boolean", "const": true }, "priceNote": { "type": "string", "minLength": 1, "maxLength": 600 }, "products": { "minItems": 1, "maxItems": 3, "type": "array", "items": { "type": "object", "properties": { "tier": { "type": "string", "enum": [ "free", "simple", "complete" ] }, "name": { "type": "string", "minLength": 1, "maxLength": 600 }, "priceCents": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "price": { "type": "string", "minLength": 1, "maxLength": 600 }, "description": { "type": "string", "minLength": 1, "maxLength": 600 }, "requiresBuildingConditionRecord": { "type": "boolean" }, "format": { "type": "string", "enum": [ "redacted_web_preview", "web_and_pdf" ] }, "emailRequired": { "type": "boolean" }, "orderChannel": { "type": "string", "enum": [ "agent_api", "web" ] } }, "required": [ "tier", "name", "priceCents", "price", "description", "requiresBuildingConditionRecord", "format", "emailRequired", "orderChannel" ], "additionalProperties": false } }, "upgrade": { "anyOf": [ { "type": "object", "properties": { "from": { "type": "string", "const": "simple" }, "to": { "type": "string", "const": "complete" }, "priceCents": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "price": { "type": "string", "minLength": 1, "maxLength": 600 } }, "required": [ "from", "to", "priceCents", "price" ], "additionalProperties": false }, { "type": "null" } ] }, "freeReportLimits": { "type": "object", "properties": { "perEmail": { "type": "object", "properties": { "count": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "windowDays": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 } }, "required": [ "count", "windowDays" ], "additionalProperties": false }, "note": { "type": "string", "minLength": 1, "maxLength": 600 }, "agentChannelPerDay": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 } }, "required": [ "note" ], "additionalProperties": false }, "capacity": { "type": "object", "properties": { "maxActiveClients": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "clientIdleSeconds": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "maxReportsInProgressPerClient": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "note": { "type": "string", "minLength": 1, "maxLength": 600 } }, "required": [ "maxActiveClients", "clientIdleSeconds", "maxReportsInProgressPerClient", "note" ], "additionalProperties": false }, "consent": { "type": "object", "properties": { "text": { "type": "string", "minLength": 1, "maxLength": 2000 }, "statementSha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "termsVersion": { "type": "string", "minLength": 1, "maxLength": 16 }, "termsUrl": { "type": "string", "maxLength": 400, "pattern": "^https:\\/\\/[^\\s]+$" }, "agentContractingTermsUrl": { "type": "string", "maxLength": 400, "pattern": "^https:\\/\\/[^\\s]+$" }, "privacyUrl": { "type": "string", "maxLength": 400, "pattern": "^https:\\/\\/[^\\s]+$" } }, "required": [ "text", "statementSha256", "termsVersion", "termsUrl", "privacyUrl" ], "additionalProperties": false }, "checksCount": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "pricingUrl": { "type": "string", "maxLength": 400, "pattern": "^https:\\/\\/[^\\s]+$" }, "orderUrl": { "type": "string", "maxLength": 400, "pattern": "^https:\\/\\/[^\\s]+$" }, "exampleReportUrl": { "type": "string", "maxLength": 400, "pattern": "^https:\\/\\/[^\\s]+$" }, "disclaimer": { "type": "string", "minLength": 1, "maxLength": 600 } }, "required": [ "contract", "language", "currency", "vatIncluded", "priceNote", "products", "consent", "checksCount", "pricingUrl", "orderUrl", "exampleReportUrl", "disclaimer" ], "additionalProperties": false }, "ListChecksOutput": { "type": "object", "properties": { "contract": { "type": "string", "const": "agent-api-1.3.0" }, "language": { "type": "string", "enum": [ "es", "en", "de", "nl", "fr" ] }, "count": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "checks": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "number": { "type": "integer", "minimum": 1, "maximum": 99 }, "key": { "type": "string", "enum": [ "aluminosis", "iee", "risks_by_year", "asbestos", "cadastral_record", "building_condition", "energy_certificate", "land_history", "ground_motion", "geology_and_drainage", "flooding", "seismic", "radon", "sun_hours", "solar_potential", "price_and_market", "surroundings_and_noise", "land_affections", "land_classification", "climate_and_light", "wildfire", "industrial_facilities", "public_safety" ] }, "title": { "type": "string", "minLength": 1, "maxLength": 600 }, "question": { "type": "string", "minLength": 1, "maxLength": 600 }, "integration": { "type": "string", "enum": [ "integrated", "pending_integration" ] }, "includedIn": { "minItems": 1, "type": "array", "items": { "type": "string", "enum": [ "free", "simple", "complete" ] } } }, "required": [ "number", "key", "title", "question", "integration", "includedIn" ], "additionalProperties": false } }, "semaphore": { "type": "object", "properties": { "ok": { "type": "string", "minLength": 1, "maxLength": 600 }, "attention": { "type": "string", "minLength": 1, "maxLength": 600 }, "no_data": { "type": "string", "minLength": 1, "maxLength": 600 }, "not_included": { "type": "string", "minLength": 1, "maxLength": 600 } }, "required": [ "ok", "attention", "no_data", "not_included" ], "additionalProperties": false }, "methodologyUrl": { "type": "string", "maxLength": 400, "pattern": "^https:\\/\\/[^\\s]+$" } }, "required": [ "contract", "language", "count", "checks", "semaphore", "methodologyUrl" ], "additionalProperties": false }, "CheckCoverageOutput": { "type": "object", "properties": { "contract": { "type": "string", "const": "agent-api-1.3.0" }, "language": { "type": "string", "enum": [ "es", "en", "de", "nl", "fr" ] }, "provinces": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "provinceCode": { "anyOf": [ { "type": "string", "pattern": "^\\d{2}$" }, { "type": "null" } ] }, "provinceLabel": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 120 }, { "type": "null" } ] }, "territoryCode": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 64 }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "covered", "not_yet_covered", "unrecognized" ] }, "foral": { "type": "boolean" }, "addressSource": { "anyOf": [ { "type": "string", "enum": [ "dgc", "nora_foral_cadastres" ] }, { "type": "null" } ] }, "unitSelection": { "anyOf": [ { "type": "string", "enum": [ "dwelling_or_building", "building_only" ] }, { "type": "null" } ] }, "buildingConditionRegistry": { "anyOf": [ { "type": "string", "enum": [ "integrated", "not_integrated" ] }, { "type": "null" } ] }, "reason": { "anyOf": [ { "type": "string", "enum": [ "foral_adapter_pending", "not_a_spanish_province" ] }, { "type": "null" } ] }, "note": { "type": "string", "minLength": 1, "maxLength": 600 } }, "required": [ "provinceCode", "provinceLabel", "territoryCode", "status", "foral", "addressSource", "unitSelection", "buildingConditionRegistry", "reason", "note" ], "additionalProperties": false } }, "municipalities": { "anyOf": [ { "maxItems": 20, "type": "array", "items": { "type": "object", "properties": { "provinceCode": { "type": "string", "pattern": "^\\d{2}$" }, "municipalityDgcCode": { "type": "string", "pattern": "^\\d{1,3}$" }, "municipalityIneCode": { "type": "string", "pattern": "^\\d{3}$" }, "officialLabel": { "type": "string", "minLength": 1, "maxLength": 120 } }, "required": [ "provinceCode", "municipalityDgcCode", "municipalityIneCode", "officialLabel" ], "additionalProperties": false } }, { "type": "null" } ] }, "municipalityLookup": { "type": "string", "enum": [ "not_requested", "found", "not_found", "unavailable" ] }, "coverageNote": { "type": "string", "minLength": 1, "maxLength": 600 } }, "required": [ "contract", "language", "provinces", "municipalities", "municipalityLookup", "coverageNote" ], "additionalProperties": false }, "SearchAddressOutput": { "anyOf": [ { "type": "object", "properties": { "contract": { "type": "string", "const": "agent-api-1.3.0" }, "language": { "type": "string", "enum": [ "es", "en", "de", "nl", "fr" ] }, "kind": { "type": "string", "const": "municipality" }, "options": { "maxItems": 20, "type": "array", "items": { "type": "object", "properties": { "provinceCode": { "type": "string", "pattern": "^\\d{2}$" }, "municipalityDgcCode": { "type": "string", "pattern": "^\\d{1,3}$" }, "municipalityIneCode": { "type": "string", "pattern": "^\\d{3}$" }, "officialLabel": { "type": "string", "minLength": 1, "maxLength": 120 } }, "required": [ "provinceCode", "municipalityDgcCode", "municipalityIneCode", "officialLabel" ], "additionalProperties": false } } }, "required": [ "contract", "language", "kind", "options" ], "additionalProperties": false }, { "type": "object", "properties": { "contract": { "type": "string", "const": "agent-api-1.3.0" }, "language": { "type": "string", "enum": [ "es", "en", "de", "nl", "fr" ] }, "kind": { "type": "string", "const": "street" }, "numberHint": { "type": "string", "minLength": 1, "maxLength": 16 }, "options": { "maxItems": 20, "type": "array", "items": { "type": "object", "properties": { "provinceCode": { "type": "string", "pattern": "^\\d{2}$" }, "municipalityDgcCode": { "type": "string", "pattern": "^\\d{1,3}$" }, "municipalityIneCode": { "type": "string", "pattern": "^\\d{3}$" }, "officialLabel": { "type": "string", "minLength": 1, "maxLength": 120 }, "streetTypeCode": { "type": "string", "pattern": "^[A-Z0-9]{1,4}$" }, "streetCode": { "type": "string", "pattern": "^[A-Z0-9]{1,15}$" }, "streetTypeLabel": { "type": "string", "minLength": 1, "maxLength": 120 }, "localityId": { "type": "string", "pattern": "^[0-9]{14}$" }, "localityLabel": { "type": "string", "minLength": 1, "maxLength": 120 } }, "required": [ "provinceCode", "municipalityDgcCode", "municipalityIneCode", "officialLabel", "streetTypeCode", "streetCode" ], "additionalProperties": false } } }, "required": [ "contract", "language", "kind", "options" ], "additionalProperties": false } ] }, "ResolveBuildingOutput": { "type": "object", "properties": { "contract": { "type": "string", "const": "agent-api-1.3.0" }, "language": { "type": "string", "enum": [ "es", "en", "de", "nl", "fr" ] }, "status": { "type": "string", "enum": [ "resolved", "select_unit", "not_found", "unconfirmed" ] }, "evaluationScope": { "anyOf": [ { "type": "string", "enum": [ "building", "dwelling" ] }, { "type": "null" } ] }, "building": { "anyOf": [ { "type": "object", "properties": { "cadastralReference": { "type": "string", "pattern": "^[A-Z0-9]{14,20}$" }, "rc14": { "type": "string", "pattern": "^[A-Z0-9]{14}$" }, "address": { "type": "string", "minLength": 1, "maxLength": 120 }, "postalCode": { "type": "string", "pattern": "^\\d{5}$" }, "municipality": { "type": "string", "minLength": 1, "maxLength": 120 }, "province": { "type": "string", "minLength": 1, "maxLength": 120 }, "use": { "type": "string", "minLength": 1, "maxLength": 80 }, "surfaceAreaM2": { "type": "number", "exclusiveMinimum": 0 }, "constructionYear": { "type": "integer", "minimum": 1000, "maximum": 2100 }, "stair": { "type": "string", "minLength": 1, "maxLength": 16 }, "floor": { "type": "string", "minLength": 1, "maxLength": 16 }, "door": { "type": "string", "minLength": 1, "maxLength": 16 } }, "required": [ "cadastralReference", "rc14" ], "additionalProperties": false }, { "type": "null" } ] }, "candidates": { "maxItems": 200, "type": "array", "items": { "type": "object", "properties": { "cadastralReference": { "type": "string", "pattern": "^[A-Z0-9]{14,20}$" }, "rc14": { "type": "string", "pattern": "^[A-Z0-9]{14}$" }, "address": { "type": "string", "minLength": 1, "maxLength": 120 }, "postalCode": { "type": "string", "pattern": "^\\d{5}$" }, "municipality": { "type": "string", "minLength": 1, "maxLength": 120 }, "province": { "type": "string", "minLength": 1, "maxLength": 120 }, "use": { "type": "string", "minLength": 1, "maxLength": 80 }, "surfaceAreaM2": { "type": "number", "exclusiveMinimum": 0 }, "constructionYear": { "type": "integer", "minimum": 1000, "maximum": 2100 }, "stair": { "type": "string", "minLength": 1, "maxLength": 16 }, "floor": { "type": "string", "minLength": 1, "maxLength": 16 }, "door": { "type": "string", "minLength": 1, "maxLength": 16 } }, "required": [ "cadastralReference", "rc14" ], "additionalProperties": false } }, "availableNumbers": { "maxItems": 40, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 16 } }, "resolutionToken": { "anyOf": [ { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" }, { "type": "null" } ] }, "resolutionExpiresInSeconds": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, { "type": "null" } ] }, "ieeAvailability": { "anyOf": [ { "type": "string", "enum": [ "available", "none", "not_integrated", "unverified" ] }, { "type": "null" } ] }, "availableTiers": { "maxItems": 3, "type": "array", "items": { "type": "string", "enum": [ "free", "simple", "complete" ] } }, "notice": { "type": "string", "minLength": 1, "maxLength": 600 } }, "required": [ "contract", "language", "status", "evaluationScope", "building", "candidates", "resolutionToken", "resolutionExpiresInSeconds", "ieeAvailability", "availableTiers", "notice" ], "additionalProperties": false }, "ResolveBuildingInput": { "anyOf": [ { "type": "object", "properties": { "language": { "default": "es", "type": "string", "enum": [ "es", "en", "de", "nl", "fr" ] }, "cadastralReference": { "type": "string", "pattern": "^[A-Z0-9]{14}([A-Z0-9]{4}|[A-Z0-9]{6})?$" }, "scope": { "type": "string", "const": "building" } }, "required": [ "cadastralReference" ], "additionalProperties": false }, { "type": "object", "properties": { "language": { "default": "es", "type": "string", "enum": [ "es", "en", "de", "nl", "fr" ] }, "address": { "type": "object", "properties": { "provinceCode": { "type": "string", "pattern": "^\\d{2}$" }, "municipalityDgcCode": { "type": "string", "pattern": "^\\d{1,3}$" }, "municipalityIneCode": { "type": "string", "pattern": "^\\d{3}$" }, "streetTypeCode": { "type": "string", "pattern": "^[A-Z0-9]{1,4}$" }, "streetCode": { "type": "string", "pattern": "^[A-Z0-9]{1,15}$" }, "number": { "type": "string", "minLength": 1, "maxLength": 16, "pattern": "^[\\p{L}\\p{N}/ -]+$" }, "localityId": { "type": "string", "pattern": "^[0-9]{14}$" }, "block": { "type": "string", "minLength": 1, "maxLength": 16, "pattern": "^[\\p{L}\\p{N}/ .-]+$" }, "stair": { "type": "string", "minLength": 1, "maxLength": 16, "pattern": "^[\\p{L}\\p{N}/ .-]+$" }, "floor": { "type": "string", "minLength": 1, "maxLength": 16, "pattern": "^[\\p{L}\\p{N}/ .-]+$" }, "door": { "type": "string", "minLength": 1, "maxLength": 16, "pattern": "^[\\p{L}\\p{N}/ .-]+$" } }, "required": [ "provinceCode", "municipalityDgcCode", "municipalityIneCode", "streetTypeCode", "streetCode", "number" ], "additionalProperties": false } }, "required": [ "address" ], "additionalProperties": false } ] }, "CreateFreeReportOutput": { "type": "object", "properties": { "contract": { "type": "string", "const": "agent-api-1.3.0" }, "language": { "type": "string", "enum": [ "es", "en", "de", "nl", "fr" ] }, "jobId": { "type": "string", "pattern": "^scr_[A-Za-z0-9_-]{22}$" }, "status": { "type": "string", "const": "queued" }, "statusToken": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}\\.[A-Za-z0-9_-]{43}$" }, "previewUrl": { "type": "string", "maxLength": 400, "pattern": "^https:\\/\\/[^\\s]+$" }, "pollAfterSeconds": { "type": "integer", "minimum": 1, "maximum": 600 }, "emailNotice": { "type": "boolean" }, "notice": { "type": "string", "minLength": 1, "maxLength": 600 } }, "required": [ "contract", "language", "jobId", "status", "statusToken", "previewUrl", "pollAfterSeconds", "emailNotice", "notice" ], "additionalProperties": false }, "CreateFreeReportInput": { "type": "object", "properties": { "language": { "default": "es", "type": "string", "enum": [ "es", "en", "de", "nl", "fr" ] }, "resolutionToken": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" }, "consent": { "type": "boolean", "const": true }, "consentStatementSha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "email": { "type": "string", "minLength": 6, "maxLength": 254, "pattern": "^[^\\s@]+@[^\\s@]+\\.[^\\s@]{2,}$" } }, "required": [ "resolutionToken", "consent", "consentStatementSha256" ], "additionalProperties": false }, "GetJobStatusOutput": { "type": "object", "properties": { "contract": { "type": "string", "const": "agent-api-1.3.0" }, "language": { "type": "string", "enum": [ "es", "en", "de", "nl", "fr" ] }, "jobId": { "type": "string", "pattern": "^scr_[A-Za-z0-9_-]{22}$" }, "status": { "type": "string", "enum": [ "awaiting_payment", "payment_received", "queued", "in_progress", "ready", "failed", "expired", "payment_expired", "refunded" ] }, "stage": { "anyOf": [ { "type": "string", "pattern": "^[A-Z0-9_]{1,64}$" }, { "type": "null" } ] }, "queuePosition": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "estimatedSeconds": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "previewUrl": { "type": "string", "maxLength": 400, "pattern": "^https:\\/\\/[^\\s]+$" }, "withLimitations": { "type": "boolean" }, "errorCode": { "type": "string", "pattern": "^[A-Z0-9_]{1,100}$" }, "pollAfterSeconds": { "type": "integer", "minimum": 1, "maximum": 600 }, "payment": { "type": "object", "properties": { "orderId": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "status": { "type": "string", "enum": [ "pending", "paid", "expired", "failed", "refunded" ] } }, "required": [ "orderId", "status" ], "additionalProperties": false }, "notice": { "type": "string", "minLength": 1, "maxLength": 600 } }, "required": [ "contract", "language", "jobId", "status", "stage", "notice" ], "additionalProperties": false }, "PurchaseReportOutput": { "type": "object", "properties": { "contract": { "type": "string", "const": "agent-api-1.3.0" }, "language": { "type": "string", "enum": [ "es", "en", "de", "nl", "fr" ] }, "orderId": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "status": { "type": "string", "const": "awaiting_payment" }, "tier": { "type": "string", "enum": [ "simple", "complete" ] }, "name": { "type": "string", "minLength": 1, "maxLength": 600 }, "priceCents": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "price": { "type": "string", "minLength": 1, "maxLength": 600 }, "currency": { "type": "string", "const": "EUR" }, "vatIncluded": { "type": "boolean", "const": true }, "checkoutUrl": { "type": "string", "maxLength": 2048, "pattern": "^https:\\/\\/checkout\\.stripe\\.com\\/\\S+$" }, "checkoutExpiresAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "jobId": { "type": "string", "pattern": "^scr_[A-Za-z0-9_-]{22}$" }, "statusToken": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}\\.[A-Za-z0-9_-]{43}$" }, "reportUrl": { "type": "string", "maxLength": 400, "pattern": "^https:\\/\\/[^\\s]+$" }, "pollAfterSeconds": { "type": "integer", "minimum": 1, "maximum": 600 }, "termsVersion": { "type": "string", "minLength": 1, "maxLength": 16 }, "agentContractingTermsUrl": { "type": "string", "maxLength": 400, "pattern": "^https:\\/\\/[^\\s]+$" }, "notice": { "type": "string", "minLength": 1, "maxLength": 600 } }, "required": [ "contract", "language", "orderId", "status", "tier", "name", "priceCents", "price", "currency", "vatIncluded", "checkoutUrl", "checkoutExpiresAt", "jobId", "statusToken", "reportUrl", "pollAfterSeconds", "termsVersion", "agentContractingTermsUrl", "notice" ], "additionalProperties": false }, "PurchaseReportInput": { "type": "object", "properties": { "language": { "default": "es", "type": "string", "enum": [ "es", "en", "de", "nl", "fr" ] }, "tier": { "type": "string", "enum": [ "simple", "complete" ] }, "resolutionToken": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" }, "freeReport": { "type": "object", "properties": { "jobId": { "type": "string", "pattern": "^scr_[A-Za-z0-9_-]{22}$" }, "statusToken": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}\\.[A-Za-z0-9_-]{43}$" } }, "required": [ "jobId", "statusToken" ], "additionalProperties": false }, "email": { "type": "string", "minLength": 6, "maxLength": 254, "pattern": "^[^\\s@]+@[^\\s@]+\\.[^\\s@]{2,}$" }, "consent": { "type": "boolean", "const": true }, "consentStatementSha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "termsVersion": { "type": "string", "minLength": 1, "maxLength": 16 }, "acceptTerms": { "type": "boolean", "const": true }, "waiveWithdrawalRight": { "type": "boolean", "const": true } }, "required": [ "tier", "email", "consent", "consentStatementSha256", "termsVersion", "acceptTerms", "waiveWithdrawalRight" ], "additionalProperties": false }, "AgentApiError": { "type": "object", "properties": { "contract": { "type": "string", "const": "agent-api-1.3.0" }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "INVALID_REQUEST", "INVALID_ADDRESS", "PROVINCE_REQUIRED", "OUTSIDE_REPORT_COVERAGE", "BUILDING_NOT_SELECTED", "RESOLUTION_EXPIRED", "CONSENT_STATEMENT_OUTDATED", "COMPLETE_TIER_UNAVAILABLE", "RESOLUTION_ALREADY_USED", "REPORT_NOT_READY", "ALREADY_PURCHASED", "PURCHASE_NOT_AVAILABLE", "NOT_FOR_SALE", "JOB_NOT_FOUND", "FREE_REPORT_EMAIL_LIMIT_REACHED", "FREE_REPORT_IP_LIMIT_REACHED", "FREE_REPORT_DAILY_CAPACITY_REACHED", "AGENT_DAILY_CAPACITY_REACHED", "CLIENT_LIMIT", "CHANNEL_AT_CAPACITY", "QUEUE_FULL", "PAYMENTS_UNAVAILABLE", "SOURCE_UNAVAILABLE", "SERVICE_UNAVAILABLE", "INTERNAL_ERROR" ] }, "message": { "type": "string", "minLength": 1, "maxLength": 300 }, "retryAfterSeconds": { "type": "integer", "minimum": 1, "maximum": 1209600 } }, "required": [ "code", "message" ], "additionalProperties": false } }, "required": [ "contract", "error" ], "additionalProperties": false } }, "responses": { "Error400": { "description": "Error with one of these codes in `error.code`: INVALID_REQUEST, INVALID_ADDRESS, PROVINCE_REQUIRED.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentApiError" } } } }, "Error404": { "description": "Error with one of these codes in `error.code`: JOB_NOT_FOUND.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentApiError" } } } }, "Error409": { "description": "Error with one of these codes in `error.code`: BUILDING_NOT_SELECTED, CONSENT_STATEMENT_OUTDATED, COMPLETE_TIER_UNAVAILABLE, RESOLUTION_ALREADY_USED, REPORT_NOT_READY, ALREADY_PURCHASED, PURCHASE_NOT_AVAILABLE, NOT_FOR_SALE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentApiError" } } } }, "Error410": { "description": "Error with one of these codes in `error.code`: RESOLUTION_EXPIRED.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentApiError" } } } }, "Error422": { "description": "Error with one of these codes in `error.code`: OUTSIDE_REPORT_COVERAGE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentApiError" } } } }, "Error429": { "description": "Error with one of these codes in `error.code`: FREE_REPORT_EMAIL_LIMIT_REACHED, FREE_REPORT_IP_LIMIT_REACHED, FREE_REPORT_DAILY_CAPACITY_REACHED, AGENT_DAILY_CAPACITY_REACHED, CLIENT_LIMIT.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying (also in `error.retryAfterSeconds`).", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentApiError" } } } }, "Error500": { "description": "Error with one of these codes in `error.code`: INTERNAL_ERROR.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentApiError" } } } }, "Error503": { "description": "Error with one of these codes in `error.code`: CHANNEL_AT_CAPACITY, QUEUE_FULL, PAYMENTS_UNAVAILABLE, SOURCE_UNAVAILABLE, SERVICE_UNAVAILABLE.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying (also in `error.retryAfterSeconds`).", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentApiError" } } } }, "ErrorBodyTooLarge": { "description": "Error `INVALID_REQUEST`: the body is larger than 16384 bytes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentApiError" } } } }, "ErrorUnsupportedMediaType": { "description": "Error `INVALID_REQUEST`: the body must be sent with `Content-Type: application/json`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentApiError" } } } } }, "securitySchemes": { "statusToken": { "type": "http", "scheme": "bearer", "description": "The `statusToken` returned by `POST /reports/free` or `POST /reports/purchase`: only whoever holds it sees the status and the link." } } } }