{ "openapi": "3.1.0", "info": { "title": "occasioni.it API", "version": "1.0.0", "description": "Italian opportunities, read every night from official sources: public grants and calls for businesses (occasioni.it), and for people who want a new job, a new town or a new home: remote jobs open to Italy, the 7,900 Italian municipalities, programmes that pay people to move (secondlife.it). Start with match_business (a company) or plan_preview (a person). Searching is free. Paid reports (eligibility check, application draft, personal plan, municipality dossier, remote-job kit) are ordered with create_order: with prepaid credit on the API key they are generated at once, otherwise you get a checkout_url for the user. Data is in Italian; always give the user the official link and the deadline. Every operation also accepts GET with query parameters. Same tools over MCP at /mcp." }, "servers": [ { "url": "https://occasioni.it" } ], "components": { "securitySchemes": { "bearer": { "type": "http", "scheme": "bearer", "description": "Optional API key (op_...). Free key at /sviluppatori" } } }, "security": [ [], { "bearer": [] } ], "paths": { "/api/v1/search_incentives": { "post": { "operationId": "search_incentives", "summary": "Cerca bandi e incentivi", "description": "Search Italian public grants, incentives and calls (national catalogue incentivi.gov.it plus regional and chamber-of-commerce calls), refreshed nightly. Open calls only by default. Text in Italian.", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "q": { "type": "string", "description": "Testo libero, es. \"digitalizzazione negozi\"" }, "region": { "type": "string", "description": "Regione", "enum": [ "Abruzzo", "Basilicata", "Calabria", "Campania", "Emilia-Romagna", "Friuli-Venezia Giulia", "Lazio", "Liguria", "Lombardia", "Marche", "Molise", "Piemonte", "Puglia", "Sardegna", "Sicilia", "Toscana", "Trentino-Alto Adige/Südtirol", "Umbria", "Valle d'Aosta/Vallée d'Aoste", "Veneto" ] }, "beneficiary": { "type": "string", "description": "Tipo di beneficiario", "enum": [ "Impresa", "Professionista", "Cooperative/Associazioni Non Profit", "Impresa - SU/PMI innovativa", "Impresa - prevalenza femminile", "Impresa - prevalenza giovanile", "Impresa da costituire - Altro", "Impresa da costituire - Giovanile", "Impresa da costituire - Femminile", "Cittadino", "Consorzio", "Rete d'impresa", "Ente Pubblico", "Università/Ente di Ricerca" ] }, "size": { "type": "string", "description": "Dimensione impresa", "enum": [ "Microimpresa", "Piccola Impresa", "Media Impresa", "Grande Impresa" ] }, "purpose": { "type": "string", "description": "Finalità", "enum": [ "Sostegno investimenti", "Sostegno liquidità", "Innovazione e ricerca", "Start up/Sviluppo d'impresa", "Transizione ecologica", "Internazionalizzazione", "Inclusione sociale", "Digitalizzazione", "Imprenditoria giovanile", "Imprenditoria femminile", "Crisi d'impresa", "Formazione (lavoro, occupazione, riqualificazione professionale dei lavoratori)", "Rafforzamento del capitale" ] }, "sector": { "type": "string", "description": "Settore", "enum": [ "Agricoltura, silvicoltura e pesca", "Agroalimentare", "Alberghiero", "Artigianato", "Autoveicoli e altri mezzi di trasporto", "Chimica e Farmaceutica", "Commercio", "Cultura", "Edilizia", "Elettronica", "Fornitura Energia, Acqua e gestione Rifiuti", "ICT", "Meccanica", "Metallurgia", "Mobili, Legno e Carta", "Moda e Tessile", "Ristorazione", "Salute", "Servizi di trasporto", "Turismo", "Altri servizi" ] }, "aid_form": { "type": "string", "description": "Forma di aiuto", "enum": [ "Contributo/Fondo perduto", "Prestito/Anticipo rimborsabile", "Interventi a garanzia", "Capitale di rischio", "Agevolazione fiscale" ] }, "closing_within_days": { "type": "integer", "description": "Solo bandi che chiudono entro N giorni", "minimum": 1, "maximum": 365 }, "min_amount": { "type": "integer", "description": "Contributo massimo almeno di N euro", "minimum": 0 }, "include_closed": { "type": "boolean", "description": "Includi anche i bandi chiusi" }, "sort": { "type": "string", "description": "Ordine", "enum": [ "deadline", "amount", "new", "relevance" ] }, "limit": { "type": "integer", "description": "Risultati (max 50)", "minimum": 1, "maximum": 50 }, "offset": { "type": "integer", "description": "Salta i primi N", "minimum": 0 } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object" } } } } } }, "400": { "description": "Bad input" }, "404": { "description": "Not found" }, "429": { "description": "Rate limit" } } } }, "/api/v1/get_incentive": { "post": { "operationId": "get_incentive", "summary": "Scheda completa di un bando", "description": "Full card of one incentive: requirements, beneficiaries, eligible costs, amounts, deadline, official link and the source summary.", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Id della scheda, es. \"incentivi:1000\"" } }, "required": [ "id" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object" } } } } } }, "400": { "description": "Bad input" }, "404": { "description": "Not found" }, "429": { "description": "Rate limit" } } } }, "/api/v1/match_business": { "post": { "operationId": "match_business", "summary": "Bandi adatti a un'attività", "description": "Ranks the open calls for a business profile and explains each score in plain Italian. No model call: a transparent database score.", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "region": { "type": "string", "description": "Regione della sede operativa", "enum": [ "Abruzzo", "Basilicata", "Calabria", "Campania", "Emilia-Romagna", "Friuli-Venezia Giulia", "Lazio", "Liguria", "Lombardia", "Marche", "Molise", "Piemonte", "Puglia", "Sardegna", "Sicilia", "Toscana", "Trentino-Alto Adige/Südtirol", "Umbria", "Valle d'Aosta/Vallée d'Aoste", "Veneto" ] }, "beneficiary": { "type": "string", "description": "Tipo di soggetto", "enum": [ "Impresa", "Professionista", "Cooperative/Associazioni Non Profit", "Impresa da costituire - Altro", "Impresa da costituire - Giovanile", "Impresa da costituire - Femminile" ] }, "size": { "type": "string", "description": "Dimensione", "enum": [ "Microimpresa", "Piccola Impresa", "Media Impresa", "Grande Impresa" ] }, "sector": { "type": "string", "description": "Settore", "enum": [ "Agricoltura, silvicoltura e pesca", "Agroalimentare", "Alberghiero", "Artigianato", "Autoveicoli e altri mezzi di trasporto", "Chimica e Farmaceutica", "Commercio", "Cultura", "Edilizia", "Elettronica", "Fornitura Energia, Acqua e gestione Rifiuti", "ICT", "Meccanica", "Metallurgia", "Mobili, Legno e Carta", "Moda e Tessile", "Ristorazione", "Salute", "Servizi di trasporto", "Turismo", "Altri servizi" ] }, "purposes": { "type": "array", "description": "Cosa vuole finanziare", "items": { "type": "string", "enum": [ "Sostegno investimenti", "Sostegno liquidità", "Innovazione e ricerca", "Start up/Sviluppo d'impresa", "Transizione ecologica", "Internazionalizzazione", "Inclusione sociale", "Digitalizzazione", "Imprenditoria giovanile", "Imprenditoria femminile", "Crisi d'impresa", "Formazione (lavoro, occupazione, riqualificazione professionale dei lavoratori)", "Rafforzamento del capitale" ] } }, "young": { "type": "boolean", "description": "Compagine prevalentemente under 36" }, "female": { "type": "boolean", "description": "Compagine prevalentemente femminile" }, "innovative": { "type": "boolean", "description": "Startup o PMI innovativa iscritta" }, "grant_only": { "type": "boolean", "description": "Solo contributi a fondo perduto" }, "description": { "type": "string", "description": "Descrizione libera dell'attività e del progetto (max 600 caratteri)" }, "limit": { "type": "integer", "description": "Risultati (max 50)", "minimum": 1, "maximum": 50 } }, "required": [ "region" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object" } } } } } }, "400": { "description": "Bad input" }, "404": { "description": "Not found" }, "429": { "description": "Rate limit" } } } }, "/api/v1/closing_soon": { "post": { "operationId": "closing_soon", "summary": "Bandi in scadenza", "description": "Open calls closing within N days (default 30), soonest first.", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "days": { "type": "integer", "description": "Giorni", "minimum": 1, "maximum": 180 }, "region": { "type": "string", "description": "Regione", "enum": [ "Abruzzo", "Basilicata", "Calabria", "Campania", "Emilia-Romagna", "Friuli-Venezia Giulia", "Lazio", "Liguria", "Lombardia", "Marche", "Molise", "Piemonte", "Puglia", "Sardegna", "Sicilia", "Toscana", "Trentino-Alto Adige/Südtirol", "Umbria", "Valle d'Aosta/Vallée d'Aoste", "Veneto" ] }, "limit": { "type": "integer", "description": "Risultati", "minimum": 1, "maximum": 50 } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object" } } } } } }, "400": { "description": "Bad input" }, "404": { "description": "Not found" }, "429": { "description": "Rate limit" } } } }, "/api/v1/catalogue_stats": { "post": { "operationId": "catalogue_stats", "summary": "Numeri del catalogo", "description": "Live numbers: open calls, calls closing in 30 days, grants, total budget, remote jobs, places, and per-region counts.", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": {} } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object" } } } } } }, "400": { "description": "Bad input" }, "404": { "description": "Not found" }, "429": { "description": "Rate limit" } } } }, "/api/v1/search_remote_jobs": { "post": { "operationId": "search_remote_jobs", "summary": "Lavori da remoto aperti all'Italia", "description": "Remote jobs workable from Italy (Jobicy, Remotive, Himalayas; credit and apply link kept). Filter by text or skill area.", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "q": { "type": "string", "description": "Testo libero, es. \"customer support\"" }, "skills": { "type": "array", "description": "Aree di competenza", "items": { "type": "string", "enum": [ "software", "design", "marketing", "sales", "support", "finance", "hr", "writing", "education", "health", "management" ] } }, "limit": { "type": "integer", "description": "Risultati", "minimum": 1, "maximum": 50 } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object" } } } } } }, "400": { "description": "Bad input" }, "404": { "description": "Not found" }, "429": { "description": "Rate limit" } } } }, "/api/v1/search_places": { "post": { "operationId": "search_places", "summary": "Comuni italiani", "description": "Italian municipalities (all 7,900) with population, coordinates and any programme that pays people to move there (1-euro houses, residence bonuses).", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "q": { "type": "string", "description": "Nome del comune" }, "region": { "type": "string", "description": "Regione", "enum": [ "Abruzzo", "Basilicata", "Calabria", "Campania", "Emilia-Romagna", "Friuli-Venezia Giulia", "Lazio", "Liguria", "Lombardia", "Marche", "Molise", "Piemonte", "Puglia", "Sardegna", "Sicilia", "Toscana", "Trentino-Alto Adige/Südtirol", "Umbria", "Valle d'Aosta/Vallée d'Aoste", "Veneto" ] }, "min_population": { "type": "integer", "description": "Popolazione minima", "minimum": 0 }, "max_population": { "type": "integer", "description": "Popolazione massima", "minimum": 0 }, "with_programmes": { "type": "boolean", "description": "Solo comuni con un programma per chi si trasferisce" }, "limit": { "type": "integer", "description": "Risultati", "minimum": 1, "maximum": 50 } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object" } } } } } }, "400": { "description": "Bad input" }, "404": { "description": "Not found" }, "429": { "description": "Rate limit" } } } }, "/api/v1/get_place": { "post": { "operationId": "get_place", "summary": "Scheda di un comune", "description": "One municipality: population, province, coordinates, programmes for new residents, and the regional incentives open to people.", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Id della scheda (es. \"comune:028001\") o codice ISTAT" } }, "required": [ "id" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object" } } } } } }, "400": { "description": "Bad input" }, "404": { "description": "Not found" }, "429": { "description": "Rate limit" } } } }, "/api/v1/relocation_programmes": { "post": { "operationId": "relocation_programmes", "summary": "Programmi per chi si trasferisce", "description": "Verified programmes that pay or help people to move: 1-euro houses, residence bonuses, subsidised homes, remote-worker schemes. Each with its official source.", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "region": { "type": "string", "description": "Regione", "enum": [ "Abruzzo", "Basilicata", "Calabria", "Campania", "Emilia-Romagna", "Friuli-Venezia Giulia", "Lazio", "Liguria", "Lombardia", "Marche", "Molise", "Piemonte", "Puglia", "Sardegna", "Sicilia", "Toscana", "Trentino-Alto Adige/Südtirol", "Umbria", "Valle d'Aosta/Vallée d'Aoste", "Veneto" ] }, "type": { "type": "string", "description": "Tipo", "enum": [ "case_1_euro", "bonus_residenza", "casa_agevolata", "lavoro_remoto", "altro" ] }, "limit": { "type": "integer", "description": "Risultati", "minimum": 1, "maximum": 100 } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object" } } } } } }, "400": { "description": "Bad input" }, "404": { "description": "Not found" }, "429": { "description": "Rate limit" } } } }, "/api/v1/plan_preview": { "post": { "operationId": "plan_preview", "summary": "Anteprima del piano per ripartire", "description": "Free preview of the secondlife.it personal plan: how many places, remote jobs and incentives fit a person, with the top few of each. No model call.", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "age": { "type": "string", "description": "Fascia di età", "enum": [ "18-25", "26-35", "36-50", "51-65", "65+" ] }, "region_from": { "type": "string", "description": "Regione in cui vive oggi", "enum": [ "Abruzzo", "Basilicata", "Calabria", "Campania", "Emilia-Romagna", "Friuli-Venezia Giulia", "Lazio", "Liguria", "Lombardia", "Marche", "Molise", "Piemonte", "Puglia", "Sardegna", "Sicilia", "Toscana", "Trentino-Alto Adige/Südtirol", "Umbria", "Valle d'Aosta/Vallée d'Aoste", "Veneto" ] }, "region_to": { "type": "string", "description": "Regione dove vorrebbe vivere (vuoto = qualunque)", "enum": [ "Abruzzo", "Basilicata", "Calabria", "Campania", "Emilia-Romagna", "Friuli-Venezia Giulia", "Lazio", "Liguria", "Lombardia", "Marche", "Molise", "Piemonte", "Puglia", "Sardegna", "Sicilia", "Toscana", "Trentino-Alto Adige/Südtirol", "Umbria", "Valle d'Aosta/Vallée d'Aoste", "Veneto" ] }, "move": { "type": "string", "description": "Disponibilità a trasferirsi", "enum": [ "yes", "maybe", "no" ] }, "place_size": { "type": "string", "description": "Dimensione del luogo ideale", "enum": [ "village", "town", "city" ] }, "work": { "type": "string", "description": "Che lavoro cerca", "enum": [ "remote", "local", "own_business", "study" ] }, "skills": { "type": "array", "description": "Aree di competenza", "items": { "type": "string", "enum": [ "software", "design", "marketing", "sales", "support", "finance", "hr", "writing", "education", "health", "management" ] } }, "family": { "type": "string", "description": "Situazione familiare", "enum": [ "single", "couple", "kids" ] }, "house": { "type": "string", "description": "Casa", "enum": [ "rent", "buy", "renovate" ] }, "budget": { "type": "string", "description": "Budget per il trasferimento", "enum": [ "low", "mid", "high" ] }, "english": { "type": "boolean", "description": "Parla inglese a livello lavorativo" }, "female": { "type": "boolean", "description": "Donna (per incentivi all'imprenditoria femminile)" } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object" } } } } } }, "400": { "description": "Bad input" }, "404": { "description": "Not found" }, "429": { "description": "Rate limit" } } } }, "/api/v1/catalogue_trends": { "post": { "operationId": "catalogue_trends", "summary": "Andamento dei bandi nel tempo", "description": "Time series of the Italian incentives catalogue since 2021: calls opened per month, calls open at mid-month, calls closing per month, seasonality (which months are busy), a 6-month estimate with range, and which purposes are growing. Optional region.", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "region": { "type": "string", "description": "Regione", "enum": [ "Abruzzo", "Basilicata", "Calabria", "Campania", "Emilia-Romagna", "Friuli-Venezia Giulia", "Lazio", "Liguria", "Lombardia", "Marche", "Molise", "Piemonte", "Puglia", "Sardegna", "Sicilia", "Toscana", "Trentino-Alto Adige/Südtirol", "Umbria", "Valle d'Aosta/Vallée d'Aoste", "Veneto" ] } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object" } } } } } }, "400": { "description": "Bad input" }, "404": { "description": "Not found" }, "429": { "description": "Rate limit" } } } }, "/api/v1/expected_calls": { "post": { "operationId": "expected_calls", "summary": "Bandi che tornano", "description": "Calls that recur every year (same body, same call, opened in at least two years): past openings, usual month and the expected next opening date, with a confidence level. Use it to tell a user when a closed call should reopen.", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "within_days": { "type": "integer", "description": "Solo quelli attesi entro N giorni", "minimum": 1, "maximum": 400 }, "q": { "type": "string", "description": "Filtra per testo nel titolo o nell'ente" }, "limit": { "type": "integer", "description": "Risultati", "minimum": 1, "maximum": 100 } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object" } } } } } }, "400": { "description": "Bad input" }, "404": { "description": "Not found" }, "429": { "description": "Rate limit" } } } }, "/api/v1/list_products": { "post": { "operationId": "list_products", "summary": "Servizi a pagamento", "description": "Paid services an agent can order for its user (eligibility check, application draft, personal plan, municipality dossier, remote-job kit) and subscriptions.", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": {} } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object" } } } } } }, "400": { "description": "Bad input" }, "404": { "description": "Not found" }, "429": { "description": "Rate limit" } } } }, "/api/v1/create_order": { "post": { "operationId": "create_order", "summary": "Ordina un servizio per l'utente", "description": "Orders a paid report. With an API key that has credit, it is paid at once and generated; otherwise it returns a checkout_url to hand to the human (Stripe), who pays and receives the report by email. Input depends on the product: verifica/bozza need ref (incentive id) and input (business profile + project); piano needs input (questionnaire answers); luogo needs ref (place id); kit needs input.cv, input.role and input.jobs (remote-job ids).", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "product": { "type": "string", "description": "Prodotto", "enum": [ "verifica", "bozza", "piano", "luogo", "kit" ] }, "ref": { "type": "string", "description": "Id della scheda (bando o comune) quando serve" }, "email": { "type": "string", "description": "Email dell'utente che riceverà il report" }, "input": { "type": "object", "description": "Dati per il report (profilo, progetto, risposte, CV)" } }, "required": [ "product", "email" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object" } } } } } }, "400": { "description": "Bad input" }, "404": { "description": "Not found" }, "429": { "description": "Rate limit" } } } }, "/api/v1/get_order": { "post": { "operationId": "get_order", "summary": "Stato e contenuto di un ordine", "description": "Status of an order by its token; when ready, the full report as structured JSON.", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "description": "Token dell'ordine" } }, "required": [ "token" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object" } } } } } }, "400": { "description": "Bad input" }, "404": { "description": "Not found" }, "429": { "description": "Rate limit" } } } } } }