{"openapi":"3.1.0","info":{"title":"Losali Numbers API","version":"1.0.0","summary":"Annuaire public, en lecture seule, des numéros spéciaux français couverts par Losali.","description":"API publique et gratuite exposant l'annuaire des numéros spéciaux français\n(numéros courts 3xxx, numéros 08, services clients) couverts par **Losali**\n(https://losalidirect.com).\n\nPour chaque numéro, l'API renvoie le service rattaché, sa typologie, une\ndescription, et le tarif applicable lors d'un appel **depuis la France**\n(coût par appel et coût par minute, tels que publiés à l'ARCEP/InfoSVA).\n\nCes numéros ne sont pas joignables directement depuis l'étranger ; ils le\nsont uniquement via Losali. Le tarif Losali (facturé à l'appelant depuis\nl'étranger) est distinct du tarif depuis la France et s'affiche dans\nl'application avant chaque appel.\n\nDonnées fournies à titre informatif. Les marques et numéros cités\nappartiennent à leurs détenteurs respectifs.\n","contact":{"name":"Losali","url":"https://losalidirect.com/contact"},"license":{"name":"CC-BY-4.0","identifier":"CC-BY-4.0"},"x-logo":{"url":"https://losalidirect.com/favicon.png","altText":"Losali"}},"servers":[{"url":"https://api.losalidirect.com/v1","description":"Production"}],"externalDocs":{"description":"Documentation de l'API et connecteur MCP","url":"https://api.losalidirect.com/v1/docs"},"tags":[{"name":"numbers","description":"Numéros spéciaux français."},{"name":"brands","description":"Services / entreprises regroupant un ou plusieurs numéros."},{"name":"meta","description":"Découverte et documentation."}],"paths":{"/numbers":{"get":{"operationId":"listNumbers","tags":["numbers"],"summary":"Lister et rechercher des numéros.","parameters":[{"name":"q","in":"query","description":"Recherche plein texte sur le service et la description.","schema":{"type":"string"}},{"name":"type","in":"query","description":"Famille de numéro.","schema":{"type":"string","enum":["numero_court","08","0800","082","089","autre"]}},{"name":"prefix","in":"query","description":"Filtrer par préfixe (ex. \"0892\").","schema":{"type":"string"}},{"name":"page","in":"query","schema":{"type":"integer","minimum":1,"default":1}},{"name":"per_page","in":"query","schema":{"type":"integer","minimum":1,"maximum":200,"default":50}}],"responses":{"200":{"description":"Liste paginée de numéros.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/NumberRecord"}}}}]}}}}}}},"/numbers/{number}":{"get":{"operationId":"getNumber","tags":["numbers"],"summary":"Récupérer un numéro par sa valeur (chiffres uniquement).","parameters":[{"name":"number","in":"path","required":true,"description":"Numéro en chiffres, sans espaces (ex. \"3949\", \"0892685685\").","schema":{"type":"string","pattern":"^[0-9]{4,15}$"}}],"responses":{"200":{"description":"Le numéro demandé.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/NumberRecord"}}}]}}}},"404":{"description":"Numéro inconnu, ou non publié (sans service rattaché, ou numéro mobile 06 / 07).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/brands":{"get":{"operationId":"listBrands","tags":["brands"],"summary":"Lister les services / entreprises.","parameters":[{"name":"q","in":"query","schema":{"type":"string"}},{"name":"page","in":"query","schema":{"type":"integer","minimum":1,"default":1}},{"name":"per_page","in":"query","schema":{"type":"integer","minimum":1,"maximum":200,"default":50}}],"responses":{"200":{"description":"Liste paginée de services.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/BrandRecord"}}}}]}}}}}}},"/brands/{slug}":{"get":{"operationId":"getBrand","tags":["brands"],"summary":"Récupérer un service et ses numéros.","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-z0-9-]+$"}}],"responses":{"200":{"description":"Le service demandé, avec ses numéros.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/BrandRecord"}}}]}}}},"404":{"description":"Service inconnu.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/export.csv":{"get":{"operationId":"exportCsv","tags":["meta"],"summary":"Export CSV complet de l'annuaire (licence CC-BY-4.0).","description":"Tous les numéros publiés de l'annuaire (mêmes règles que /numbers : un\nnuméro sans service rattaché ou un mobile 06 / 07 n'y figure pas),\ngénérés depuis la base et mis en cache quelques heures. Mêmes colonnes\nque le jeu de données publié sur data.gouv.fr ; la colonne\ndate_mise_a_jour reprend meta.data_updated. Une cellule de texte qui\ncommence par = + - ou @ est précédée d'une apostrophe (protection\ncontre l'injection de formules dans un tableur). Limité à 10 requêtes\npar minute et par adresse. L'ancienne adresse\nhttps://losalidirect.com/data/losali-annuaire-numeros-speciaux.csv\nredirige ici (308).\n","responses":{"200":{"description":"Fichier CSV (UTF-8, séparateur virgule, fins de ligne CRLF).","headers":{"X-Data-Updated":{"description":"Date de la dernière vérification des services et des tarifs (comme meta.data_updated).","schema":{"type":"string","format":"date"}},"X-Registry-Checked":{"description":"Date de la dernière vérification des attributions au registre de l'ARCEP (comme meta.registry_checked). Absent tant qu'aucune vérification n'a abouti.","schema":{"type":"string","format":"date"}},"Content-Disposition":{"description":"attachment; filename=\"losali-annuaire-numeros-speciaux.csv\"","schema":{"type":"string"}}},"content":{"text/csv":{"schema":{"type":"string"}}}},"429":{"description":"Trop de requêtes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erreur interne.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/openapi.json":{"get":{"operationId":"getOpenApi","tags":["meta"],"summary":"Spécification OpenAPI de cette API (sert aussi à générer le wrapper MCP).","responses":{"200":{"description":"Document OpenAPI 3.1.","content":{"application/json":{"schema":{"type":"object"}}}}}}}},"components":{"schemas":{"Envelope":{"type":"object","required":["meta"],"properties":{"meta":{"$ref":"#/components/schemas/Meta"}}},"Meta":{"type":"object","description":"Métadonnées d'attribution, de fraîcheur et de pagination, présentes sur chaque réponse.","required":["attribution","license","source","data_updated"],"properties":{"source":{"type":"string","const":"Losali (https://losalidirect.com)"},"attribution":{"type":"string","example":"Source : Losali (losalidirect.com). Données sous licence CC-BY-4.0. Marques détenues par leurs propriétaires respectifs."},"license":{"type":"string","const":"CC-BY-4.0"},"license_url":{"type":"string","format":"uri","const":"https://creativecommons.org/licenses/by/4.0/"},"data_updated":{"type":["string","null"],"format":"date","description":"Date de la dernière vérification des services et des tarifs de l'annuaire.","example":"2026-06-29"},"registry_checked":{"type":["string","null"],"format":"date","description":"Date de la dernière vérification réussie des attributions des numéros au registre de numérotation de l'ARCEP (contrôle hebdomadaire). Ne dit rien des services ni des tarifs. null tant qu'aucune vérification n'a abouti.","example":"2026-10-11"},"source_dataset":{"type":["string","null"],"description":"Provenance des données (source ouverte d'origine).","example":"Dérivé des données publiques de numérotation de l'ARCEP (« Ressources en numérotation téléphonique », data.gouv.fr) et enrichi par Losali."},"page":{"type":"integer","nullable":true},"per_page":{"type":"integer","nullable":true},"total":{"type":"integer","nullable":true}}},"NumberRecord":{"type":"object","required":["number","type","pricing_from_france","reachable_from_abroad","losali","self"],"properties":{"number":{"type":"string","description":"Numéro en chiffres (clé de ressource).","example":"3949"},"type":{"type":"string","enum":["numero_court","08","0800","082","089","autre"],"description":"Famille de numéro, dérivée du format.","example":"numero_court"},"service":{"type":["string","null"],"description":"Nom du service rattaché (colonne `service` de la table `destinations`).","example":"POLE EMPLOI"},"typology":{"type":["string","null"],"description":"Typologie du numéro (colonne `typology`).","example":"Relation Client (Entreprise / Administration / Association / ...)"},"description":{"type":["string","null"],"description":"Description du service (colonne `description`). `null` lorsque la source ne contient qu'un libellé indiquant l'absence de donnée (ex. \"non renseigné\").\n","example":"Ce numéro permet aux demandeurs d'emploi et aux actifs de contacter le service de leur choix"},"pricing_from_france":{"$ref":"#/components/schemas/PricingFromFrance"},"reachable_from_abroad":{"$ref":"#/components/schemas/Reachability"},"losali":{"$ref":"#/components/schemas/LosaliOffer"},"brand_slug":{"type":["string","null"],"description":"Slug du service correspondant, si une fiche existe.","example":"pole-emploi"},"web_url":{"type":["string","null"],"format":"uri","description":"Page Losali correspondante, si elle existe.","example":"https://losalidirect.com/appeler-pole-emploi-de-l-etranger"},"self":{"type":"string","format":"uri","example":"https://api.losalidirect.com/v1/numbers/3949"},"last_verified":{"type":"string","format":"date","example":"2026-06-29"}}},"PricingFromFrance":{"type":"object","description":"Tarif applicable lors d'un appel DEPUIS LA FRANCE (source ARCEP/InfoSVA). Ce n'est PAS le prix facturé par Losali, qui est distinct et affiché dans l'application avant l'appel.\n","required":["cost_per_call_eur","cost_per_minute_eur","currency","note"],"properties":{"cost_per_call_eur":{"type":["number","null"],"description":"Coût par appel depuis la France (colonne `cost_per_call`). `null` si inconnu.","example":0},"cost_per_minute_eur":{"type":["number","null"],"description":"Coût par minute depuis la France (colonne `cost_per_min`). `null` si inconnu.","example":0},"currency":{"type":"string","const":"EUR"},"note":{"type":"string","const":"Tarif depuis la France. Le prix Losali, distinct, s'affiche avant l'appel."}}},"Reachability":{"type":"object","description":"Joignabilité du numéro depuis l'étranger.","required":["directly","via_losali","note"],"properties":{"directly":{"type":"boolean","const":false,"description":"Jamais joignable directement depuis l'étranger."},"via_losali":{"type":"boolean","const":true,"description":"Joignable via Losali (appel WebRTC dans le navigateur)."},"note":{"type":"string","const":"Non joignable directement depuis l'étranger ; uniquement via Losali (https://losalidirect.com)."}}},"LosaliOffer":{"type":"object","description":"Joignabilité et offre Losali pour ce numéro.","required":["callable","free_first_call_eligible","note"],"properties":{"callable":{"type":"boolean","const":true},"free_first_call_eligible":{"type":"boolean","description":"Vrai pour les numéros à coût opérateur nul (cost/min ET cost/appel à zéro), hors numéros surtaxés (081/082/089). Ces numéros sont éligibles à l'offre « 1er appel gratuit » de Losali (nouveaux utilisateurs, durée plafonnée, selon l'offre en cours) ; les appels normaux sont facturés au tarif Losali affiché avant l'appel. Inclut les numéros courts gratuits (ex. 3949) et les numéros verts (0800).\n","example":true},"note":{"type":"string","example":"Coût opérateur nul : éligible à l'offre « 1er appel gratuit » de Losali (nouveaux utilisateurs, durée plafonnée, selon l'offre en cours). Hors offre, tarif Losali affiché avant l'appel."},"price":{"oneOf":[{"$ref":"#/components/schemas/LosaliPrice"},{"type":"null"}],"description":"Prix Losali standard de ce numéro, calculé comme au lancement d'un appel. null quand le numéro n'a pas encore de prix publié ; le prix s'affiche alors avant l'appel.\n"}}},"LosaliPrice":{"type":"object","required":["per_minute_eur","per_call_eur","currency","note"],"properties":{"per_minute_eur":{"type":"number","example":0.99},"per_call_eur":{"type":"number","description":"Frais par appel établi, 0 pour la plupart des numéros.","example":0},"currency":{"type":"string","const":"EUR"},"note":{"type":"string","example":"Tarif Losali standard, décompté du crédit prépayé et affiché avant l'appel. C'est le prix total de l'appel : la surtaxe française du numéro n'y est pas ajoutée."}}},"BrandRecord":{"type":"object","required":["slug","name","self"],"properties":{"slug":{"type":"string","example":"pole-emploi"},"name":{"type":"string","example":"France Travail (ex-Pôle Emploi)"},"aliases":{"type":"array","items":{"type":"string"},"example":["Pôle Emploi","France Travail"]},"numbers":{"type":"array","description":"Numéros rattachés à ce service.","items":{"$ref":"#/components/schemas/NumberRecord"}},"web_url":{"type":["string","null"],"format":"uri","example":"https://losalidirect.com/appeler-pole-emploi-de-l-etranger"},"self":{"type":"string","format":"uri","example":"https://api.losalidirect.com/v1/brands/pole-emploi"}}},"Error":{"type":"object","required":["meta","error"],"properties":{"meta":{"$ref":"#/components/schemas/Meta"},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","example":"not_found"},"message":{"type":"string","example":"Aucun numéro ne correspond à 9999."}}}}}}}}