{"openapi":"3.2.0","info":{"title":"Spanish Company CIF NIF Lookup from Website API","description":"Extract a Spanish company CIF/NIF and legal name from its website. Checks the NIF control character and legal-page context, with a source path for CRM enrichment and supplier onboarding.","version":"1.0.0"},"servers":[{"url":"https://tdrgc.jojapi.net"}],"security":[{"ApiKeyAuth":[]}],"tags":[{"name":"Company data"}],"x-agent-commerce":{"catalog_url":"https://tdrgc.jojapi.net/_jojapi/agent/plans","discovery_url":"https://tdrgc.jojapi.net/.well-known/x402","directory_url":"https://agents.jojapi.net/apis/spanish-company-tax-data","docs":"https://docs.jojapi.com/consumers/agents"},"paths":{"/v1/extract":{"post":{"operationId":"post_v1_extract","summary":"Extract a Spanish company identity from a website","description":"Checks the homepage and same-site legal/contact pages. Accepts one URL per request. Supports implemented Spanish limited company, public limited company and cooperative forms; does not execute JavaScript or read PDFs/images. A completed lookup without a match can consume a billable query. Gateway authentication and subscription errors may use the marketplace response format.","tags":["Company data"],"responses":{"200":{"description":"A unique company identity was associated and its tax identifier passed formal validation. The example is fictional.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["success","domain","legal_name","tax_id","tax_id_valid","tax_address","found_at"],"properties":{"success":{"type":"boolean","enum":[true]},"domain":{"type":"string","example":"comercial-horizonte.es","description":"Normalized hostname without a leading www. Other subdomains are preserved."},"legal_name":{"type":"string","minLength":1,"example":"Comercial Horizonte SL","description":"Legal company name associated with the corporate tax identifier."},"tax_id":{"type":"string","pattern":"^[ABCDEFGHJNPQRSUVW][0-9]{7}[0-9A-J]$","minLength":9,"maxLength":9,"example":"B12345674","description":"Spanish corporate tax identifier with a valid structure and check character. Personal DNI/NIE identifiers are excluded."},"tax_id_valid":{"type":"boolean","enum":[true],"description":"Formal validity only. This does not certify registration, existence, activity or website ownership."},"tax_address":{"type":"string","nullable":true,"description":"Explicitly labelled and attributable fiscal address; null when missing or conflicting."},"found_at":{"type":"string","pattern":"^/","example":"/aviso-legal","description":"Source page path, without a query string."}}},"example":{"success":true,"domain":"comercial-horizonte.es","legal_name":"Comercial Horizonte SL","tax_id":"B12345674","tax_id_valid":true,"tax_address":"Calle Mayor 1, 28013 Madrid","found_at":"/aviso-legal"}}}},"400":{"description":"Invalid JSON, input schema or public website URL.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["success","domain","legal_name","tax_id","tax_id_valid","tax_address","found_at","error"],"properties":{"success":{"type":"boolean","enum":[false]},"domain":{"type":"string","nullable":true,"description":"Normalized hostname if established; otherwise null."},"legal_name":{"type":"string","nullable":true,"enum":[null]},"tax_id":{"type":"string","nullable":true,"enum":[null]},"tax_id_valid":{"type":"boolean","enum":[false]},"tax_address":{"type":"string","nullable":true,"enum":[null]},"found_at":{"type":"string","nullable":true,"enum":[null]},"error":{"type":"object","additionalProperties":false,"required":["code","message"],"properties":{"code":{"type":"string","enum":["invalid_url","invalid_request","request_too_large","unsupported_media_type","unauthorized","not_configured","not_found","invalid_tax_id","ambiguous","upstream_unavailable","timeout","internal_error","route_not_found","method_not_allowed"]},"message":{"type":"string","description":"Human-readable message returned by the origin, currently in Spanish. Use the HTTP status and code for client logic."}}}}}}}},"401":{"description":"Authentication failed. Check your JoJ API key and subscription. Gateway errors can use a different body.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["success","domain","legal_name","tax_id","tax_id_valid","tax_address","found_at","error"],"properties":{"success":{"type":"boolean","enum":[false]},"domain":{"type":"string","nullable":true,"description":"Normalized hostname if established; otherwise null."},"legal_name":{"type":"string","nullable":true,"enum":[null]},"tax_id":{"type":"string","nullable":true,"enum":[null]},"tax_id_valid":{"type":"boolean","enum":[false]},"tax_address":{"type":"string","nullable":true,"enum":[null]},"found_at":{"type":"string","nullable":true,"enum":[null]},"error":{"type":"object","additionalProperties":false,"required":["code","message"],"properties":{"code":{"type":"string","enum":["invalid_url","invalid_request","request_too_large","unsupported_media_type","unauthorized","not_configured","not_found","invalid_tax_id","ambiguous","upstream_unavailable","timeout","internal_error","route_not_found","method_not_allowed"]},"message":{"type":"string","description":"Human-readable message returned by the origin, currently in Spanish. Use the HTTP status and code for client logic."}}}}}}}},"402":{"description":"Gateway billing rejection: insufficient balance, exhausted quota or a plan that does not cover this endpoint."},"403":{"description":"Gateway access rejection: the consumer key is restricted or the account cannot access this API."},"404":{"description":"No usable company identity was found. A completed lookup can consume a billable query.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["success","domain","legal_name","tax_id","tax_id_valid","tax_address","found_at","error"],"properties":{"success":{"type":"boolean","enum":[false]},"domain":{"type":"string","nullable":true,"description":"Normalized hostname if established; otherwise null."},"legal_name":{"type":"string","nullable":true,"enum":[null]},"tax_id":{"type":"string","nullable":true,"enum":[null]},"tax_id_valid":{"type":"boolean","enum":[false]},"tax_address":{"type":"string","nullable":true,"enum":[null]},"found_at":{"type":"string","nullable":true,"enum":[null]},"error":{"type":"object","additionalProperties":false,"required":["code","message"],"properties":{"code":{"type":"string","enum":["invalid_url","invalid_request","request_too_large","unsupported_media_type","unauthorized","not_configured","not_found","invalid_tax_id","ambiguous","upstream_unavailable","timeout","internal_error","route_not_found","method_not_allowed"]},"message":{"type":"string","description":"Human-readable message returned by the origin, currently in Spanish. Use the HTTP status and code for client logic."}}}}}}}},"405":{"description":"Method not allowed. This endpoint accepts POST.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["success","domain","legal_name","tax_id","tax_id_valid","tax_address","found_at","error"],"properties":{"success":{"type":"boolean","enum":[false]},"domain":{"type":"string","nullable":true,"description":"Normalized hostname if established; otherwise null."},"legal_name":{"type":"string","nullable":true,"enum":[null]},"tax_id":{"type":"string","nullable":true,"enum":[null]},"tax_id_valid":{"type":"boolean","enum":[false]},"tax_address":{"type":"string","nullable":true,"enum":[null]},"found_at":{"type":"string","nullable":true,"enum":[null]},"error":{"type":"object","additionalProperties":false,"required":["code","message"],"properties":{"code":{"type":"string","enum":["invalid_url","invalid_request","request_too_large","unsupported_media_type","unauthorized","not_configured","not_found","invalid_tax_id","ambiguous","upstream_unavailable","timeout","internal_error","route_not_found","method_not_allowed"]},"message":{"type":"string","description":"Human-readable message returned by the origin, currently in Spanish. Use the HTTP status and code for client logic."}}}}}}}},"409":{"description":"Conflicting company identities or an ambiguous association.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["success","domain","legal_name","tax_id","tax_id_valid","tax_address","found_at","error"],"properties":{"success":{"type":"boolean","enum":[false]},"domain":{"type":"string","nullable":true,"description":"Normalized hostname if established; otherwise null."},"legal_name":{"type":"string","nullable":true,"enum":[null]},"tax_id":{"type":"string","nullable":true,"enum":[null]},"tax_id_valid":{"type":"boolean","enum":[false]},"tax_address":{"type":"string","nullable":true,"enum":[null]},"found_at":{"type":"string","nullable":true,"enum":[null]},"error":{"type":"object","additionalProperties":false,"required":["code","message"],"properties":{"code":{"type":"string","enum":["invalid_url","invalid_request","request_too_large","unsupported_media_type","unauthorized","not_configured","not_found","invalid_tax_id","ambiguous","upstream_unavailable","timeout","internal_error","route_not_found","method_not_allowed"]},"message":{"type":"string","description":"Human-readable message returned by the origin, currently in Spanish. Use the HTTP status and code for client logic."}}}}}}}},"413":{"description":"The request body exceeds 2048 bytes or its declared length is invalid.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["success","domain","legal_name","tax_id","tax_id_valid","tax_address","found_at","error"],"properties":{"success":{"type":"boolean","enum":[false]},"domain":{"type":"string","nullable":true,"description":"Normalized hostname if established; otherwise null."},"legal_name":{"type":"string","nullable":true,"enum":[null]},"tax_id":{"type":"string","nullable":true,"enum":[null]},"tax_id_valid":{"type":"boolean","enum":[false]},"tax_address":{"type":"string","nullable":true,"enum":[null]},"found_at":{"type":"string","nullable":true,"enum":[null]},"error":{"type":"object","additionalProperties":false,"required":["code","message"],"properties":{"code":{"type":"string","enum":["invalid_url","invalid_request","request_too_large","unsupported_media_type","unauthorized","not_configured","not_found","invalid_tax_id","ambiguous","upstream_unavailable","timeout","internal_error","route_not_found","method_not_allowed"]},"message":{"type":"string","description":"Human-readable message returned by the origin, currently in Spanish. Use the HTTP status and code for client logic."}}}}}}}},"415":{"description":"Use Content-Type: application/json.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["success","domain","legal_name","tax_id","tax_id_valid","tax_address","found_at","error"],"properties":{"success":{"type":"boolean","enum":[false]},"domain":{"type":"string","nullable":true,"description":"Normalized hostname if established; otherwise null."},"legal_name":{"type":"string","nullable":true,"enum":[null]},"tax_id":{"type":"string","nullable":true,"enum":[null]},"tax_id_valid":{"type":"boolean","enum":[false]},"tax_address":{"type":"string","nullable":true,"enum":[null]},"found_at":{"type":"string","nullable":true,"enum":[null]},"error":{"type":"object","additionalProperties":false,"required":["code","message"],"properties":{"code":{"type":"string","enum":["invalid_url","invalid_request","request_too_large","unsupported_media_type","unauthorized","not_configured","not_found","invalid_tax_id","ambiguous","upstream_unavailable","timeout","internal_error","route_not_found","method_not_allowed"]},"message":{"type":"string","description":"Human-readable message returned by the origin, currently in Spanish. Use the HTTP status and code for client logic."}}}}}}}},"422":{"description":"An observed corporate tax identifier failed formal validation.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["success","domain","legal_name","tax_id","tax_id_valid","tax_address","found_at","error"],"properties":{"success":{"type":"boolean","enum":[false]},"domain":{"type":"string","nullable":true,"description":"Normalized hostname if established; otherwise null."},"legal_name":{"type":"string","nullable":true,"enum":[null]},"tax_id":{"type":"string","nullable":true,"enum":[null]},"tax_id_valid":{"type":"boolean","enum":[false]},"tax_address":{"type":"string","nullable":true,"enum":[null]},"found_at":{"type":"string","nullable":true,"enum":[null]},"error":{"type":"object","additionalProperties":false,"required":["code","message"],"properties":{"code":{"type":"string","enum":["invalid_url","invalid_request","request_too_large","unsupported_media_type","unauthorized","not_configured","not_found","invalid_tax_id","ambiguous","upstream_unavailable","timeout","internal_error","route_not_found","method_not_allowed"]},"message":{"type":"string","description":"Human-readable message returned by the origin, currently in Spanish. Use the HTTP status and code for client logic."}}}}}}}},"429":{"description":"A rate or quota limit was reached. Gateway errors can use a different body."},"500":{"description":"Internal processing error; no internal details are exposed.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["success","domain","legal_name","tax_id","tax_id_valid","tax_address","found_at","error"],"properties":{"success":{"type":"boolean","enum":[false]},"domain":{"type":"string","nullable":true,"description":"Normalized hostname if established; otherwise null."},"legal_name":{"type":"string","nullable":true,"enum":[null]},"tax_id":{"type":"string","nullable":true,"enum":[null]},"tax_id_valid":{"type":"boolean","enum":[false]},"tax_address":{"type":"string","nullable":true,"enum":[null]},"found_at":{"type":"string","nullable":true,"enum":[null]},"error":{"type":"object","additionalProperties":false,"required":["code","message"],"properties":{"code":{"type":"string","enum":["invalid_url","invalid_request","request_too_large","unsupported_media_type","unauthorized","not_configured","not_found","invalid_tax_id","ambiguous","upstream_unavailable","timeout","internal_error","route_not_found","method_not_allowed"]},"message":{"type":"string","description":"Human-readable message returned by the origin, currently in Spanish. Use the HTTP status and code for client logic."}}}}}}}},"502":{"description":"No usable public source page could be downloaded.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["success","domain","legal_name","tax_id","tax_id_valid","tax_address","found_at","error"],"properties":{"success":{"type":"boolean","enum":[false]},"domain":{"type":"string","nullable":true,"description":"Normalized hostname if established; otherwise null."},"legal_name":{"type":"string","nullable":true,"enum":[null]},"tax_id":{"type":"string","nullable":true,"enum":[null]},"tax_id_valid":{"type":"boolean","enum":[false]},"tax_address":{"type":"string","nullable":true,"enum":[null]},"found_at":{"type":"string","nullable":true,"enum":[null]},"error":{"type":"object","additionalProperties":false,"required":["code","message"],"properties":{"code":{"type":"string","enum":["invalid_url","invalid_request","request_too_large","unsupported_media_type","unauthorized","not_configured","not_found","invalid_tax_id","ambiguous","upstream_unavailable","timeout","internal_error","route_not_found","method_not_allowed"]},"message":{"type":"string","description":"Human-readable message returned by the origin, currently in Spanish. Use the HTTP status and code for client logic."}}}}}}}},"503":{"description":"The origin service is not available for authenticated extraction.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["success","domain","legal_name","tax_id","tax_id_valid","tax_address","found_at","error"],"properties":{"success":{"type":"boolean","enum":[false]},"domain":{"type":"string","nullable":true,"description":"Normalized hostname if established; otherwise null."},"legal_name":{"type":"string","nullable":true,"enum":[null]},"tax_id":{"type":"string","nullable":true,"enum":[null]},"tax_id_valid":{"type":"boolean","enum":[false]},"tax_address":{"type":"string","nullable":true,"enum":[null]},"found_at":{"type":"string","nullable":true,"enum":[null]},"error":{"type":"object","additionalProperties":false,"required":["code","message"],"properties":{"code":{"type":"string","enum":["invalid_url","invalid_request","request_too_large","unsupported_media_type","unauthorized","not_configured","not_found","invalid_tax_id","ambiguous","upstream_unavailable","timeout","internal_error","route_not_found","method_not_allowed"]},"message":{"type":"string","description":"Human-readable message returned by the origin, currently in Spanish. Use the HTTP status and code for client logic."}}}}}}}},"504":{"description":"The application time budget was exhausted.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["success","domain","legal_name","tax_id","tax_id_valid","tax_address","found_at","error"],"properties":{"success":{"type":"boolean","enum":[false]},"domain":{"type":"string","nullable":true,"description":"Normalized hostname if established; otherwise null."},"legal_name":{"type":"string","nullable":true,"enum":[null]},"tax_id":{"type":"string","nullable":true,"enum":[null]},"tax_id_valid":{"type":"boolean","enum":[false]},"tax_address":{"type":"string","nullable":true,"enum":[null]},"found_at":{"type":"string","nullable":true,"enum":[null]},"error":{"type":"object","additionalProperties":false,"required":["code","message"],"properties":{"code":{"type":"string","enum":["invalid_url","invalid_request","request_too_large","unsupported_media_type","unauthorized","not_configured","not_found","invalid_tax_id","ambiguous","upstream_unavailable","timeout","internal_error","route_not_found","method_not_allowed"]},"message":{"type":"string","description":"Human-readable message returned by the origin, currently in Spanish. Use the HTTP status and code for client logic."}}}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["url"],"properties":{"url":{"type":"string","minLength":4,"maxLength":1024,"x-max-utf16-code-units":1024,"example":"https://example.com/","description":"Public website hostname or HTTP/HTTPS URL. Normalized to the HTTPS origin. Paths and queries are discarded. Credentials, IP literals, private destinations, fragments and non-standard ports are rejected."}}},"example":{"url":"https://comercial-horizonte.es"}}}}}}},"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-JoJAPI-Key","description":"Your JoJ API key."}}}}